Skip to content

Contact groups

A group is a static list: contacts join and leave only through these endpoints, through groupIds when you create a contact, or through an import’s groupId. Campaigns target groups with groupIds.

Field Type Description
id string grp_…
name string Unique in your organization.
description string or null
memberCount integer Contacts in the group.
createdAt, updatedAt string
GET/v1/contact-groupscontacts:read
Query Type Description
q string Text contained in the name.
limit integer 1 to 200, default 50.
cursor string nextCursor from the previous page.
Terminal window
curl https://api.smsfabric.com/v1/contact-groups \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"data": [
{
"id": "grp_t6w9z2c5f8i1l4o7r0u3x6a9",
"name": "Newsletter",
"description": "Signed up on the website",
"memberCount": 4210,
"createdAt": "2026-09-14T12:00:00.000Z",
"updatedAt": "2026-11-18T16:22:10.000Z"
}
],
"nextCursor": null
}
POST/v1/contact-groupscontacts:manage

Returns 201 with the group. Supports Idempotency-Key.

Body field Type Required Constraints
name string Yes 1 to 120 characters, unique.
description string No Up to 500 characters.
Terminal window
curl https://api.smsfabric.com/v1/contact-groups \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Newsletter", "description": "Signed up on the website"}'
Error When
409 group_exists A group with this name exists.
GET/v1/contact-groups/:idcontacts:read
Terminal window
curl https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

Returns the group. List its members with GET /v1/contacts?groupId=grp_….

PATCH/v1/contact-groups/:idcontacts:manage

Takes name and description, both optional, with the create constraints. Returns the group. 409 group_exists on a duplicate name.

Terminal window
curl -X PATCH https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9 \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"description": "Website sign-ups since September"}'
DELETE/v1/contact-groups/:idcontacts:manage

Deletes the group. Its contacts stay. Returns 204.

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/contact-groups/:id/memberscontacts:manage

Adds up to 1,000 contacts. Contacts already in the group are ignored. Ids that aren’t contacts of your organization are counted in notFound and never linked. Returns 200.

Body field Type Required Constraints
contactIds string[] Yes 1 to 1,000 unique ids.
Terminal window
curl https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9/members \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactIds": ["con_a8d1g4j7m0p3s6v9y2b5e8h1", "con_b9e2h5k8n1q4t7w0z3c6f9i2"]}'
{ "changed": 2, "notFound": 0, "memberCount": 4212 }
POST/v1/contact-groups/:id/members/removecontacts:manage

Same body and response as Add members. changed counts the contacts removed.

Terminal window
curl https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9/members/remove \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contactIds": ["con_b9e2h5k8n1q4t7w0z3c6f9i2"]}'
{ "changed": 1, "notFound": 0, "memberCount": 4211 }