API documentation for Oramobile

You can get details about your registered sender IDs. The information includes the sender name, sender type (promotional or transactional), date created and status. It also includes gateways registered.

This is used to get a single sender ID details

Base URL: https://api.mobilesasa.com/v1/senders/load-details

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

{
    "senderID": "MOBILESASA"
}

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/senders/load-details' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "senderID": "MOBILESASA"
}'

{
    "status": true,
    "responseCode": "0200",
    "payload": {
        "senderID": "BITWISE",
        "senderType": "Promotional",
        "senderStatus": "Active",
        "senderCreatedAt": "2021-04-30 18:22:18",
        "senderGateways": [
            "Safaricom",
            "Airtel"
        ]
    }
}

Sender Type is either Promotional or Transactional. senderGateways are the networks on which the sender is mapped.

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

This is used to get all registered sender ID details

Base URL: https://api.mobilesasa.com/v1/senders/load-all

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json body should be empty

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/senders/load-all' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data ''

{
    "status": true,
    "responseCode": "0200",
    "payload": [
        {
            "senderID": "SENDER1",
            "senderType": "Transactional",
            "senderStatus": "Active",
            "senderCreatedAt": "2021-03-19 12:08:44",
            "senderGateways": ["Safaricom", "Airtel"]
        },
        {
            "senderID": "SENDER2",
            "senderType": "Promotional",
            "senderStatus": "Active",
            "senderCreatedAt": "2021-04-30 18:22:18",
            "senderGateways": ["Safaricom", "Airtel"]
        },
        {
            "senderID": "SENDER3",
            "senderType": "Transactional",
            "senderStatus": "Active",
            "senderCreatedAt": "2021-05-25 17:10:42",
            "senderGateways": ["Safaricom", "Airtel", "Airtouch (Telkom)"]
        }
    ]
}

Sender Type is either Promotional or Transactional. senderGateways are the networks on which the sender is mapped.

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

Short codes are 5-digit numbers such as 23358 that provide two way SMS communication. This enables an organization to automate communication via SMS. This can be used to provide feedback, perform customer care functions among many other uses.

You can receive SMS details sent to the short code by providing us a callback URL where the details are sent to. A Json payload is sent to the end point as below:

{
   "reference": "0128b6d6-db68-4bc2-868d-4acc0c93c72a",
   "shortCode": "23358",
   "msisdn": "254723xxxxxx",
   "message": "This is a sample message",
   "receivedAt": "20240312095937"
}

The parameters are explained below:

Parameter Name	Description	Example
reference	The unique identifier of the message	0128b6d6-db68-4bc2-868d-4acc0c93c72a
shortCode	Your registered short code number	23358
msisdn	Sender phone number	254722002222
message	Message sent by the sender	This is a sample message
receivedAt	Time the message was sent by sender	20240312095937

To enable sending out short code messages, for example, to automate replies, the short code is registered as an SMS sender ID. You can therefore send out SMS using the send SMS options explained in the first section and use the short code as the senderId.

Groups are used to segment contacts. A group can have contacts with phone, name and email. You can add and delete contacts from group.

This is used to get a list of registered groups in an account.

NOTE: Send a GET request to get groups

Base URL: https://api.mobilesasa.com/v1/groups

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json body should be empty

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/groups' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE'

{
    "status": true,
    "responseCode": "0200",
    "groups": [
        {
            "groupId": "9b51731e-2ed4-4649-8ba8-7be1c4a56345",
            "name": "Test Group"
        }
    ]
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

You can automatically add contacts to group. If the contact (phone number) exists, the name and email will be updated

Base URL: https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/add-contact

NOTE: The group UUID should be passed in the URL. Send a POST request

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

{
    "phone": "0705xxxxxx",
    "name": "Test Contact",
    "email": "aguvasucyril@gmail.com"
}

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/add-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "phone": "0705xxxxxx",
    "name": "Test Contact",
    "email": "test@gmail.com"
}'

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact Added"
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

You can automatically delete contact from group.

Base URL: https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/remove-contact

NOTE: The group UUID should be passed in the URL. Send a DELETE request

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

{
    "phone": "0705xxxxxx"
}

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/remove-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "phone": "0705xxxxxx"
}'

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact deleted!"
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

Birthday/Anniversary groups are used to segment birthdays. Each group can have a different message and time to send. You can add and delete contacts from group.

This is used to get a list of registered Birthday/Anniversary groups in an account.

NOTE: Send a GET request to get groups

Base URL: https://api.mobilesasa.com/v1/anniversary-groups

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json body should be empty

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/anniversary-groups' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE'

{
    "status": true,
    "responseCode": "0200",
    "groups": [
        {
            "groupId": "4ce17108-e08f-4353-87ad-180166db8bba",
            "name": "Test Anniversary1",
            "description": "Testing anniversaries",
            "contactsCount": 3
        },
        {
            "groupId": "38abc713-c7c4-445c-ba05-ab9ecca64b7b",
            "name": "Test Anniversary2",
            "description": "All Bitwise Staff",
            "contactsCount": 7
        },
        {
            "groupId": "277947fc-b606-46fb-9d54-c7e195a110ac",
            "name": "Test Anniversary3",
            "description": "birthdays",
            "contactsCount": 1
        },
        {
            "groupId": "17194005-e137-4568-9b4b-0970b23d652d",
            "name": "Test Anniversary4",
            "description": "These are my friends.",
            "contactsCount": 7
        }
    ]
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

You can automatically add a birthday/anniversary date to a group. If the contact (phone number) exists, the name and date will be updated

Base URL: https://api.mobilesasa.com/v1/anniversary-groups/GROUP-UUID-HERE/add-contact

NOTE: The group UUID should be passed in the URL. Send a POST request

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

{
    "phone": "0705xxxxxx",
    "name": "John Doe",
    "date": "25-12-1990"
}

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/anniversary-groups/GROUP-UUID-HERE/add-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "phone": "0705xxxxxx",
    "name": "Test Contact",
    "date": "25-12-1990"
}'

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact Updated"
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

You can automatically delete contact from group.

Base URL: https://api.mobilesasa.com/v1/anniversary-groups/GROUP-UUID-HERE/remove-contact

NOTE: The group UUID should be passed in the URL. Send a DELETE request

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

{
    "phone": "0705xxxxxx"
}

Below is a sample CURL request

curl --location 'https://api.mobilesasa.com/v1/anniversary-groups/GROUP-UUID-HERE/remove-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "phone": "0705xxxxxx"
}'

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact deleted!"
}

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}