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
- You expose an HTTPS endpoint that accepts a
phonequery parameter - In the Phone.inc dashboard, you add the URL under Integrations → Custom Endpoint
- On every incoming call, we
GETyour URL with the caller's phone number appended - Your endpoint returns JSON matching the schema below
- 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
- In the Custom Endpoint connection editor, enable Sign requests. Phone.inc automatically generates a fresh Ed25519 key pair in your browser.
- 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. - 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.
- 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:
| Header | Value |
|---|---|
X-Phone-Inc-Timestamp | Unix timestamp in seconds |
X-Phone-Inc-Signature | ed25519-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.
+4571999900becomes%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
| Field | Type | Description |
|---|---|---|
provider | string | A machine-readable slug for your system (lowercase, no spaces) |
label | string | Human-readable name shown in the UI |
source | string | Account or workspace identifier |
Optional fields
| Field | Type | Description |
|---|---|---|
url | string | Link to the matched record in your system |
contact | object | Identity to create or update in Phone.inc's contacts |
sections | array | Array 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"
}
}
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Contact name, up to 128 characters |
email | string | No | Valid email address, truncated to 320 characters before validation. Invalid values are omitted. |
company_name | string | No | Business or employer name, up to 128 characters |
note | string | No | Note 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:
| Key | Type | Required | Description |
|---|---|---|---|
label | string | Yes | The label shown to the left of the value |
value | string, number, or money object | Yes | The value to display |
format | string | No | How to render the value (see format hints) |
url | string | No | Makes 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
| Format | Value type | Rendering |
|---|---|---|
text | String (default if omitted) | Rendered as-is |
money | { "amount": "89", "currency": "DKK" } | Locale-formatted with currency symbol |
date | ISO 8601 string | Formatted 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. 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:
| Limit | Maximum |
|---|---|
| Sections per response | 5 |
| Fields per fields section | 15 |
| Columns per table section | 8 |
| Rows per table section | 10 |
| Value string length | 500 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 response | Our behavior |
|---|---|
| HTTP 200 with valid JSON | Display the data |
| HTTP 200 with empty/invalid JSON | Skip silently (no error shown) |
| HTTP 404 or empty body | Skip silently — caller not found in your system |
| HTTP 429 | Retry on next call, log as rate-limited |
| HTTP 5xx or timeout | Log as transient error, retry on next call |
| Connection refused | Log 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)