Vocatech

Recipes

Sync contacts

Written beside the API’s code, and read from it every hour.

Plain text

Keep the contacts that pop up on calls in step with your own system.

  1. GET /v1/contacts/fields returns your field names. Fields with is_match decide which contact a row updates. Fields with is_phone hold numbers.
  2. POST /v1/contacts takes up to 500 contacts per request. A row updates the contact whose match fields all equal it, or creates a new one.
  3. DELETE /v1/contacts removes the ids you deleted on your side, up to 500 per request.
# 1. Your field names
curl https://api.vocatech.com/v1/contacts/fields \
  -H "Authorization: Bearer $VOCATECH_API_KEY"

# 2. Create or update, up to 500 per request
curl -X POST https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "fields": { "Name": "Jordan Reyes", "Phone": "7185550142", "Account": "A-1042" } },
      { "fields": { "Name": "Riley Morgan", "Phone": "7185550143;7185550144", "Account": "A-1043" } }
    ]
  }'

# 3. Delete, up to 500 ids per request
curl -X DELETE https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer $VOCATECH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [5031, 5032] }'
POST /v1/contacts response200 OK
{
  "summary": { "total": 2, "created": 1, "updated": 1, "errors": 0 },
  "contacts": [
    {
      "contact": { "id": 5012, "fields": { "Name": "Jordan Reyes", "Phone": "7185550142", "Account": "A-1042" } },
      "action": "updated"
    },
    {
      "contact": { "id": 5033, "fields": { "Name": "Riley Morgan", "Phone": "7185550143;7185550144", "Account": "A-1043" } },
      "action": "created"
    }
  ],
  "errors": []
}
  • Use the field names exactly as GET /v1/contacts/fields returns them. Unknown names are ignored.
  • Phone fields keep digits only and drop a leading 1. Put several numbers in one field with semicolons: 7185550143;7185550144.
  • Values over 255 characters are cut.
  • A batch answers 200 with a summary, and one entry in errors for each row that failed, by its index in your batch. A single contact sent as {"fields": {...}} answers 201 when created and 200 when updated.