Caller context

When the phone rings, knowing who's calling — and what they bought — 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 the matching customer plus their recent orders.

Today we look up data from Shopify. More providers are on the way. The response shape is stable across providers, so building against it now means you'll get new sources for free.

The caller context model

The endpoint returns an array of contexts — one per provider that found a matching customer. Each context has the customer's basic profile and their recent orders, all linked back to the source system with deep links into its admin UI.

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 (e.g. invalid input).

Context object

Name
provider
Type
string
Description
Identifier for the source system, e.g. shopify.
Name
store
Type
string
Description
The store or workspace within the provider, e.g. the Shopify shop domain.
Name
customer
Type
object
Description
The matched customer profile. See below.
Name
orders
Type
array
Description
Recent orders for this customer, newest first. See below.

Customer object

Name
id
Type
string
Description
The customer's ID in the provider's system.
Name
name
Type
string
Description
Display name (typically First Last).
Name
email
Type
string
Description
Email on file. May be null.
Name
phone
Type
string
Description
Phone number on file in E.164 format.
Name
admin_url
Type
string
Description
Deep link to the customer in the provider's admin UI. Open this in a new tab when an employee clicks "view in Shopify".

Order object

Name
id
Type
string
Description
The order's ID in the provider's system.
Name
name
Type
string
Description
Human-readable order number, e.g. #1042.
Name
processed_at
Type
timestamp
Description
ISO 8601 timestamp of when the order was placed.
Name
total
Type
string
Description
Order total as a decimal string (so amounts don't lose precision), e.g. "129.95".
Name
currency
Type
string
Description
ISO 4217 currency code, e.g. USD.
Name
status
Type
string
Description
Provider-specific order status, e.g. paid, fulfilled, refunded.
Name
admin_url
Type
string
Description
Deep link to the order in the provider's admin UI.

GET/v1/caller_context

Look up a caller

Query every connected integration for the given phone number and return the matched customers and their recent orders. 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",
      "store": "acme-store.myshopify.com",
      "customer": {
        "id": "gid://shopify/Customer/8123456789",
        "name": "Jamie Rivera",
        "email": "[email protected]",
        "phone": "+14085550199",
        "admin_url": "https://admin.shopify.com/store/acme-store/customers/8123456789"
      },
      "orders": [
        {
          "id": "gid://shopify/Order/4112233445",
          "name": "#1042",
          "processed_at": "2026-05-09T22:14:01Z",
          "total": "129.95",
          "currency": "USD",
          "status": "paid",
          "admin_url": "https://admin.shopify.com/store/acme-store/orders/4112233445"
        }
      ]
    }
  ],
  "enriched_at": "2026-05-11T16:45:09Z"
}

Missing phone

{
  "error": "phone parameter required"
}