Preview · This help is still growing and will be extended over time.
Configure the Custom Integration
Connecting your own system to echo through an HTTP API
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
- The Custom Integration is activated for your organization. If it is missing in the catalog under Settings → Integrations, contact echo support (opens in a new tab).
- It is added under Settings → Integrations (see How integrations work).
- You are signed in to echo as an administrator.
- Your endpoint is reachable from the internet over HTTPS and implements the contract below.
How echo calls your endpoint
Request
echo sends a GET request to the Contacts Endpoint with two query parameters:
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
nullor missing. An element with neither is ignored. - Id
- Required. Your system's ID of the person or company. echo sends it back with
type=idand 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:
- Filter yourself. echo shows what you return. For
phone, return only contacts that have this number. - Always answer successfully. Any status other than 2xx (also
404for “not found”) or a response that is not valid JSON counts as an error – and an error can make the whole caller lookup fail, also for the other integrations. Answer "nothing found" with[]. - Answer quickly. echo waits for all integrations before showing the result, so a slow endpoint delays every caller lookup.
Set up the integration
Open the settings
Open Settings → Custom Integration. The entry appears in the settings menu once the integration has been added.
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-KeyorAuthorization. - 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 appendsqueryandtype; 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'sId, 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.
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
- 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"
- Repeat with
type=nameandtype=mail, and with a value that does not exist (expected:[]). - 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}.