Custom Caller Context

Connect any internal system — a CRM, helpdesk, ERP, or custom database — to Phone.inc's caller context by hosting a single JSON endpoint. When a call comes in, we call your URL with the phone number and display the response to your team.

How it works

  1. You expose an HTTPS endpoint that accepts a phone query parameter
  2. In the Phone.inc dashboard, you add the URL under Integrations → Custom Endpoint
  3. On every incoming call, we GET your URL with the caller's phone number appended
  4. Your endpoint returns JSON matching the schema below
  5. Your team sees the data in the sidebar before they pick up

Setting it up

Go to Integrations in your Phone.inc dashboard, find "Custom Endpoint" in the available integrations, and click Connect. Enter your endpoint URL and save.

For authentication without API tokens in the URL, enable request signing. Signing is optional and off by default. Existing unsigned endpoints and URLs with query-string credentials continue to work unchanged:

https://your-api.com/caller-lookup?token=abc123

We'll append &phone=%2B4571999900 to that URL on each call. Enabling signing does not remove existing credentials from your URL; remove them yourself once your endpoint verifies signatures.

Optional request signing

  1. In the Custom Endpoint connection editor, enable Sign requests. Phone.inc automatically generates a fresh Ed25519 key pair in your browser.
  2. Copy the Public key to your endpoint's configuration. It is a 32-byte raw public key encoded as 44 standard Base64 characters, including the final = padding, without PEM headers. Only the public key belongs on your server. Phone.inc stores the private key encrypted and never returns it from the editor or test response.
  3. Follow the Ruby verification example, then use Test with an E.164 phone number. Tests use the current signing settings, including an unsaved replacement key.
  4. Save the connection to apply those settings to live lookups.

Each time you enable signing, a new key pair is generated. To rotate a key, switch signing off and back on in the editor without saving between those steps. Install the new public key on your endpoint alongside the old public key, test, and save. Remove the old public key after saving. Saving with signing disabled sends no signing headers. An endpoint that requires signatures will reject unsigned requests until you change its policy.

Signing applies only to caller-context GET requests, not AI tool operations. HTTPS is still required. Signed endpoint URLs cannot contain embedded username/password credentials or fragments.

Signature contract

Signed requests include:

HeaderValue
X-Phone-Inc-TimestampUnix timestamp in seconds
X-Phone-Inc-Signatureed25519-v1= followed by a standard Base64 signature

The algorithm is Ed25519, with a 64-byte signature (88 Base64 characters). Verify the signature over these four UTF-8 lines, joined by a single LF (\n), with no trailing newline. Pass the message directly to Ed25519; do not hash it first:

<timestamp header>
GET
<lowercase endpoint hostname>:<port>
<raw request path and query string>

Always include the port, including 443 for the default HTTPS port. The path includes a leading /. Preserve the exact query encoding and order, including the appended phone; do not parse and re-encode it. For example:

1793275200
GET
your-api.com:443
/caller-lookup?account=acme&phone=%2B4571999900

Use your configured public endpoint hostname and port, not an untrusted forwarded header or internal reverse-proxy hostname. Reject missing headers, unknown signature versions, malformed signatures, failed verification, and timestamps more than five minutes in the past or future. Keep server clocks synchronized. For strict replay prevention within that window, atomically record each verified signature in a shared cache for the remaining validity window and reject duplicates; caller-context GETs must remain read-only.

This protocol is distinct from partner caller-context signing, which uses shared-secret HMAC and v1= signatures.

Ruby verification

For Ruby 3.4+ and Rails, no extra gems are needed. Set PHONE_INC_CONTEXT_PUBLIC_KEY to the public key copied from the editor. Replace your-api.com:443 with your public endpoint's lowercase hostname and port.

Add this method to your lookup controller:

require 'openssl'
require 'base64'

