API Documentation

Premium SMS / Nigeria Direct Carrier Billing

User Detection & Subscription in Nigeria

To subscribe a user in Nigeria, for Direct Carrier Billing, we must perform two separate steps.

  1. Redirect the user to the MSISDN Detection platform which will return to us ( if successful ) the Network and the User ID.
  2. Call the Subscribe method on the API providing the UserID and the ServiceID.

Requesting the UserID

To request the UserID, you should have the following information ready:

  • Return URL (Your FULL URL, including the http://... . User will be sent back to this url upon completion.)
  • MTN Product ID (required for detecting MTN customers)
  • Your Reference ID (optional)

Flow: Redirect the user to the Lookup URL. Once the lookup is preformed, user will be sent back to your Return URL


The user will return to the given Return URL with the following (GET) parameters appended.

Attribute Example Description
status success / failed Describing the status of the lookup
userid abcd4321_-$ Returned only if status==success! A ASCII value unique to this subscriber, instead of the MSISDN.
network mtnng / etisalatng Returned only if status==success! Network name for the subscriber
message Returned only if status==failed! Error description


On Successful detection user will return to your domain:


On failure, user will return to your domain while:


Subscribing the User to the Service

Once you have the UserID you can request a subscription to your service. For this you can use our NetworkSubscription API.

For subscribing a MTN Customer request:

GET: https://content.mobivate.com/lookup/subscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}

For subscribing a Etisalat Customer request:

GET: https://content.mobivate.com/lookup/subscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}

Where the required parameters are:

Parameter Description
userid The userid that was sent to your Return URL
keyword The ProductID that you wish to subscribe the user to. Bare in mind, if subscribing the user to MTNNG, you must use the same MTN_PRODUCT_ID as you did when requesting the USER ID

The Response All requests will return HTTP Code 200 and a JSON body.


On Success:

  subscribed: true,
  message: "Subscription request has been accepted!",
  code: 202

or on Failure:

  subscribed: false,
  message: "Execution Error: Invalid Ad Id",
  code: 400

Unsubscribing user from the Service

Unsubscription works the same way the Subscription request does except the URL endpoint is slightly different.

For un-subscribing a MTN Customer request:

GET: https://content.mobivate.com/lookup/unsubscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}

For un-subscribing a Etisalat Customer request:

GET: https://content.mobivate.com/lookup/unsubscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}

Error Codes

Code Description
202 Request has been accepted
400 Execution Error: ...
409 Network Generated Error (custom message follows)
417 Invalid response received
501 Unknown network
600 Missing UserID or Keyword parameters
601 Request failed for unknown reason

Delivery Notifications

On successfully billed request, a notification will be sent to your nominated URL.


GET: http://www.yourdomain.com/nigeria-notifications?user-identity=$abcd1234$&service-id=xyz&status=1

Where the possible status codes are:

Status Description
0 New subscription started
1 Positive Billing
2 Failed Billing, Insufficient funds
3 Inactive Subscription, User opted out

← Previous Page - Next Page →