Documentation

API Reference

SMS API Contacts API OTP API Voice API MMS API WhatsApp API Viber API

HTTP API

HTTP Contacts API

Contacts API

OPENSMS Contacts API helps you manage contacts that are identified by a unique random ID. Using this ID, you can create, view, update, or delete contacts. This API works as a collection of customer-specific contacts that allows you to group them and assign custom values that you can later use when sending SMS template messages.

The Contacts API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts

Parameters

Parameter	Required	Description
api_token	Yes	API Token From Developers option. Get API Token
Accept	Yes	Set to `application/json`
Content-Type	Yes	Set to `application/json`

Create a contact

Creates a new contact object. OPENSMS returns the created contact object with each request.

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts/{group_id}/store

Parameters

Parameter	Required	Type	Description
group_id	Yes	string	Contact Groups `uid`
PHONE	Yes	number	The phone number of the contact.
OTHER_FIELDS	No	string	All Contact's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the contact group fields configuration)

Example request

                                
curl -X POST https://www.opensms.co.ke/api/http/contacts/6065ecdc9184a/store \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"api_token":"YOUR_API_KEY",
"PHONE":"8801721970168",
"FIRST_NAME":"Jhon",
"LAST_NAME":"Doe",
}'

Returns

Returns a contact object if the request was successful.

                                
{
    "status": "success",
    "data": "contacts data with all details",
}

If the request failed, an error object will be returned.

                                
{
    "status": "error",
    "message" : "A human-readable description of the error."
}

View a contact

Retrieves the information of an existing contact. You only need to supply the unique contact uid and group uid that was returned upon creation or receiving.

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts/{group_id}/search/{uid}

Parameters

Parameter	Required	Type	Description
group_id	Yes	string	Contact Groups `uid`
uid	Yes	string	Contact `uid`

Example request

                                
curl -X POST https://www.opensms.co.ke/api/http/contacts/6065ecdc9184a/search/606732aec8705 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"api_token":"YOUR_API_KEY"}'

Returns

Returns a contact object if the request was successful.

                                
{
    "status": "success",
    "data": "contacts data with all details",
}

If the request failed, an error object will be returned.

                                
{
    "status": "error",
    "message" : "A human-readable description of the error."
}

Update a contact

Updates an existing contact. You only need to supply the unique uid of contact and contact group uid that was returned upon creation.

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts/{group_id}/update/{uid}

Parameters

Parameter	Required	Type	Description
group_id	Yes	string	Contact Groups `uid`
uid	Yes	string	Contact `uid`
PHONE	Yes	number	The phone number of the contact.
OTHER_FIELDS	No	string	All Contact's other fields: FIRST_NAME (?), LAST_NAME (?),... (depending on the contact group fields configuration)

Example request

                                
curl -X PATCH https://www.opensms.co.ke/api/http/contacts/6065ecdc9184a/update/606732aec8705 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"api_token":"YOUR_API_KEY",
"PHONE":"8801721970168",
"FIRST_NAME":"Jhon",
"LAST_NAME":"Doe",
}'

Returns

Returns a contact object if the request was successful.

                                
{
    "status": "success",
    "data": "contacts data with all details",
}

If the request failed, an error object will be returned.

                                
{
    "status": "error",
    "message" : "A human-readable description of the error."
}

Delete a contact

Deletes an existing contact. You only need to supply the unique contact uid and group uid that was returned upon creation.

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts/{group_id}/delete/{uid}

Parameters

Parameter	Required	Type	Description
group_id	Yes	string	Contact Groups `uid`
uid	Yes	string	Contact `uid`

Example request

                                
curl -X DELETE https://www.opensms.co.ke/api/http/contacts/6065ecdc9184a/delete/606732aec8705 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"api_token":"YOUR_API_KEY"}'

Returns

Returns a contact object if the request was successful.

                                
{
    "status": "success",
    "data": "contacts data with all details",
}

If the request failed, an error object will be returned.

                                
{
    "status": "error",
    "message" : "A human-readable description of the error."
}

View all contacts in group

API Endpoint

                                
                                    https://www.opensms.co.ke/api/http/contacts/{group_id}/all

Parameters

Parameter	Required	Type	Description
group_id	Yes	string	Contact Groups `uid`

Example request

                                
curl -X POST https://www.opensms.co.ke/api/http/contacts/6065ecdc9184a/all \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"api_token":"YOUR_API_KEY"}'

Returns

Returns a contact object if the request was successful.

                                
{
    "status": "success",
    "data": "contacts data with pagination",
}

If the request failed, an error object will be returned.

                                
{
    "status": "error",
    "message" : "A human-readable description of the error."
}