Caller context

When the phone rings, knowing who's calling turns a cold call into a warm one. The Caller context endpoint takes a phone number, queries every integration you've connected to your Phone.inc account, and returns matching data in a generic, structured format.

Today we support Shopify and Custom Endpoint integrations. The response shape is the same across all providers — your app renders it once, and new integrations work automatically.

The caller context model

The endpoint returns an array of contexts — one per provider that found a match. Each context contains sections — either key-value fields or tables — with optional format hints so your UI can render money, dates, and badges appropriately.

Top-level properties

Name
contexts
Type
array
Description
One entry per provider that matched the phone number. Empty if no integration recognized the caller.
Name
enriched_at
Type
timestamp
Description
ISO 8601 timestamp of when the lookup was performed. null if no providers were queried.
Name
contact
Type
object | null
Description
The matching Phone.inc contact, if one exists for this number.

Context entry

Name
provider
Type
string
Description
Machine-readable identifier for the source system, e.g. shopify, custom_endpoint.
Name
label
Type
string
Description
Human-readable name shown in the UI, e.g. Shopify, Internal CRM.
Name
source
Type
string
Description
The store, workspace, or account identifier, e.g. acme.myshopify.com.
Name
url
Type
string | null
Description
Deep link to the matched record in the provider's admin UI.
Name
sections
Type
array
Description
Array of section objects. Each section is either a fields section or a table section.

Fields section

Name
type
Type
string
Description
Always "fields".
Name
label
Type
string
Description
Optional heading above the field list.
Name
fields
Type
array
Description
Array of field objects with label, value, optional format, url, and bold.

Table section

Name
type
Type
string
Description
Always "table".
Name
label
Type
string
Description
Required heading above the table.
Name
columns
Type
array
Description
Column definitions with key, label, and optional format.
Name
rows
Type
array
Description
Row objects with url (optional link for the row) and values (a map of column key to value).

Format hints

Values can include a format hint to control rendering:

Format	Value shape	Rendering
`text`	String (default)	Rendered as-is
`money`	`{ "amount": "89", "currency": "DKK" }`	Locale-formatted with currency symbol
`date`	ISO 8601 string	Relative or absolute date
`email`	String	Clickable mailto link
`phone`	String (E.164)	Tap-to-call on mobile
`badge`	String	Colored status pill

To make any value clickable, use the field-level url property instead of a format hint.

GET/v1/caller_context

Look up a caller

Query every connected integration for the given phone number and return the matched data. Designed to be called the moment an inbound call rings — the response is fast enough to surface customer context before the employee picks up.

Pass the caller's phone number in E.164 format. Other formats are accepted on a best-effort basis, but E.164 produces the most reliable matches.

If no integration is connected, or none recognizes the number, you'll get an empty contexts array — that's the success path, not an error.

Required query parameters

Name
phone
Type
string
Description
The caller's phone number, ideally in E.164 (e.g. +14155551234). Required — calling the endpoint without it returns 400.

Request

GET

/v1/caller_context

curl -G https://app.phone.inc/api/v1/caller_context \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  --data-urlencode phone=+14085550199

Response

{
  "contexts": [
    {
      "provider": "shopify",
      "label": "Shopify",
      "source": "acme-store.myshopify.com",
      "url": "https://acme-store.myshopify.com/admin/customers/8123456789",
      "sections": [
        {
          "type": "fields",
          "fields": [
            { "label": "Customer", "value": "Jamie Rivera", "url": "https://acme-store.myshopify.com/admin/customers/8123456789" },
            { "label": "Email", "value": "[email protected]", "format": "email" },
            { "label": "Phone", "value": "+14085550199", "format": "phone" }
          ]
        },
        {
          "type": "table",
          "label": "Orders",
          "columns": [
            { "key": "name", "label": "Order" },
            { "key": "date", "label": "Date", "format": "date" },
            { "key": "total", "label": "Total", "format": "money" },
            { "key": "status", "label": "Status", "format": "badge" }
          ],
          "rows": [
            {
              "url": "https://acme-store.myshopify.com/admin/orders/4112233445",
              "values": {
                "name": "#1042",
                "date": "2026-05-09T22:14:01Z",
                "total": { "amount": "129.95", "currency": "USD" },
                "status": "Paid"
              }
            }
          ]
        }
      ]
    }
  ],
  "enriched_at": "2026-05-11T16:45:09Z",
  "contact": null
}

Missing phone

{
  "error": "phone parameter required"
}