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.
The group object
Section titled “The group object”| 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 |
List groups
Section titled “List groups”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. |
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}Create a group
Section titled “Create a group”POST
/v1/contact-groupscontacts:manageReturns 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. |
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. |
Retrieve a group
Section titled “Retrieve a group”GET
/v1/contact-groups/:idcontacts:readcurl 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_….
Update a group
Section titled “Update a group”PATCH
/v1/contact-groups/:idcontacts:manageTakes name and description, both optional, with the create constraints. Returns the group. 409 group_exists on a duplicate name.
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 a group
Section titled “Delete a group”DELETE
/v1/contact-groups/:idcontacts:manageDeletes the group. Its contacts stay. Returns 204.
curl -X DELETE https://api.smsfabric.com/v1/contact-groups/grp_t6w9z2c5f8i1l4o7r0u3x6a9 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Add members
Section titled “Add members”POST
/v1/contact-groups/:id/memberscontacts:manageAdds 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. |
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 }Remove members
Section titled “Remove members”POST
/v1/contact-groups/:id/members/removecontacts:manageSame body and response as Add members. changed counts the contacts removed.
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 }