Groups

Quickly create groups to segment your contacts. Need to update a group's name or details? No problem—you can edit groups dynamically as your contact structure evolves. The API also makes it easy to list all your existing groups, so you can easily retrieve references and keep track of everything in one place. And when a group is no longer relevant, you can clean up by deleting it without hassle.

Create Group

Endpoint

Path: /contact/group/create
Method: POST

Sample Request

json

{
    "name": "Leads",
    "description": "New website signups"
}

bash

curl --location 'https://app.cecula.com/api/contact/group/create' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Leads",
    "description": "New website signups"
}'

Sample Response

json

{
    "reference": "2f4f0083-b7e0-404a-86e2-b33dc77947f1",
    "new": true,
    "message": "Group Created"
}

If you had previously created a group with the same new, the response will indicated as follows:

json

{
    "reference": "2f4f0083-b7e0-404a-86e2-b33dc77947f1",
    "new": false,
    "message": "Group Exists"
}

Full List of Fields

Field	Data Type	Description	Required
name	String	Group name	Yes
description	String	Group description	No
subscribable	Boolean	Indicates if users can subscribe/unsubscribe to the group via SMS sent to your hosted SIM. [Defaults to False]	No
subscription_autoresponse	String	Auto-response SMS sent to users upon subscribing to the group.	No
unsubscribe_autoresponse	String	Auto-response SMS sent when a user unsubscribes.	No
optin_code	String	Code received via SMS to subscribe a user to the group.	No
optout_code	String	Code received via SMS to unsubscribe a user from the group.	No
subscription_sim	String	Your SIM hosted with Cecula Sync, used to receive OPT-IN and OPT-OUT requests.	No

List Groups

Endpoint

Path: /contact/groups
Method: GET

bash

curl --location 'https://app.cecula.com/api/contact/groups' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Sample Response

json

{
    "data": [
        {
            "uuid": "e13955a0-6742-4b6a-8f04-433a2ee06270",
            "name": "Demo2",
            "description": "Second group for testing bulk contacts upload"
        },
        {
            "uuid": "02da72b4-dad3-4afb-a11f-55426470f4f1",
            "name": "Demo3",
            "description": "A third try at performance"
        }
    ],
    "meta": {
        "search": "",
        "total": 2,
        "skipped": 0,
        "perPage": 25,
        "page": 1,
        "pageCount": 1
    }
}

💡 Need Help?

For in-depth on dataset management, we highly recommend you read up and understand Fetching Records.

Group Details

Endpoint

Path: /contact/group/{group-reference}
Method: GET

bash

curl --location 'https://app.cecula.com/api/contact/group/c21e0aba-986a-4f84-befe-c826624e6481' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Sample Response

json

{
    "group": {
        "name": "Demo2",
        "uuid": "e13955a0-6742-4b6a-8f04-433a2ee06270",
        "group_type": null,
        "description": "Second group for testing bulk contacts upload",
        "subscription_object": 0,
        "subscribable": 0,
        "subscription_autoresponse": null,
        "unsubscribe_autoresponse": null,
        "subscription_sim": null,
        "optin_code": null,
        "optout_code": null,
        "created_at": "2024-10-31T01:50:29.000000Z",
        "updated_at": "2024-10-31T01:50:29.000000Z"
    },
    "contacts_endpoint": "https://app.cecula.com/api/contact/group/e13955a0-6742-4b6a-8f04-433a2ee06270/contacts"
}

Edit Group

Endpoint

Path: /contact/group/{group-reference}/update
Method: PATCH

Sample Request Body

json

{
    "description": "Where only the most curious, the most daring, and the most exclusive contacts gather!",
    "subscribable": true
}

bash

curl --location --request PATCH 'https://app.cecula.com/api/contact/group/02da72b4-dad3-4afb-a11f-55426470f4f1/update' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "description": "Where only the most curious, the most daring, and the most exclusive contacts gather!",
    "subscribable": true
}'

Response

json

{
    "status": "success"
}

Save Contact to Group

Endpoint

Path: /contact/group/{group-reference}/add-contacts
Method: POST

Add Single Contact

json

{
    "contacts": [
        {
            "first_name": "Akaninyene",
            "family_name": "",
            "email": "[email protected]",
            "mobile": "09090000246"
        }
    ]
}

bash

curl --location 'https://app.cecula.com/api/contact/group/02da72b4-dad3-4afb-a11f-55426470f4f1/add-contacts' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contacts": [
        {
            "first_name": "Akaninyene",
            "family_name": "",
            "email": "[email protected]",
            "mobile": "09090000246"
        }
    ]
}'