def valid_phone_inc_request?(request)
  timestamp = request.headers['X-Phone-Inc-Timestamp'].to_s
  header = request.headers['X-Phone-Inc-Signature'].to_s
  return false unless timestamp.match?(/\A\d{1,12}\z/)
  return false if (Time.now.to_i - timestamp.to_i).abs > 300
  return false unless header.start_with?('ed25519-v1=')

  key = OpenSSL::PKey.new_raw_public_key(
    'ED25519', Base64.strict_decode64(ENV.fetch('PHONE_INC_CONTEXT_PUBLIC_KEY'))
  )
  signature = Base64.strict_decode64(header.delete_prefix('ed25519-v1='))
  message = [
    timestamp, request.request_method,
    'your-api.com:443', request.original_fullpath
  ].join("\n")
  key.verify(nil, signature, message)
rescue ArgumentError, OpenSSL::PKey::PKeyError
  false
end

At the start of your lookup action, reject invalid requests before reading or returning caller data:

return head(:unauthorized) unless valid_phone_inc_request?(request)

If a proxy rewrites paths, verify against the original public path and raw query string before rewriting, or preserve them through a trusted proxy configuration. This example bounds replay to five minutes; add the shared replay cache described above if your policy requires single-use requests. Verify before querying your CRM or returning caller data. A valid signature authenticates Phone.inc's request, not the caller's identity.

Endpoint contract

Request

We make a GET request to your URL with the caller's phone number appended as a query parameter:

GET https://your-api.com/caller-lookup?phone=%2B4571999900
  • Phone numbers are URL-encoded E.164 format (e.g. +4571999900 becomes %2B4571999900)
  • If your URL already has query parameters, we append &phone=...
  • We set a timeout of 2.5 seconds
  • We send Accept: application/json

Response

Return a JSON object with provider, label, and source. Include contact, sections, or both — a contact-only response is valid and is normalized with an empty sections array:

{
  "provider": "internal_crm",
  "label": "Internal CRM",
  "source": "acme-corp",
  "url": "https://crm.acme.com/contacts/456",
  "contact": {
    "name": "Jamie Rivera",
    "email": "jamie@example.com",
    "company_name": "Acme Inc.",
    "note": "VIP customer"
  },
  "sections": [
    {
      "type": "fields",
      "fields": [
        { "label": "Account Manager", "value": "Sarah Jensen" },
        { "label": "Contract Value", "value": { "amount": "24000", "currency": "DKK" }, "format": "money" },
        { "label": "Renewal", "value": "2026-09-01T00:00:00Z", "format": "date" }
      ]
    },
    {
      "type": "table",
      "label": "Open Tickets",
      "columns": [
        { "key": "id", "label": "Ticket" },
        { "key": "subject", "label": "Subject" },
        { "key": "status", "label": "Status", "format": "badge" }
      ],
      "rows": [
        {
          "url": "https://crm.acme.com/tickets/78",
          "values": { "id": "#78", "subject": "Invoice question", "status": "Open" }
        },
        {
          "url": "https://crm.acme.com/tickets/65",
          "values": { "id": "#65", "subject": "Delivery delay", "status": "Resolved" }
        }
      ]
    }
  ]
}

Required fields

FieldTypeDescription
providerstringA machine-readable slug for your system (lowercase, no spaces)
labelstringHuman-readable name shown in the UI
sourcestringAccount or workspace identifier

Optional fields

FieldTypeDescription
urlstringLink to the matched record in your system
contactobjectIdentity to create or update in Phone.inc's contacts
sectionsarrayArray of section objects (see below). Omitted or null values become an empty array.

Cache the matched contact

Include a contact object when the caller matched by your endpoint should be cached in Phone.inc's address book:

{
  "contact": {
    "name": "Jamie Rivera",
    "email": "jamie@example.com",
    "company_name": "Acme Inc.",
    "note": "VIP customer"
  }
}
FieldTypeRequiredDescription
namestringYesContact name, up to 128 characters
emailstringNoValid email address, truncated to 320 characters before validation. Invalid values are omitted.
company_namestringNoBusiness or employer name, up to 128 characters
notestringNoNote copied to the contact, up to 10,000 characters

The phone query parameter from our request becomes the contact's phone number. Do not return a separate phone inside contact.

