Contacts

Programmatically save new contacts to your Cecula account, update existing contact details, or delete contacts that are no longer needed. This API also enables you to add or remove contacts from specific groups you manage. Additionally, you can retrieve a list of all contacts or see which groups a contact belongs to, allowing for better segmentation and targeted messaging.

Save Contact

This endpoint is used to save contact information. If a contact has been previously saved with the submitted mobile number, the contact information will be overwritten.

Endpoint

• Path: /contact/save
• Method: POST

Sample Request

{
    "first_name": "Godwin",
    "family_name": "Archibong",
    "organization": "Cecula Limited",
    "mobile": "0818xxxxxxx",
    "email": "[email protected]"
}

See http request code snippet in your programming language:

curl --location 'https://app.cecula.com/api/contact/save' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Godwin",
    "family_name": "Archibong",
    "organization": "Cecula Limited",
    "mobile": "0818xxxxxxx",
    "email": "[email protected]"
}'

Sample Response

{
    "reference": "625a973a-63fe-4f7d-a56b-3604c8a6b56a",
    "new": true,
    "message": "Contact Added"
}

Full List of Fields

Refer to the table below for full list of fields that can be submitted for each contact.

Field	Data Type	Description	Required
mobile	String	The mobile number of the contact	Yes
email	String	The email address of the contact	No
first_name	String	The given name of the contact	Yes
family_name	String	The family name (surname) of the contact	No
other_names	String	Middle-name, nickname or any other name	No
whatsapp_number	String	The contact's Whatsapp number	No
viber_number	String	The contact's Viber number	No
skype_id	String	The contact's skpe username	No
organization	String	The name of the organization	No
groups	Array	An array of the groups the contact should be enlisted on	No

List Contacts

This endpoint returns a paginated list of saved contacts in alphabetical order.

Endpoint

• Path: /contacts
• Method: GET

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

Response

{
    "data": [
        {
            "uuid": "19e2710e-9d5b-4a97-b246-9780528c4415",
            "first_name": "Akaninyene",
            ...
        },
        {
            "uuid": "c9381744-ed84-4214-9728-72454dd52527",
            "first_name": "Godwin",
            ...
        },
        ...
    ],
    "meta": {
        "search": "",
        "total": 38,
        "skipped": 0,
        "perPage": 25,
        "page": 1,
        "pageCount": 2
    }
}

💡 Help with Meta Object

The meta object bears page-context information. Click Here for description of each property.

Contact Details

Returns detailed information about the referenced contact.

Endpoint

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

curl --location 'https://app.cecula.com/api/contact/0708cf65-4f0d-463c-9abb-942baf6edd40' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Sample Response

{
    "contact": {
        "uuid": "0708cf65-4f0d-463c-9abb-942baf6edd40",
        "phone": "08146xxxxxx",
        "email": "[email protected]",
        "first_name": "Akaninyene",
        "family_name": "",
        "other_names": "",
        "gender": "O",
        "organization": "",
        "skype_id": null,
        "whatsapp_number": null,
        "viber_number": null,
        "facebook": null,
        "twitter": null,
        "linkedin": null,
        "groupme": null,
        "wechat": null,
        "youtube": null,
        "self_subscribed": 0
    },
    "groups": [
        {
            "uuid": "02da72b4-dad3-4afb-a11f-55426470f4f1",
            "name": "Demo3"
        }
    ]
}

Contact Groups

Returns an array of the groups a contact belongs to. This list only displays the group name and reference. For details about the group, user Group Details endpoint.

Endpoint

• Path: /contact/{contacts-reference}/groups
• Method: GET

curl --location 'https://app.cecula.com/api/contact/0708cf65-4f0d-463c-9abb-942baf6edd40/groups' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json'

Sample Response

[
    {
        "uuid": "02da72b4-dad3-4afb-a11f-55426470f4f1",
        "name": "Demo3"
    }
]

Delete Contact

Use this endpoint to permanently delete a contact. This additionally, removes the contact from all groups it has been enrolled to.

Endpoint

• Path: /contact/{contacts-reference}
• Method: DELETE

curl --location --request DELETE 'https://app.cecula.com/api/contact/19e2710e-9d5b-4a97-b246-9780528c4415' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \

Sample Respones

{
    "status": "success"
}