readyDocs Open the appOpen the app

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 with JSON.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. manual by default.
statusstring
active for a new contact. opted_out, blocked, wrong_number and deceased mean texting is off (dnd_sms is 1). How people opt out: Compliance.
scoreinteger
Lead score. 50 for a new contact.
dnd_smsinteger
1 when texting is off for this contact, 0 otherwise. An integer, not a boolean.
opt_out_lockedinteger
1 when a STOP or a TCPA lock blocks texts. See Suppression fields.
opt_out_atstring | null
When the contact opted out, ISO 8601. null if 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. null if 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

tagstring · query
Exact tag name, case-sensitive: VIP isn’t vip.
statusstring · query
For example opted_out.
dndinteger · query
1: only contacts with texting turned off.
limitinteger · queryDefault 50Max 1000
Page size.
offsetinteger · queryDefault 0
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_desc
  • phone_asc , phone_desc
  • source_asc , source_desc
  • assignee_asc , assignee_desc
  • lastact_asc , lastact_desc
  • status_asc , status_desc
  • score_high , score_low
  • date_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. after with la_from, before with la_to, or between with both. Dates are YYYY-MM-DD, read as UTC days: after includes the la_from day, before leaves the la_to day out, and between includes both days. Any other value, or a missing date, returns 400.
dialer_list_idinteger · query
Only contacts in this list or smart list.
status=deletedquery
Includes soft-deleted contacts. Every other status leaves 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 to ids_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 always 0.
total_is_estimateboolean
true when total is an estimate.
Errors
HTTPCodeWhen
400invalid_offsetNot 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
HTTPCodeWhen
400INVALID_CONTACT_IDNot a contact id (for example a phone number).
403CONTACT_NOT_ASSIGNEDYour key belongs to a team member who sees only their assigned contacts, and this contact is assigned to someone else.
404CONTACT_NOT_FOUNDNo 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_namestring
last_namestring
emailstring
tagsstring[]
An array of strings.
company_namestring
pipeline_stagestringDefault: the first stage of your pipeline (new_lead if 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.
sourcestringDefault manual
timezonestring
IANA name such as America/Chicago. If omitted, set from a US number’s area code.
websitestring
address1, address2, city, state, postal_code, countrystring
Address fields.
date_of_birthstring
genderstring
assigned_tointeger
A team member id.
dnd_sms, dnd_email, dnd_callsinteger
1 to turn off texting, email or calls. Turning texting off is an opt-out that can’t be undone over the API.

Returns 201 with the new Contact object in data.

Errors
HTTPCodeWhen
400no codeNo phone number.
400 INVALID_PHONE The number can’t be read.
400invalid_fieldWrong type, such as non-list tags.
400ASSIGNEE_NOT_ON_ACCOUNTassigned_to isn’t on your account.
409CONTACT_EXISTSNumber exists. Find it with GET /contacts?search=<phone>.