When the phone number has no Phone.inc contact, we create one. When a contact already exists, we fill only blank fields. Data from your endpoint never overwrites a name, email, company name, or note saved by a user.

The contact object controls address-book caching. The sections array controls what employees see in caller context. You can return either or both in the same response. A response without contact continues to work exactly as before.

Section types

Fields section

A vertical list of label/value pairs.

{
  "type": "fields",
  "label": "Customer Info",
  "fields": [
    { "label": "Name", "value": "Niklas Stephenson" },
    { "label": "Email", "value": "niklas@example.com", "format": "email" },
    { "label": "Phone", "value": "+4571999900", "format": "phone" }
  ]
}

Each field has:

KeyTypeRequiredDescription
labelstringYesThe label shown to the left of the value
valuestring, number, or money objectYesThe value to display
formatstringNoHow to render the value (see format hints)
urlstringNoMakes the value a clickable link

Table section

A compact table with column headers and rows. Columns are rendered in a two-line layout per row: the first half of columns stacks on the left, the second half on the right. For example, with four columns [Order, Date, Total, Status], each row renders as:

#1001            $89.00
Apr 28           Paid

Order your columns so the primary identifier is first and the most important secondary value is in the right-hand half (at position ceil(columns.length / 2)).

{
  "type": "table",
  "label": "Recent Orders",
  "columns": [
    { "key": "name", "label": "Order" },
    { "key": "date", "label": "Date", "format": "date" },
    { "key": "total", "label": "Total", "format": "money" }
  ],
  "rows": [
    {
      "url": "https://your-system.com/orders/1001",
      "values": {
        "name": "#1001",
        "date": "2026-04-28T12:00:00Z",
        "total": { "amount": "89", "currency": "DKK" }
      }
    }
  ]
}

Format hints

FormatValue typeRendering
textString (default if omitted)Rendered as-is
money{ "amount": "89", "currency": "DKK" }Locale-formatted with currency symbol
dateISO 8601 stringFormatted date
emailStringClickable mailto link
phoneString (E.164)Tap-to-call on mobile
badgeStringColored status pill

To make any value clickable, use the field-level url property instead of a format hint. The url property works with every format — for example, a badge value with a url renders as a pill that links to the given URL.

Limits

We enforce these limits to keep the UI fast and readable:

LimitMaximum
Sections per response5
Fields per fields section15
Columns per table section8
Rows per table section10
Value string length500 characters

Data beyond these limits is silently truncated. Unknown keys in the JSON are silently ignored — we will never reject a payload for having extra fields, so you can safely add internal metadata without breaking the integration.

Error handling

Your responseOur behavior
HTTP 200 with valid JSONDisplay the data
HTTP 200 with empty/invalid JSONSkip silently (no error shown)
HTTP 404 or empty bodySkip silently — caller not found in your system
HTTP 429Retry on next call, log as rate-limited
HTTP 5xx or timeoutLog as transient error, retry on next call
Connection refusedLog as transient error

We never mark the integration as permanently broken for transient errors. Your team won't see error states for occasional blips.

Example implementation

A minimal Node.js/Express endpoint:

const express = require('express')
const app = express()

app.get('/caller-lookup', (req, res) => {
  const phone = req.query.phone
  if (!phone) return res.status(400).json({ error: 'phone required' })

  // Look up the caller in your system
  const customer = db.findCustomerByPhone(phone)
  if (!customer) return res.status(404).json({})

  res.json({
    provider: 'my_crm',
    label: 'My CRM',
    source: 'production',
    url: `https://crm.example.com/customers/${customer.id}`,
    contact: {
      name: customer.name,
      email: customer.email,
      company_name: customer.companyName,
      note: customer.note,
    },
    sections: [
      {
        type: 'fields',
        fields: [
          { label: 'Name', value: customer.name },
          { label: 'Email', value: customer.email, format: 'email' },
          { label: 'Account type', value: customer.tier, format: 'badge' },
        ],
      },
    ],
  })
})

app.listen(3000)