Documentation

Network Double Opt-in (NDOI)

To initiate a subscription on the network side (Network DOI), you should call the following API request:

GET:
/api/doi/<account_id>/<api_key>/?source=<shortcode>&destination=<msisdn>&keyword=<kw>&frequency=7&amount=100&campaign=Test&reference=<your internal reference>

Upon submitting the request, you will receive an HTTP 200 Accepted status and either a Reference ID or Error code as a response.

On Accepted (Message reference):

MT-c65561314eb34088b6df42d8241aace0

On Failed / Auto-receipted (Error Code)

541

Asynchronous Final Notification

Asynchronous final notification will be delivered to your standard DR Path with codes:

CodeDescriptionYour action…
540DOI Confirmed by userContinue with the subscription (ie. send welcome messages and content)
541Message delayed while waiting for DOIExisting NDOI exists. Please hold before retrying.
542Message rejected due to DOIThe user has not confirmed the NDOI yet. Please wait before retrying.
543DOI Unconfirmed / Awaiting user actionThe user has not confirmed the NDOI yet. Please wait before retrying.
544DOI Declined by userThe user declined NDOI. You should wait for the user to initiate a request again.
545DOI FailedNetwork DOI failed. Try again or contact Mobivate support to investigate further.

For the full list of Response codes, please see here


Request Parameters

The following GET parameters are required when submitting the N-DOI request.

ParameterFormatDescription
sourceNumberService Number / Shortcode
destinationNumberSubscribers number / MSISDN
keywordStringProductID / ServiceID / Keyword. Formats may vary depending on the country
campaignStringCampaign name
frequencyNumberWeekly billing frequency
amountNumberAmount billed per message, in cents


Keyword Patterns per country

You must submit the keyword parameter with each of your requests. These keyword patters depend on the country. You should maintain an up-to-date list of your provisioned keywords. You can get the updated list at any time from your account manager.

CountryFormatPatternExample
South Africa{ServiceID}([a-z0-9]+)43292zpz58124
Kenya{ProductID}:{ServiceID}([a-z0-9]+):([0-9]+)MDSP2000060241:6013442000004456
Ghana{Keyword}:{ServiceID}([a-z0-9]+):([0-9]+)games:23301220000010596

Unsubscribing

To unsubscribe a user, issue the same request for subscription (/api/doi/…), on add “&stop=1” to the parameters