By area

Callers

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

Everything your account knows about one phone number, in one answer. Built for an AI agent or a screen pop that needs context before it answers.

Look up a caller

GET/v1/callers/{number}

Everything your account knows about one phone number: the contacts it belongs to (up to 5), recent calls with who handled them and the AI summary, recent texts and WhatsApp messages, and the last call each way. Built for an AI agent or a screen pop that needs context before it answers.

number can be written any way: punctuation and a leading 1 are ignored. It needs at least 7 digits.

Calls and messages look back days days and return up to limit of each, newest first. Transcripts are left out unless include asks for them; each is cut at 6,000 characters. Message text is cut at 400 characters. A cut ends in [cut].

Keys with the agents scope can call this route. Each request is written to your account's HIPAA access log.

Request

curl -G https://api.vocatech.com/v1/callers/7185550142 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "days=90" \
  --data-urlencode "limit=10"

const params = new URLSearchParams({
  days: "90",
  limit: "10",
});

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

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

import requests

r = requests.get(
    "https://api.vocatech.com/v1/callers/7185550142",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "days": 90,
        "limit": 10,
    },
    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/callers/7185550142', [
    'query' => [
        'days' => 90,
        'limit' => 10,
    ],
]);

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

Parameters

Name	In	Type	Description
`number` required	path	string	The phone number, any format, at least 7 digits. For example `7185550142`.
`days`	query	integer	How far back to look, 1 to 365. A value outside that range is brought inside it. Default `90`. From 1 to 365.
`limit`	query	integer	Most calls, and most messages, to return: 1 to 50. A value outside that range is brought inside it. Default `10`. From 1 to 50.
`include`	query	string	What to include, separated by commas: `contacts`, `calls`, `messages`, `transcripts`. `transcripts` brings the calls with it. Unknown words are ignored. Default `contacts,calls,messages`. For example `contacts,calls,messages,transcripts`.

Answers

200

What we know about the number.

