Contacts
One contact per phone number. A contact has more fields than listed here: ignore fields you don’t recognize, new ones may be added. The suppression fields (opt_out_locked, dnd_sms and others) are explained under Opt-outs.
#The Contact object
idinteger- The contact id. Use it in
/contacts/:id, not the phone number. phonestring- The number, stored as E.164. One contact per number, and it can’t be changed.
first_namestring- First name.
last_namestring- Last name.
emailstring- Email address.
tagsstring- A JSON-encoded string, for example
"[\"vip\",\"hot\"]". Parse it withJSON.parse(contact.tags). When you send tags, send a real array. pipeline_stagestring- A stage id from your pipeline, for example
new_lead. sourcestring- Where the contact came from.
manualby default. statusstringactivefor a new contact.opted_out,blocked,wrong_numberanddeceasedmean texting is off (dnd_smsis1). How people opt out: Compliance.scoreinteger- Lead score.
50for a new contact. dnd_smsinteger1when texting is off for this contact,0otherwise. An integer, not a boolean.opt_out_lockedinteger1when a STOP or a TCPA lock blocks texts. See Suppression fields.opt_out_atstring | null- When the contact opted out, ISO 8601.
nullif they haven’t. timezonestring- IANA name such as
America/New_York. Set from a US number’s area code if you don’t send one. custom_fieldsobject | null- Your custom fields, key by key.
created_atstring- When the contact was added, ISO 8601.
updated_atstring- When the contact last changed, ISO 8601.
last_message_atstring | null- When the last message with the contact was, ISO 8601.
nullif none. List contacts reads it fresh. Get a contact returns the stored value, which is refreshed every 30 minutes, so it can lag.
#List contacts
Your contacts, most recently updated first, with filters.
Parameters
searchstring · query- Partial, case-insensitive match on name, email, company or phone.
How matching works
Name means first or last name. Phone numbers match in any format once you type at least 7 digits; shorter digit strings match only as written. Withouttag, only the first 5,000 matches in yoursortorder are considered, so a broad search can miss an older contact. Narrow broad searches. tagstring · query- Exact tag name, case-sensitive:
VIPisn’tvip. statusstring · query- For example
opted_out. dndinteger · query1: only contacts with texting turned off.limitinteger · queryDefault50Max1000- Page size.
offsetinteger · queryDefault0- Rows to skip: a whole number, 0 or more. Deep offsets get slower; offset is for screens, not for copying a whole account.
sortenum · query- Default: most recently updated first. For a full export use
date_added: a contact edited while you page jumps to the front of the default order. Or take every contact in one file with Export contacts as CSV. Unknown values fall back to the default.name_asc,name_descphone_asc,phone_descsource_asc,source_descassignee_asc,assignee_desclastact_asc,lastact_descstatus_asc,status_descscore_high,score_lowdate_added
stagestring · query- Pipeline stage.
sourcestring · query- Where the contact came from.
companystring · query- Company name.
statestring · query- US state.
assigned_tostring · query- A team member id, or
unassigned. score_min, score_maxinteger · query- Lead score range.
include_spaminteger · query- Contacts marked spam are left out unless you send
1. stage_notstring · query- Comma-separated stage ids to leave out.
last_contactinteger · query- Only contacts changed in the last N days (by
updated_at, not by messages). last_activity, la_from, la_tostring · query- Filters by the last message. A smart list rule with the same name means something else: the last edit (Smart lists).
none: never messaged.afterwithla_from,beforewithla_to, orbetweenwith both. Dates areYYYY-MM-DD, read as UTC days:afterincludes thela_fromday,beforeleaves thela_today out, andbetweenincludes both days. Any other value, or a missing date, returns400. dialer_list_idinteger · query- Only contacts in this list or smart list.
status=deletedquery- Includes soft-deleted contacts. Every other
statusleaves them out. sort=custom:<field_id>:asc|descquery- Sorts by a custom field. Dates sort by date, other values as text.
ids_only, ids_limitinteger · query- With
ids_only=1, returns{ids, total, has_more}instead of contacts: the ids that match, up toids_limit(max 100,000).
Returns a list of Contact objects in data.
Returns
totalinteger- Matching contacts, for display only. Stop paging on a page shorter than
limit(or empty). It can be an estimate, up to 2 minutes old. When nothing matches it is always0. total_is_estimatebooleantruewhentotalis an estimate.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_offset | Not a whole number, 0 or more. |
#Get a contact
One contact by id.
Parameters
idinteger · pathRequired- The contact id.
Returns a Contact object in data.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | INVALID_CONTACT_ID | Not a contact id (for example a phone number). |
| 403 | CONTACT_NOT_ASSIGNED | Your key belongs to a team member who sees only their assigned contacts, and this contact is assigned to someone else. |
| 404 | CONTACT_NOT_FOUND | No contact with this id on your account. |
#Create a contact
Adds a contact. Retrying a timed-out create is safe: an existing number (any format) returns 409 CONTACT_EXISTS, and Idempotency-Key isn’t used here. A new contact fires the contact_created webhook. Free, but scrubbing runs if it’s on, at your scrub rate. Needs the edit_contacts permission.
Parameters
phonestringRequired- E.164 recommended (
+12125550199). Any common US format is accepted; stored as E.164.
More parameters
first_namestringlast_namestringemailstringtagsstring[]- An array of strings.
company_namestringpipeline_stagestringDefault: the first stage of your pipeline (new_leadif you never changed your stages)- Free text, stored as sent; use a stage id from List stages. A stage name is not matched to its id, so a contact sent with one sits on no stage.
sourcestringDefaultmanualtimezonestring- IANA name such as
America/Chicago. If omitted, set from a US number’s area code. websitestringaddress1, address2, city, state, postal_code, countrystring- Address fields.
date_of_birthstringgenderstringassigned_tointeger- A team member id.
dnd_sms, dnd_email, dnd_callsinteger1to turn off texting, email or calls. Turning texting off is an opt-out that can’t be undone over the API.consent_attestedbooleantruerecords that this person agreed to get texts from you. The record keeps your IP address and user agent. If it can’t be saved, the contact is still created and the reply hasconsent_not_recorded: true.consent_attestation_textstring- The consent wording you showed, up to 1,000 characters. Used only with
consent_attested. Without it, a standard sentence is recorded.
Returns 201 with the new Contact object in data.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | no code | No phone number. |
| 400 | INVALID_PHONE |
The number can’t be read. |
| 400 | invalid_field | Wrong type, such as non-list tags. |
| 400 | ASSIGNEE_NOT_ON_ACCOUNT | assigned_to isn’t on your account. |
| 409 | CONTACT_EXISTS | Number exists. Find it with GET /contacts?search=<phone>. |
See also: the guide to doing this in the app.