Skip to main content

​
Overview

The contact lookup webhook lets you identify unknown inbound callers by looking up their phone number in your system before the call connects. When enabled, telli sends a POST request to your endpoint with the caller’s phone number, and your endpoint responds with the contact’s details. This is useful when you want to:
  • Greet callers by name
  • Route calls based on customer data
  • Pass custom properties to your agent’s prompt via dynamic variables
The webhook is called before the call connects. The timeout you configure adds to the caller’s ringing time. Keep your endpoint fast and set the timeout as low as possible.

​
Setup

  1. Go to Settings → Integrations
  2. Select Contact Lookup Webhook
  3. Enter your webhook URL
  4. Set a timeout (1–10 seconds)
  5. Optionally add custom headers and query parameters
  6. Enable the integration and click Save

​
Request

When an inbound call arrives from an unknown number, telli sends a POST request to your webhook URL: 
{
  "event": "contact_lookup",
  "phone_number": "+14155551234"
}
FieldTypeDescription
eventstringAlways "contact_lookup"
phone_numberstringThe caller’s phone number in E.164 format
Any custom headers and query parameters you configured in the integration settings are included in the request.

​
Signature verification

The request includes an x-telli-signature header that you can use to verify the request was sent by telli. The signature is an HMAC-SHA256 hash of the request body, signed with your account’s API key.

​
Response

Your endpoint should return a JSON response with the contact’s details: 
{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "salutation": "Ms.",
    "email": "[email protected]",
    "external_id": "usr_12345",
    "external_url": "https://crm.example.com/contacts/12345",
    "phone_number": "+14155551234",
    "properties": {
      "plan": "enterprise",
      "account_manager": "John Smith",
      "priority": 1
    }
  }
}
FieldTypeRequiredDescription
first_namestringYesContact’s first name (1–50 characters)
last_namestringYesContact’s last name (1–50 characters)
salutationstringNoSalutation or title (e.g. “Mr.”, “Ms.”, “Dr.”)
emailstringNoContact’s email address
external_idstringNoYour system’s identifier for the contact. If a contact with this ID already exists, it will be updated instead of creating a duplicate.
external_urlstringNoA URL to the contact in your system
phone_numberstringNoThe contact’s phone number (defaults to the caller’s number if omitted)
propertiesobjectNoCustom contact properties. Keys must match your configured property keys. Values must match the property’s data type (string, number, boolean, date, select value, or array for multi-select).

​
Unknown caller

If the phone number is not found in your system, return an empty contact: 
{
  "contact": null
}

​
Custom properties

The properties object lets you pass custom data that matches your contact properties configuration. Property keys must match the keys you’ve defined in Settings → Contact properties. Values that don’t match a defined property key are ignored.

​
Error handling

  • If your endpoint returns a non-2xx status code, the call proceeds with an unknown contact
  • If your endpoint doesn’t respond within the configured timeout, the call proceeds with an unknown contact
  • If the response body doesn’t match the expected format, the call proceeds with an unknown contact
In all error cases, the call is never blocked — the caller will always be connected.

​
Example implementation

Here’s a minimal example using Node.js and Express: 
app.post("/telli/contact-lookup", (req, res) => {
  const { phone_number } = req.body;

  // Look up the contact in your database
  const contact = db.findContactByPhone(phone_number);

  if (!contact) {
    return res.json({ contact: null });
  }

  res.json({
    contact: {
      first_name: contact.firstName,
      last_name: contact.lastName,
      email: contact.email,
      external_id: contact.id,
      properties: {
        plan: contact.plan,
        account_manager: contact.accountManager,
        priority: contact.priority,
      },
    },
  });
});