Field	Type	Description
`number` required	string	The number you asked about, digits only, without a leading 1.
`days` required	integer	How many days back the calls and messages go.
`contacts` required	array of objects	Contacts with this number, up to 5. Up to 5 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.
`calls` required	array of objects	Newest first.
`calls[].call_id` required	string
`calls[].direction` required	string	`incoming` or `outgoing`.
`calls[].status` required	string	The first leg's status, as in `GET /v1/calls`.
`calls[].start_time` required	string (date-time) or null
`calls[].end_time` required	string (date-time) or null
`calls[].duration` required	integer	Seconds.
`calls[].remote_name` required	string
`calls[].remote_number` required	string
`calls[].our_number` required	string	Your number on the call.
`calls[].handled_by` required	object or null	The person on your side: the last extension that held an incoming call, or the one that placed an outgoing call.
`calls[].handled_by.extension` required	string
`calls[].handled_by.name` required	string
`calls[].summary` required	string or null	The first AI summary on the call.
`calls[].journey` required	array of objects
`calls[].journey[].order` required	integer
`calls[].journey[].type` required	string
`calls[].journey[].extension` required	string or null
`calls[].journey[].extension_name` required	string or null
`calls[].journey[].start_time` required	string (date-time) or null
`calls[].journey[].duration` required	integer	Seconds.
`calls[].journey[].summary` required	string or null	The AI summary of this leg, when recorded.
`calls[].journey[].transcription`	string or null	Only with `include=transcripts`. Cut at 6,000 characters, ending in `[cut]`.
`messages` required	array of objects	Newest first.
`messages[].channel` required	string	One of `text` or `whatsapp`.
`messages[].direction` required	string	`incoming` or `outgoing`.
`messages[].body` required	string	Cut at 400 characters, ending in `[cut]`.
`messages[].sent_time` required	string	UTC, ISO 8601 without milliseconds.
`messages[].our_number` required	string
`messages[].remote_number` required	string
`last_call` required	object or null	The newest call either way.
`last_call.call_id` required	string
`last_call.direction` required	string	`incoming` or `outgoing`.
`last_call.status` required	string	The first leg's status, as in `GET /v1/calls`.
`last_call.start_time` required	string (date-time) or null
`last_call.end_time` required	string (date-time) or null
`last_call.duration` required	integer	Seconds.
`last_call.remote_name` required	string
`last_call.remote_number` required	string
`last_call.our_number` required	string	Your number on the call.
`last_call.handled_by` required	object or null	The person on your side: the last extension that held an incoming call, or the one that placed an outgoing call.
`last_call.handled_by.extension` required	string
`last_call.handled_by.name` required	string
`last_call.summary` required	string or null	The first AI summary on the call.
`last_call.journey` required	array of objects
`last_call.journey[].order` required	integer
`last_call.journey[].type` required	string
`last_call.journey[].extension` required	string or null
`last_call.journey[].extension_name` required	string or null
`last_call.journey[].start_time` required	string (date-time) or null
`last_call.journey[].duration` required	integer	Seconds.
`last_call.journey[].summary` required	string or null	The AI summary of this leg, when recorded.
`last_call.journey[].transcription`	string or null	Only with `include=transcripts`. Cut at 6,000 characters, ending in `[cut]`.
`last_incoming` required	object or null	The newest incoming call.
`last_incoming.call_id` required	string
`last_incoming.direction` required	string	`incoming` or `outgoing`.
`last_incoming.status` required	string	The first leg's status, as in `GET /v1/calls`.
`last_incoming.start_time` required	string (date-time) or null
`last_incoming.end_time` required	string (date-time) or null
`last_incoming.duration` required	integer	Seconds.
`last_incoming.remote_name` required	string
`last_incoming.remote_number` required	string
`last_incoming.our_number` required	string	Your number on the call.
`last_incoming.handled_by` required	object or null	The person on your side: the last extension that held an incoming call, or the one that placed an outgoing call.
`last_incoming.handled_by.extension` required	string
`last_incoming.handled_by.name` required	string
`last_incoming.summary` required	string or null	The first AI summary on the call.
`last_incoming.journey` required	array of objects
`last_incoming.journey[].order` required	integer
`last_incoming.journey[].type` required	string
`last_incoming.journey[].extension` required	string or null
`last_incoming.journey[].extension_name` required	string or null
`last_incoming.journey[].start_time` required	string (date-time) or null
`last_incoming.journey[].duration` required	integer	Seconds.
`last_incoming.journey[].summary` required	string or null	The AI summary of this leg, when recorded.
`last_incoming.journey[].transcription`	string or null	Only with `include=transcripts`. Cut at 6,000 characters, ending in `[cut]`.
`last_outgoing` required	object or null	The newest outgoing call.
`last_outgoing.call_id` required	string
`last_outgoing.direction` required	string	`incoming` or `outgoing`.
`last_outgoing.status` required	string	The first leg's status, as in `GET /v1/calls`.
`last_outgoing.start_time` required	string (date-time) or null
`last_outgoing.end_time` required	string (date-time) or null
`last_outgoing.duration` required	integer	Seconds.
`last_outgoing.remote_name` required	string
`last_outgoing.remote_number` required	string
`last_outgoing.our_number` required	string	Your number on the call.
`last_outgoing.handled_by` required	object or null	The person on your side: the last extension that held an incoming call, or the one that placed an outgoing call.
`last_outgoing.handled_by.extension` required	string
`last_outgoing.handled_by.name` required	string
`last_outgoing.summary` required	string or null	The first AI summary on the call.
`last_outgoing.journey` required	array of objects
`last_outgoing.journey[].order` required	integer
`last_outgoing.journey[].type` required	string
`last_outgoing.journey[].extension` required	string or null
`last_outgoing.journey[].extension_name` required	string or null
`last_outgoing.journey[].start_time` required	string (date-time) or null
`last_outgoing.journey[].duration` required	integer	Seconds.
`last_outgoing.journey[].summary` required	string or null	The AI summary of this leg, when recorded.
`last_outgoing.journey[].transcription`	string or null	Only with `include=transcripts`. Cut at 6,000 characters, ending in `[cut]`.
`counts` required	object
`counts.contacts` required	integer
`counts.calls` required	integer
`counts.messages` required	integer

Example

