Skip to content
ClientTether Support
Integrations · Developer guide

API for IVRs

Letting a phone system recognise callers, create the ones it doesn’t know, and write the call into the contact’s history.

New · Updated Sep 21, 2026 · 4 min read
On this page

1Connecting a phone system

If calls to your business go through an IVR or a call-centre platform rather than through ClientTether’s own number, the two still need to agree on who’s calling. The API is how that happens: the phone system asks ClientTether whether the caller is already a contact, and acts on the answer.

2The usual pattern

  • A call arrives; the IVR has the caller’s number.
  • It calls read_client_exist?phone=<10 digits> with the account’s access headers.
  • If a contact comes back, the IVR routes the call to the assigned user and can pop the record for whoever answers.
  • If not, the IVR calls create_client to create the contact, so the call is recorded against a real record rather than lost.
  • Either way, create_history_notes writes what happened — who called, when, what the outcome was — into the contact’s history.
  • Where the call should start follow-up, update_client_by_id can set the action plan or sales cycle.

3Things to get right

  • Phone numbers are stored as ten digits with no formatting. Strip +1, brackets, dashes and spaces before you send them.
  • Use the web key of the account the call belongs to. In a franchise network the IVR usually has to pick the location first.
  • Set user_name on history notes to a real user’s first and last name, or the note won’t be attributed.
  • Switch on duplicate checking for create_client in Settings → API, or a repeat caller with a missing match creates a second record.

Screen pop without an IVR

Accounts that use ClientTether’s own telephony can get the same behaviour with the Ext Screen Pop add-on instead of building against the API. See Add-Ons.

4Troubleshooting

Known callers are being created as new contacts

The number format doesn’t match — almost always a leading 1 or punctuation.

Calls land in the wrong location’s account

The web key is fixed when it should be chosen per call.