Contacts
A contact is a person you send campaigns to: one per phone number per organization, with names, tags, custom fields, consent and opt-out state. Numbers are encrypted at rest. Add contacts to groups or import a CSV.
The contact object
Section titled “The contact object”| Field | Type | Description |
|---|---|---|
id |
string | con_… |
phone |
string | E.164. |
country |
string or null | ISO 3166-1 alpha-2 country of the number. |
firstName, lastName, email |
string or null | |
timeZone |
string or null | IANA zone. Overrides the number’s zone for campaign quiet hours. |
tags |
string[] | Sorted. |
customFields |
object | Flat snake_case keys with string, number, boolean or null values. Used as {{custom.<key>}}. |
consent |
object or null | { source, at, text }: where and when the person agreed. |
optedOut |
object or null | { at, source }. source is sms_keyword (a STOP reply), api or web. Opted-out contacts are skipped by campaigns. |
groups |
object[] | { id, name } of each group the contact is in. |
createdAt, updatedAt |
string |
Create a contact
Section titled “Create a contact”/v1/contactscontacts:manageReturns 201 with the contact. Supports Idempotency-Key.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
phone |
string | Yes | The number. | E.164; one contact per number. |
firstName |
string | No | Up to 120 characters. | |
lastName |
string | No | Up to 120 characters. | |
email |
string | No | A valid email, up to 254 characters. | |
timeZone |
string | No | IANA zone, such as Africa/Cairo. |
|
tags |
string[] | No | Up to 20; each 1 to 40 letters, digits, spaces, _ or -, starting with a letter or digit. |
|
customFields |
object | No | Up to 50 snake_case keys, 4 KB; values are strings up to 500 characters, numbers, booleans or null. No nesting. |
|
consent |
object | No | source (web_form, import, api, in_person, paper, sms_keyword, other), at (ISO 8601, default now), text (up to 500). |
|
groupIds |
string[] | No | Add to these groups. | Up to 20. |
curl https://api.smsfabric.com/v1/contacts \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+201001234567", "firstName": "Mona", "lastName": "Hassan", "tags": ["vip", "cairo"], "customFields": { "branch": "Nasr City", "loyalty_points": 1250 }, "consent": { "source": "web_form", "text": "I agree to receive offers by SMS." }, "groupIds": ["grp_t6w9z2c5f8i1l4o7r0u3x6a9"] }'{ "id": "con_a8d1g4j7m0p3s6v9y2b5e8h1", "phone": "+201001234567", "country": "EG", "firstName": "Mona", "lastName": "Hassan", "email": null, "timeZone": null, "tags": ["cairo", "vip"], "customFields": { "branch": "Nasr City", "loyalty_points": 1250 }, "consent": { "source": "web_form", "at": "2026-11-19T10:40:00.000Z", "text": "I agree to receive offers by SMS." }, "optedOut": null, "groups": [{ "id": "grp_t6w9z2c5f8i1l4o7r0u3x6a9", "name": "Newsletter" }], "createdAt": "2026-11-19T10:40:00.000Z", "updatedAt": "2026-11-19T10:40:00.000Z"}| Error | When |
|---|---|
409 contact_exists |
A contact with this number exists. |
404 not_found |
A groupIds entry is not in your organization. |
400 validation_failed |
An invalid field. |
List contacts
Section titled “List contacts”/v1/contactscontacts:readNewest first, paginated.
| Query | Type | Description |
|---|---|---|
q |
string | A full number (exact match, any format with +), the last 4 digits, or text contained in the first name, last name or email. |
tag |
string | Contacts with this tag. |
groupId |
string | Contacts in this group. |
optedOut |
string | true or false. |
limit |
integer | 1 to 200, default 50. |
cursor |
string | nextCursor from the previous page. |
curl "https://api.smsfabric.com/v1/contacts?tag=vip&optedOut=false&limit=100" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Returns { "data": [Contact, …], "nextCursor": "…" | null }.
List tags
Section titled “List tags”/v1/contacts/tagscontacts:readTags in use with how many contacts carry each, most used first, top 200. Tags compare case-insensitively.
| Query | Type | Description |
|---|---|---|
q |
string | Tag prefix. |
curl "https://api.smsfabric.com/v1/contacts/tags?q=ca" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [{ "tag": "cairo", "contacts": 1840 }, { "tag": "campaign-2025", "contacts": 312 }] }Export contacts as CSV
Section titled “Export contacts as CSV”/v1/contacts/export.csvcontacts:read, logs:exportStreams contacts as text/csv with columns id, phone, firstName, lastName, email, country, timeZone, tags, groups, customFields, consentSource, consentAt, optedOutAt, createdAt. Cells are escaped against formula injection. Needs both scopes, counts toward the bulk rate limit (20 a minute), and is audited as contacts.exported with the row count.
| Query | Type | Description |
|---|---|---|
tag |
string | Only contacts with this tag. |
groupId |
string | Only contacts in this group. |
curl "https://api.smsfabric.com/v1/contacts/export.csv?groupId=grp_t6w9z2c5f8i1l4o7r0u3x6a9" \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -o newsletter.csvRetrieve a contact
Section titled “Retrieve a contact”/v1/contacts/:idcontacts:readcurl https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Returns the contact. 404 not_found if it isn’t in your organization.
Update a contact
Section titled “Update a contact”/v1/contacts/:idcontacts:manageAccepts every create field except groupIds. tags and customFields replace the current values. Also accepts optedOut: true marks the contact opted out (source api for keys, web for portal users), false clears it. Returns the contact.
curl -X PATCH https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"timeZone": "Africa/Cairo", "optedOut": true}'| Error | When |
|---|---|
409 contact_exists |
The new phone belongs to another contact. |
404 not_found |
No such contact. |
Delete a contact
Section titled “Delete a contact”/v1/contacts/:idcontacts:manageErases the contact with its tags and group memberships (right to erasure). Messages already sent stay in the message log. Returns 204. Audited as contact.deleted.
curl -X DELETE https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"