{
  "number": "7185550142",
  "days": 90,
  "contacts": [
    {
      "id": 5012,
      "fields": {
        "First Name": "Jordan",
        "Last Name": "Reyes",
        "Phone": "7185550142",
        "Email": "jordan.reyes@example.com",
        "Account Number": "A-2291"
      }
    }
  ],
  "calls": [
    {
      "call_id": "8a1f3c2e-5b7d-4e9a-9c1b-2d4e6f8a0b1c",
      "direction": "incoming",
      "status": "answered",
      "start_time": "2026-09-21T14:03:12.000Z",
      "end_time": "2026-09-21T14:09:40.000Z",
      "duration": 388,
      "remote_name": "Jordan Reyes",
      "remote_number": "7185550142",
      "our_number": "7185550100",
      "handled_by": {
        "extension": "104",
        "name": "Maya Chen"
      },
      "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow.",
      "journey": [
        {
          "order": 1,
          "type": "auto_attendant",
          "extension": "100",
          "extension_name": "Main Menu",
          "start_time": "2026-09-21T14:03:12.000Z",
          "duration": 19,
          "summary": null
        },
        {
          "order": 2,
          "type": "user",
          "extension": "104",
          "extension_name": "Maya Chen",
          "start_time": "2026-09-21T14:03:31.000Z",
          "duration": 369,
          "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow."
        }
      ]
    }
  ],
  "messages": [
    {
      "channel": "text",
      "direction": "incoming",
      "body": "Running 10 minutes late, see you soon.",
      "sent_time": "2026-09-21T15:22:04Z",
      "our_number": "7185550100",
      "remote_number": "7185550142"
    }
  ],
  "last_call": {
    "call_id": "8a1f3c2e-5b7d-4e9a-9c1b-2d4e6f8a0b1c",
    "direction": "incoming",
    "status": "answered",
    "start_time": "2026-09-21T14:03:12.000Z",
    "end_time": "2026-09-21T14:09:40.000Z",
    "duration": 388,
    "remote_name": "Jordan Reyes",
    "remote_number": "7185550142",
    "our_number": "7185550100",
    "handled_by": {
      "extension": "104",
      "name": "Maya Chen"
    },
    "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow.",
    "journey": [
      {
        "order": 1,
        "type": "auto_attendant",
        "extension": "100",
        "extension_name": "Main Menu",
        "start_time": "2026-09-21T14:03:12.000Z",
        "duration": 19,
        "summary": null
      },
      {
        "order": 2,
        "type": "user",
        "extension": "104",
        "extension_name": "Maya Chen",
        "start_time": "2026-09-21T14:03:31.000Z",
        "duration": 369,
        "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow."
      }
    ]
  },
  "last_incoming": {
    "call_id": "8a1f3c2e-5b7d-4e9a-9c1b-2d4e6f8a0b1c",
    "direction": "incoming",
    "status": "answered",
    "start_time": "2026-09-21T14:03:12.000Z",
    "end_time": "2026-09-21T14:09:40.000Z",
    "duration": 388,
    "remote_name": "Jordan Reyes",
    "remote_number": "7185550142",
    "our_number": "7185550100",
    "handled_by": {
      "extension": "104",
      "name": "Maya Chen"
    },
    "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow.",
    "journey": [
      {
        "order": 1,
        "type": "auto_attendant",
        "extension": "100",
        "extension_name": "Main Menu",
        "start_time": "2026-09-21T14:03:12.000Z",
        "duration": 19,
        "summary": null
      },
      {
        "order": 2,
        "type": "user",
        "extension": "104",
        "extension_name": "Maya Chen",
        "start_time": "2026-09-21T14:03:31.000Z",
        "duration": 369,
        "summary": "Jordan Reyes asked to move the Thursday appointment to Friday at 10 AM. Maya Chen confirmed the new time and said a reminder text will follow."
      }
    ]
  },
  "last_outgoing": null,
  "counts": {
    "contacts": 1,
    "calls": 1,
    "messages": 1
  }
}

400

Fewer than 7 digits.

Example body

Example

{
  "error": {
    "code": 400,
    "type": "BAD_REQUEST",
    "message": "number 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 thisMedia Next Contacts