Preview · This help is still growing and will be extended over time.

Integration · Administrator

Configure the Custom Integration

Connecting your own system to echo through an HTTP API

Updated: November 2026

With the Custom Integration you connect a system for which echo has no ready-made integration – for example an in-house CRM or an industry solution. You provide an HTTP endpoint that answers echo's queries with people and companies in a fixed JSON format. echo then uses it for caller identification and contact search, like any other integration, and can link each result back to your system.

The integration is set up once by an administrator and applies to the whole organization. All users see the same data from your endpoint.

Prerequisites

How echo calls your endpoint

Fig. 1: For each lookup, echo sends a GET request to your endpoint and expects a JSON list of contacts back.

Request

echo sends a GET request to the Contacts Endpoint with two query parameters:

ParameterValue
queryThe search value; see the table below.
typephone, mail, name or id
typeWhen echo sends itquery contains
phoneIncoming call, or a search for a phone numberThe number in international format, e.g. +41441234567 (URL-encoded as %2B41441234567)
mailSearch for an email addressThe email address, e.g. anna.muster@example.com
nameSearch for a nameThe search term as entered, e.g. Anna Muster
idecho reloads a contact it found earlierThe Id of that person or company

If you fill in API Key Header Name and API Key, echo adds this header to every request:

<API Key Header Name>: <API Key>

Example of a complete request:

GET https://crm.example.com/api/contacts?query=%2B41441234567&type=phone
X-Api-Key: 3f9a7c2e1b

echo sends the header only when both fields are filled in. If your endpoint expects Authorization: Bearer … or Authorization: Basic …, enter Authorization as header name and the complete value including Bearer or Basic as API key. Other authentication methods (such as OAuth sign-in or client certificates) are not supported.

Response

For phone, mail and name, answer with HTTP status 200 and a JSON array. Each element describes one result and contains a Person, a Company, or both (a person together with the company they work for). Return an empty array [] if nothing matches.

[
  {
    "Person": {
      "Id": 1042,
      "FirstName": "Anna",
      "LastName": "Muster",
      "Emails": ["anna.muster@example.com"],
      "PhoneNumbers": ["+41 44 123 45 67"],
      "Mobiles": ["+41 79 123 45 67"],
      "Faxes": [],
      "Websites": [],
      "Remarks": ["Prefers email"],
      "Addresses": [
        {
          "Street": "Musterstrasse",
          "HouseNumber": "12",
          "PostCode": "8000",
          "City": "Zürich",
          "Canton": "ZH",
          "Country": "Switzerland"
        }
      ]
    },
    "Company": {
      "Id": 2001,
      "Name": "Muster AG",
      "Emails": ["info@example.com"],
      "PhoneNumbers": ["+41 44 123 45 00"],
      "Mobiles": [],
      "Faxes": [],
      "Websites": ["https://www.example.com"],
      "Remarks": [],
      "Addresses": []
    }
  }
]

For type=id, answer with one object of the same shape (not an array), or null if the ID no longer exists.

The fields:

Person / Company
Either may be null or missing. An element with neither is ignored.
Id
Required. Your system's ID of the person or company. echo sends it back with type=id and inserts it into the deep links. Use numeric IDs: echo currently reloads contacts by ID only if the ID is a number.
FirstName, LastName
Person's name. Required for a person.
Name
Company name. Required for a company.
Emails, PhoneNumbers, Mobiles, Faxes, Websites, Remarks
Lists of strings; optional, may be empty or null. Phone numbers ideally in international format (+41 …); numbers without a country code are interpreted with your default phone number region.
Addresses
List of addresses with Street, HouseNumber, PostCode, City, Canton, Country (all optional strings).

The app offers the complete JSON schema as a download under What response does echo expect? on the settings page.

Rules your endpoint must follow:

Set up the integration

Fig. 2: Settings → Custom Integration with a configured endpoint.
1

Open the settings

Open Settings → Custom Integration. The entry appears in the settings menu once the integration has been added.

2

Fill in the fields

Name
Required, up to 50 characters 1. The name of your system as users see it in echo, e.g. on the links Open person in Muster CRM.
API Key Header Name
Optional 2. Name of the HTTP header that carries the key, e.g. X-Api-Key or Authorization.
API Key
Optional, up to 100 characters. The value of that header. echo stores it encrypted and shows only a placeholder afterwards. Leave the field untouched to keep the saved key.
Contacts Endpoint
Required, up to 300 characters 3. Full URL of your endpoint, e.g. https://crm.example.com/api/contacts. echo appends query and type; query parameters already in the URL are kept.
Person Deep Link URL
Optional, up to 250 characters 4. Address of a person in your system. echo replaces {id} with the person's Id, e.g. https://crm.example.com/person/{id}. Without it, echo shows no link to your system for people.
Company Deep Link URL
Optional, up to 250 characters. The same for companies.
3

Save

Click Save. The button is active as soon as Name and Contacts Endpoint are filled in. echo does not test the endpoint when saving – test it as described below.

Test the connection

  1. Call your endpoint the way echo does, for example with curl, and check that it returns status 200 and the JSON shape above:
curl -H "X-Api-Key: 3f9a7c2e1b" "https://crm.example.com/api/contacts?query=%2B41441234567&type=phone"
  1. Repeat with type=name and type=mail, and with a value that does not exist (expected: []).
  2. In echo, search for a name or phone number that exists in your system. The contact should appear; with deep links configured, the link to your system is shown on the contact.

Troubleshooting

The page says the Custom Integration is not enabled. Add it under Settings → Integrations first.

The integration shows Not configured. Name or Contacts Endpoint is empty. echo does not call your endpoint until both are saved.

Callers are no longer recognized at all since the Custom Integration was added. Your endpoint probably answers with an error (e.g. 401 because of a wrong key, 404, 500, a timeout or invalid JSON). Check your endpoint's logs and test it with curl as above. Until it is fixed, you can remove the integration.

Contacts from your system do not appear. Check that your endpoint filters correctly for each type, that phone numbers are returned for the number in international format (+41…), and that the JSON uses the field names above.

A contact appears twice. echo merges a result with a contact from another integration only if the name is similar and they share a phone number or email address. Make sure your data contains these values.

A contact can be found but not reloaded. Use numeric IDs and make sure your endpoint answers type=id with a single object for both person and company IDs.

No link to your system. Fill in Person Deep Link URL or Company Deep Link URL and use the placeholder {id}.