By area

Contacts

Read from the API’s own reference file every hour.

Your contacts: the fields they carry, the list, create or update in batches, delete, and find by phone number.

List contact fields

GET/v1/contacts/fields

The fields your contacts carry, in display order. A field's name is the key in every contact's fields, and the name to use when you create or update contacts.

is_match fields find an existing contact on create. is_phone fields hold phone numbers: we keep digits only, and several numbers are separated by ;. A field tied to one of your integrations carries integration.

Request

curl https://api.vocatech.com/v1/contacts/fields \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.vocatech.com/v1/contacts/fields", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(res.status, await res.json());

import requests

r = requests.get(
    "https://api.vocatech.com/v1/contacts/fields",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->get('/v1/contacts/fields');

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Answers

200

Your contact fields.

Field	Type	Description
`fields` required	array of objects
`fields[].id` required	integer
`fields[].name` required	string	The field's name: the key in every contact's `fields`.
`fields[].order` required	integer	Display order.
`fields[].is_phone` required	boolean	Holds phone numbers. We keep digits only; several numbers are separated by `;`.
`fields[].is_match` required	boolean	Used to find an existing contact on create. A contact whose match fields all equal yours is updated instead.
`fields[].reports_enabled` required	boolean	A display setting from the portal.
`fields[].hide_no_data` required	boolean	A display setting from the portal.
`fields[].show_in_fields` required	boolean	A display setting from the portal.
`fields[].is_integration` required	boolean	True when the field is tied to one of your integrations.
`fields[].integration`	object	Present only on integration fields: the integration's settings, as set in the portal.
`fields[].integration.id`	integer
`fields[].integration.initials`	string
`fields[].integration.image_url`	string
`fields[].integration.fields`	array of objects
`fields[].integration.fields[].key`	string
`fields[].integration.fields[].display_name`	string
`fields[].integration.fields[].value`	string
`fields[].integration.fields[].fills`	array, each any	Integration settings, as set in the portal.

Example

{
  "fields": [
    {
      "id": 31,
      "name": "First Name",
      "order": 1,
      "is_phone": false,
      "is_match": false,
      "reports_enabled": true,
      "hide_no_data": false,
      "show_in_fields": true,
      "is_integration": false
    },
    {
      "id": 32,
      "name": "Last Name",
      "order": 2,
      "is_phone": false,
      "is_match": false,
      "reports_enabled": true,
      "hide_no_data": false,
      "show_in_fields": true,
      "is_integration": false
    },
    {
      "id": 33,
      "name": "Phone",
      "order": 3,
      "is_phone": true,
      "is_match": true,
      "reports_enabled": true,
      "hide_no_data": false,
      "show_in_fields": true,
      "is_integration": false
    },
    {
      "id": 34,
      "name": "Email",
      "order": 4,
      "is_phone": false,
      "is_match": false,
      "reports_enabled": false,
      "hide_no_data": true,
      "show_in_fields": true,
      "is_integration": false
    },
    {
      "id": 35,
      "name": "Account Number",
      "order": 5,
      "is_phone": false,
      "is_match": true,
      "reports_enabled": false,
      "hide_no_data": true,
      "show_in_fields": true,
      "is_integration": false
    }
  ]
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

List contacts

GET/v1/contacts

Your contacts, oldest first. search finds contacts where any field contains the text.

Request

curl -G https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

const params = new URLSearchParams({
  page: "1",
  limit: "100",
});

const res = await fetch(`https://api.vocatech.com/v1/contacts?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(res.status, await res.json());

import requests

r = requests.get(
    "https://api.vocatech.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "page": 1,
        "limit": 100,
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->get('/v1/contacts', [
    'query' => [
        'page' => 1,
        'limit' => 100,
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Parameters

Name	In	Type	Description
`page`	query	integer	Page number, from 1. Default `1`. At least 1.
`limit`	query	integer	Contacts per page, 1 to 500. A value outside that range is brought inside it. Default `100`. From 1 to 500.
`search`	query	string	Text to find in any field. For example `Reyes`.

Answers

200

A page of contacts.

Field	Type	Description
`query` required	object
`query.page` required	integer
`query.limit` required	integer
`query.search` required	string or null
`contacts` required	array of objects
`contacts[].id` required	integer	The contact's id.
`contacts[].fields` required	object	Field name to value. The names are your contact fields (`GET /v1/contacts/fields`). Phone fields hold digits; several numbers are separated by `;`.
`contacts[].fields.{field}`	string or null	One value for each field, by its name.
`meta` required	object	Paging for list routes. Each list adds its own total.
`meta.page` required	integer	This page, from 1.
`meta.limit` required	integer	Rows per page, after limits were applied.
`meta.total_pages` required	integer	How many pages there are.
`meta.total_contacts` required	integer	Contacts that match. `total_pages` is 0 when there are none.

Example

{
  "query": {
    "page": 1,
    "limit": 100,
    "search": null
  },
  "contacts": [
    {
      "id": 5012,
      "fields": {
        "First Name": "Jordan",
        "Last Name": "Reyes",
        "Phone": "7185550142",
        "Email": "jordan.reyes@example.com",
        "Account Number": "A-2291"
      }
    },
    {
      "id": 5013,
      "fields": {
        "First Name": "Sam",
        "Last Name": "Patel",
        "Phone": "7185550143;9175550123",
        "Email": "sam.patel@example.com",
        "Account Number": "A-2310"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 100,
    "total_pages": 1,
    "total_contacts": 2
  }
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Create or update contacts

POST/v1/contacts

Creates a contact, or updates the one that matches. Send one contact as {"fields": {...}}, or up to 500 as {"contacts": [{"fields": {...}}]}.

fields maps field names (from GET /v1/contacts/fields) to values. Names we do not know are ignored. Values over 255 characters are cut. Phone fields keep digits only; separate several numbers with ;.

Matching. When your account has match fields (is_match: true), a contact whose match fields all equal yours is updated instead of created. With no match fields, every contact is created new.

One contact answers 201 when created and 200 when updated. A batch always answers 200. One bad entry does not stop the rest: errors lists each one by its index in your array.

Request

curl -X POST https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "First Name": "Jordan",
      "Last Name": "Reyes",
      "Phone": "(718) 555-0142",
      "Email": "jordan.reyes@example.com",
      "Account Number": "A-2291"
    }
  }'

const res = await fetch("https://api.vocatech.com/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: {
      "First Name": "Jordan",
      "Last Name": "Reyes",
      Phone: "(718) 555-0142",
      Email: "jordan.reyes@example.com",
      "Account Number": "A-2291",
    },
  }),
});

console.log(res.status, await res.json());

import requests

r = requests.post(
    "https://api.vocatech.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "fields": {
            "First Name": "Jordan",
            "Last Name": "Reyes",
            "Phone": "(718) 555-0142",
            "Email": "jordan.reyes@example.com",
            "Account Number": "A-2291",
        },
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->post('/v1/contacts', [
    'json' => [
        'fields' => [
            'First Name' => 'Jordan',
            'Last Name' => 'Reyes',
            'Phone' => '(718) 555-0142',
            'Email' => 'jordan.reyes@example.com',
            'Account Number' => 'A-2291',
        ],
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Body

One contact

Field	Type	Description
`fields` required	object	Field name to value. Names come from `GET /v1/contacts/fields`; unknown names are ignored. Values over 255 characters are cut. At least 1 field.
`fields.{field}`	string or null	One value for each field, by its name.

A batch

Field	Type	Description
`contacts` required	array of objects	Up to 500 items.
`contacts[].fields` required	object	Field name to value. Names come from `GET /v1/contacts/fields`; unknown names are ignored. Values over 255 characters are cut. At least 1 field.
`contacts[].fields.{field}`	string or null	One value for each field, by its name.

One contact

{
  "fields": {
    "First Name": "Jordan",
    "Last Name": "Reyes",
    "Phone": "(718) 555-0142",
    "Email": "jordan.reyes@example.com",
    "Account Number": "A-2291"
  }
}

A batch

{
  "contacts": [
    {
      "fields": {
        "First Name": "Jordan",
        "Last Name": "Reyes",
        "Phone": "7185550142",
        "Account Number": "A-2291"
      }
    },
    {
      "fields": {
        "First Name": "Sam",
        "Last Name": "Patel",
        "Phone": "7185550143;9175550123",
        "Account Number": "A-2310"
      }
    }
  ]
}

Answers

200

One contact was updated, or a batch was processed.

Field	Type	Description
`summary` required	object
`summary.total` required	integer
`summary.created` required	integer
`summary.updated` required	integer
`summary.errors` required	integer
`contacts` required	array of objects
`contacts[].contact` required	object
`contacts[].contact.id` required	integer	The contact's id.
`contacts[].contact.fields` required	object	Field name to value. The names are your contact fields (`GET /v1/contacts/fields`). Phone fields hold digits; several numbers are separated by `;`.
`contacts[].contact.fields.{field}`	string or null	One value for each field, by its name.
`contacts[].action` required	string	One of `created` or `updated`.
`errors` required	array of objects
`errors[].index` required	integer	The entry's position in your `contacts` array, from 0.
`errors[].message` required	string

Example

{
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 1,
    "errors": 0
  },
  "contacts": [
    {
      "contact": {
        "id": 5012,
        "fields": {
          "First Name": "Jordan",
          "Last Name": "Reyes",
          "Phone": "7185550142",
          "Email": "jordan.reyes@example.com",
          "Account Number": "A-2291"
        }
      },
      "action": "updated"
    },
    {
      "contact": {
        "id": 5013,
        "fields": {
          "First Name": "Sam",
          "Last Name": "Patel",
          "Phone": "7185550143;9175550123",
          "Email": "sam.patel@example.com",
          "Account Number": "A-2310"
        }
      },
      "action": "created"
    }
  ],
  "errors": []
}

201

One contact was created.

Field	Type	Description
`summary` required	object
`summary.total` required	integer
`summary.created` required	integer
`summary.updated` required	integer
`summary.errors` required	integer
`contacts` required	array of objects
`contacts[].contact` required	object
`contacts[].contact.id` required	integer	The contact's id.
`contacts[].contact.fields` required	object	Field name to value. The names are your contact fields (`GET /v1/contacts/fields`). Phone fields hold digits; several numbers are separated by `;`.
`contacts[].contact.fields.{field}`	string or null	One value for each field, by its name.
`contacts[].action` required	string	One of `created` or `updated`.
`errors` required	array of objects
`errors[].index` required	integer	The entry's position in your `contacts` array, from 0.
`errors[].message` required	string

Example

{
  "summary": {
    "total": 1,
    "created": 1,
    "updated": 0,
    "errors": 0
  },
  "contacts": [
    {
      "contact": {
        "id": 5012,
        "fields": {
          "First Name": "Jordan",
          "Last Name": "Reyes",
          "Phone": "7185550142",
          "Email": "jordan.reyes@example.com",
          "Account Number": "A-2291"
        }
      },
      "action": "created"
    }
  ],
  "errors": []
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

422

No fields object, or a batch over 500.

Example bodies

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "Missing or invalid \"fields\" object."
  }
}

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "Batch size cannot exceed 500 contacts."
  }
}

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Delete contacts

DELETE/v1/contacts

Deletes one contact ({"id": 5012}) or up to 500 ({"ids": [5012, 5013]}). The ids go in a JSON body.

One contact that is not yours or does not exist answers 404. In a batch it is listed in errors, and the rest are deleted.

Request

curl -X DELETE https://api.vocatech.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 5012
  }'

const res = await fetch("https://api.vocatech.com/v1/contacts", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: 5012,
  }),
});

console.log(res.status, await res.json());

import requests

r = requests.delete(
    "https://api.vocatech.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "id": 5012,
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->delete('/v1/contacts', [
    'json' => [
        'id' => 5012,
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Body

One contact

Field	Type	Description
`id` required	integer

A batch

Field	Type	Description
`ids` required	array of integers	Up to 500 items.

One contact

{
  "id": 5012
}

A batch

{
  "ids": [
    5012,
    5013,
    5099
  ]
}

Answers

200

Deleted.

One contact

Field	Type	Description
`deleted` required	integer	The id that was deleted.

A batch

Field	Type	Description
`summary` required	object
`summary.total` required	integer
`summary.deleted` required	integer
`summary.errors` required	integer
`deleted` required	array of integers	The ids that were deleted.
`errors` required	array of objects	Ids not found on your account.
`errors[].id` required	integer
`errors[].message` required	string

One contact

{
  "deleted": 5012
}

A batch

{
  "summary": {
    "total": 3,
    "deleted": 2,
    "errors": 1
  },
  "deleted": [
    5012,
    5013
  ],
  "errors": [
    {
      "id": 5099,
      "message": "The contact you requested does not exist."
    }
  ]
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

404

One contact: not found on your account.

Example body

Example

{
  "error": {
    "code": 404,
    "type": "NOT_FOUND",
    "message": "The contact you requested does not exist."
  }
}

422

No id, or a batch over 500.

Example bodies

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "Missing \"id\" field."
  }
}

Example

{
  "error": {
    "code": 422,
    "type": "UNPROCESSABLE_ENTITY",
    "message": "Batch size cannot exceed 500 IDs."
  }
}

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Find contacts by phone number

GET/v1/contacts/lookup

The contacts a phone number belongs to, up to 10, through the same phone index Callpop uses. Any format works on either side: (718) 555-0142, +17185550142 and 7185550142 find the same contact.

Keys with the agents scope can call this route.

Request

curl -G https://api.vocatech.com/v1/contacts/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "phone=7185550142"

const params = new URLSearchParams({
  phone: "7185550142",
});

const res = await fetch(`https://api.vocatech.com/v1/contacts/lookup?${params}`, {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(res.status, await res.json());

import requests

r = requests.get(
    "https://api.vocatech.com/v1/contacts/lookup",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "phone": "7185550142",
    },
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->get('/v1/contacts/lookup', [
    'query' => [
        'phone' => '7185550142',
    ],
]);

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Parameters

Name	In	Type	Description
`phone` required	query	string	The phone number, any format, at least 7 digits. For example `7185550142`.

Answers

200

The contacts with that number. found is false when there are none.

Field	Type	Description
`phone` required	string	The number you asked about, digits only, without a leading 1.
`found` required	boolean
`contacts` required	array of objects	Up to 10. Up to 10 items.
`contacts[].id` required	integer	The contact's id.
`contacts[].fields` required	object	Field name to value. The names are your contact fields (`GET /v1/contacts/fields`). Phone fields hold digits; several numbers are separated by `;`.
`contacts[].fields.{field}`	string or null	One value for each field, by its name.

Example

{
  "phone": "7185550142",
  "found": true,
  "contacts": [
    {
      "id": 5012,
      "fields": {
        "First Name": "Jordan",
        "Last Name": "Reyes",
        "Phone": "7185550142",
        "Email": "jordan.reyes@example.com",
        "Account Number": "A-2291"
      }
    }
  ]
}

400

No phone, or fewer than 7 digits.

Example body

Example

{
  "error": {
    "code": 400,
    "type": "BAD_REQUEST",
    "message": "phone is required and must contain at least 7 digits."
  }
}

401

No key, or a key that is wrong or turned off.

403

Refused. The key is scoped away from this route, the request came from an address not on the key's allow-list, or the route refused the request (the message says why).

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Before thisCallers Next AI agents