Skip to content

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.

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
POST/v1/contactscontacts:manage

Returns 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.
Terminal window
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.
GET/v1/contactscontacts:read

Newest 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.
Terminal window
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 }.

GET/v1/contacts/tagscontacts:read

Tags in use with how many contacts carry each, most used first, top 200. Tags compare case-insensitively.

Query Type Description
q string Tag prefix.
Terminal window
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 }] }
GET/v1/contacts/export.csvcontacts:read, logs:export

Streams 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.
Terminal window
curl "https://api.smsfabric.com/v1/contacts/export.csv?groupId=grp_t6w9z2c5f8i1l4o7r0u3x6a9" \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-o newsletter.csv
GET/v1/contacts/:idcontacts:read
Terminal window
curl 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.

PATCH/v1/contacts/:idcontacts:manage

Accepts 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.

Terminal window
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/v1/contacts/:idcontacts:manage

Erases 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.

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/contacts/con_a8d1g4j7m0p3s6v9y2b5e8h1 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"