Add Multiple Contacts

json

{
    "contacts": [
        {
            "first_name": "Adewale",
            "family_name": "Morgan",
            "mobile": "08137922234"
        },
        {
            "first_name": "Hillary",
            "family_name": "",
            "mobile": "08137922235"
        }
    ]
}

bash

curl --location 'https://app.cecula.com/api/contact/group/02da72b4-dad3-4afb-a11f-55426470f4f1/add-contacts' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "contacts": [
        {
            "first_name": "Adewale",
            "family_name": "Morgan",
            "mobile": "08137922234"
        },
        {
            "first_name": "Hillary",
            "family_name": "",
            "mobile": "08137922235"
        }
    ]
}'

Response

json

{
    "status": "successful"
}

For full list of contact data that can be refer to the Contact Fields Table

List Group Contacts

Endpoint

Path: /contact/group/{group-reference}/contacts
Method: GET

bash

curl --location 'https://app.cecula.com/api/contact/group/c21e0aba-986a-4f84-befe-c826624e6481/contacts' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Sample Response

json

{
    "data": [
        {
            "uuid": "19e2710e-9d5b-4a97-b246-9780528c4415",
            "first_name": "Adewale",
            "family_name": "Morgan",
            "other_names": "",
            "mobile": "08137922234",
            "email": "[email protected]",
            "organization": "",
            "gender": "O"
        },
        {
            "uuid": "c9381744-ed84-4214-9728-72454dd52527",
            "first_name": "Hillary",
            "family_name": "",
            "other_names": "",
            "mobile": "08137922235",
            "email": "",
            "organization": "",
            "gender": "O"
        }
    ],
    "meta": {
        "search": "",
        "total": 2,
        "skipped": 0,
        "perPage": 25,
        "page": 1,
        "pageCount": 1
    }
}

💡 Need Help?

For in-depth on dataset management, we highly recommend you read up and understand Fetching Records.

Delist Contacts

Endpoint

Path: /contact/group/{group-reference}/delist-contacts
Method: DELETE

Request Body

json

{
    "contacts": [
        "08137922234",
        "08137922235"
    ]
}

bash

curl --location --request DELETE 'https://app.cecula.com/api/contact/group/02da72b4-dad3-4afb-a11f-55426470f4f1/delist-contacts' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "contacts": [
        "08137922234",
        "08137922235"
    ]
}'

Response

json

{
    "status": "success",
    "message": "The submitted contacts have been delisted from Demo3."
}

Delete Group

Endpoint

Path: /contact/group/{group-reference}
Method: DELETE

bash

curl --location --request DELETE 'https://app.cecula.com/api/contact/group/e13955a0-6742-4b6a-8f04-433a2ee06270' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Response

json

{
    "status": "success"
}

SMS Messaging

Contacts Management

Responses

Groups

Create Group

Endpoint

Sample Request

Sample Response

Full List of Fields

List Groups

Endpoint

Sample Response

Group Details

Endpoint

Sample Response

Edit Group

Endpoint

Sample Request Body

Response

Save Contact to Group

Endpoint

Add Single Contact

Add Multiple Contacts

Response

List Group Contacts

Endpoint

Sample Response

Delist Contacts

Endpoint

Request Body

Response

Delete Group

Endpoint

Response

Groups ​

Create Group ​

Endpoint ​

Sample Request ​

Sample Response ​

Full List of Fields ​

List Groups ​

Endpoint ​

Sample Response ​

Group Details ​

Endpoint ​

Sample Response ​

Edit Group ​

Endpoint ​

Sample Request Body ​

Response ​

Save Contact to Group ​

Endpoint ​

Add Single Contact ​

Add Multiple Contacts ​

Response ​

List Group Contacts ​

Endpoint ​

Sample Response ​

Delist Contacts ​

Endpoint ​

Request Body ​

Response ​

Delete Group ​

Endpoint ​

Response ​

Groups

Create Group

Endpoint

Sample Request

Sample Response

Full List of Fields

List Groups

Endpoint

Sample Response

Group Details

Endpoint

Sample Response

Edit Group

Endpoint

Sample Request Body

Response

Save Contact to Group

Endpoint

Add Single Contact

Add Multiple Contacts

Response

List Group Contacts

Endpoint

Sample Response

Delist Contacts

Endpoint

Request Body

Response

Delete Group

Endpoint

Response