Contacts
Contacts are the people you call. They're the foundation of every campaign—you can't make calls without them.
What contacts store
At minimum, a contact needs a phone number. Beyond that, you can store as much or as little information as you need:
primaryPhone
Yes
The phone number to call
firstName
No
First name
lastName
No
Last name
fullName
No
Full name (if you prefer not to split)
primaryEmail
No
Email address
address
No
Street address
city
No
City
state
No
State or region
zip
No
Postal code
occupation
No
Job title or occupation
preferredChannel
No
How they prefer to be contacted
gender
No
male or female
customAttributes
No
Any additional data you need
Creating contacts
Add a single contact:
Response:
Bulk importing contacts
For larger datasets, use the upsert endpoint. It creates new contacts and updates existing ones (matched by phone number):
This is the recommended way to sync contacts from external systems.
Searching and filtering
List contacts with pagination and search:
Searchable fields: firstName, lastName, fullName, primaryPhone, primaryEmail
Sortable fields: firstName, lastName, primaryPhone, primaryEmail, createdAt
Updating contacts
Update specific fields without affecting others:
Custom attributes
Standard fields don't cover every use case. Custom attributes let you store any additional data:
You can reference custom attributes in your call flows to personalize messages. For example, play back the accountBalance value during a payment reminder call.
Before using custom attributes, define them at the organization level. See Custom Attributes for details.
Phone number format
Gomobile accepts phone numbers in various formats, but we recommend E.164 format for consistency:
Numbers are stored as provided. Make sure your DID pool numbers and contact numbers use consistent formats for proper caller ID display.
Deleting contacts
Contacts are soft-deleted, meaning they're hidden but not permanently removed:
Soft deletion preserves historical data for reporting. Contact support if you need to permanently remove data for compliance reasons.
Best practices
Use consistent phone formats - Stick to E.164 when possible
Keep data clean - Regularly deduplicate and update stale records
Use custom attributes wisely - Define them before importing data
Segment with audiences - Don't try to filter contacts at call time
Related concepts
Audiences - Grouping contacts for campaigns
Custom Attributes - Defining additional fields
Programs - Using contacts in campaigns
Last updated