SMS Africa and Middle East 2.0

English version below

===============================================================================================

Version française

1. Souscription à une API
2. Achat de bundles
3. Envoi de SMS
   3.1 Envoi de SMS avec un sender name par defaut
   3.2 Envoi de SMS avec un sender name personnalisé
   3.3 Envoi de SMS on-net
4. A propos des accusés de réception
5. Administration de votre compte
   5.1 Votre solde de SMS
   5.2 Bilan d'usage des SMS
   5.3 Historique des achats

1. Souscription à une API

Avant toute chose, vous devez obtenir des identifiants pour votre application/service depuis ce portail, indiquer les pays que vous souhaitez cibler et acheter un ou plusieurs bundles, c'est-à-dire des crédits d'envoi.

Notez que vous pouvez contacter à tout moment les équipes locales d'Orange depuis ce formulaire pour demander

• "Sender name" - l'enregistrement d'une liste de sender names (sous réserve d’acceptation par l'équipe locale d'Orange ; une preuve que vous êtes autorisé à utiliser chacun des sender names demandés sera requise) ;
• "Larger volumes" - acheter des volumes plus importants que ceux proposés via les bundles ;
• "SMS response" - nous transmettre une URL sur laquelle vous allez pouvoir recevoir les SMS de vos clients ;
• "Real time SMS DR" - nous transmettre une URL pour recevoir le notification d'envoi de SMS (delivery receipt - veuillez consulter la rubrique "Note importante à propos du SMS DR Status" plus bas pour mieux comprendre le fonctionnement de ces accusés de réception).

Après avoir déclaré votre application, associé la ou les APIs SMS et payé votre pack / bundle, vous pouvez démarrer les étapes suivantes.

Une fois que vous avez souscrit à l'API à partir de votre application sur ce portail, pour utiliser l'API, vous devrez vous authentifier à l'aide d'un token OAuth 2.0 v3. Le token a une durée de validité d'une heure, aussi veuillez noter que votre application doit mettre en œuvre un mécanisme permettant de le renouveler automatiquement à chaque fois qu'il expire.

Les credentials (ID client, secret client) permettant de générer le token et d'utiliser l'API se trouvent dans la section "MyApps" de ce site Web, comme le montre la capture d'écran ci-dessous.

curl -X POST \
-H "Authorization: {{authorization_header}}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

Note : le flag -d entraine implicitement le format : application/x-www-form-urlencoded

Vous recevez alors des données au format JSON, dont vous pouvez extraire votre {{access_token}}:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "access_token": "{{access_token}}",
    "expires_in": "3600"
}

Bonnes pratiques pour les tokens

L'access_token a une durée de vie de 3600 secondes, soit 1 heure. Donc vous n'avez pas besoin d'en redemander un nouveau avant chaque envoi de SMS. Il vous suffit de bien gérer les erreurs potentielles dans vos futurs appels, notamment pour détecter l'erreur de type out-of-date comme ci-dessous :

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

Dans ce cas, il vous suffit de redemander un nouveau token. Pour plus d'information sur les erreurs potentielles, merci de consulter le guide complet.

2. Achat de bundles

Afin de faciliter la découverte des APIs SMS et leur intégration dans votre service, Orange vous propose l'achat d'un Starter bundle ou pack de démarrage à très bas prix, directement depuis votre abonnement mobile. Veuillez noter que ce pack ne peut être acheté qu'une seule fois par compte Orange Developer et numéro de téléphone mobile de développeur.

3. Envoi de SMS

En supposant que vous avez déclaré votre application, que vous avez souscrit à la ou les API SMS souhaitées et que vous avez acheté votre bundle, vous pouvez maintenant commencer à envoyer des SMS à vos clients. Voici les informations techniques dont vous aurez besoin :

Token url : https://api.orange.com/oauth/v3/token Messaging base-url : https://api.orange.com/smsmessaging/v1 Contract management base-url : https://api.orange.com/sms/admin/v1

Note : Vous devez avoir un contrat avec une date d'expiration valide et un solde positif. Si votre contrat a expiré ou si vous n'avez plus d'unités, vous devez acheter un nouveau bundle comme décrit ci-dessus, sinon vous recevrez un message d'erreur.
Le TPS est limité à 5 SMS par seconde.

Il existe deux façons d'envoyer des SMS : soit avec le sender name par défaut, soit avec un sender name personnalisé.

Pour envoyer un SMS à {{recipient_phone_number}}, vous devez simplement utiliser votre {{access_token}}, indiquer le {{country_sender_number}} comme senderAddress dans le corps de la requête et au niveau de l'url avec votre code pays mais sans préfixe + ou 00 - un tableau avec les valeurs recommandées pour ce paramètre se trouve plus bas sur cette page.

3.1. Envoi de SMS avec un sender name par defaut

Veuillez noter qu'un sender name par défaut sera automatiquement fixé par notre plate-forme lors de la souscription à l'API. Ce nom est lié à votre compte Orange Developer.

Pour envoyer un SMS à {{recipient_phone_number}}, vous devez simplement utiliser votre {{access_token}}, indiquer le {{country_sender_number}} comme senderAddress dans le corps de la requête et au niveau de l'url avec votre code pays mais sans préfixe + ou 00.

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "outboundSMSTextMessage":{ \
            "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

Le {{country_sender_number}} est mentionné deux fois : dans le corps (body) et dans l'url (endpoint) où tel:+ est encodé ainsi : tel%3A%2B (url-encoded).

3.2 Envoi de SMS avec un sender name personnalisé

Si vous souhaitez utiliser des sender names personnalisés, vous devez contacter l'équipe locale d'Orange, via ce formulaire.

Par exemple, si vous avez demandé l'ajout du sender name "MonService" et que cela été validé par l'équipe locale Orange, pour envoyer des SMS avec le sender name "MonService", vous devrez faire un appel comme suit :

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
                "senderName": "MonService", \
        "outboundSMSTextMessage":{ \
            "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

Note sur les sender names :
Les sender names sont limités à 11 caractères alphanumériques ou espaces ; les caractères spéciaux ne sont pas autorisés.
Vous pouvez consulter les sender names autorisés pour votre contrat dans l'écran Configurer de votre application sur ce portail.
Si vous essayez d'utiliser un sender name qui n'a pas été approuvé et white-listé sur notre plateforme, vous obtiendrez une erreur : 400 requestError.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.orange.com/smsmessaging/v1/outbound/tel:+{{recipient_phone_number}}/requests/{{resource_id}}
Content-Length: 12345
Date: Thu, 01 Avr 2015 02:38:38 GMT

{
    "outboundSMSMessageRequest":{
        "senderAddress":"tel:+{{recipient_phone_number}}",
        "senderName": "MonService",
        "outboundSMSTextMessage":{
            "message":"Hello!"
        },
        "resourceURL":"https://api.orange.com/smsmessaging/v1/outbound/tel:+{{recipient_phone_number}}/requests/{{resource_id}}"
    }
}

Vous obtenez en retour un {{resource_id}} comme unique identifiant (ID) que vous devez enregistrer si vous souhaitez par la suite le corréler avec d'autres informations, dont l'accusé de réception Delivery Receipt (DR). {{resource_id}} est une chaîne de caractères avec le format typique suivant : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

3.3 Envoi de SMS on-net

Dans certains pays, nous proposons une API différente pour envoyer des SMS vers le réseau Orange uniquement, à un tarif plus avantageux. Si vous souscrivez à cette API Orange Only, une fois que vous avez acheté un bundle de SMS, pour utiliser ces unités vous devez ajouter le paramètre suivant à vos requêtes : request resource_type_parameter_management=SMS_OCB2

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "outboundSMSTextMessage":{ \
           "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests?resource_type_parameter_management=SMS_OCB2"

Liste de country_sender_number par pays, avec un rappel du code standard ISO-3166 à trois lettres :

4. A propos des accusés de réception

Chaque SMS envoyé va déclencher l'émission d'un accusé de réception SMS DR (Delivery Receipt) dans les 24 heures qui suivent. Pour le recevoir, vous devez créer un end-point sur votre propre backend / serveur.

Votre end-point ou URL de backend doit :

• être sécurisée (par un certificat non auto-signé) et sous protocole https ;
• être accessible depuis l'Internet sur le PORT 443 ;
• retourner HTTP 200 OK pour confirmer la réception du SMS DR ;
• être 'connue' de notre plate-forme avant de pouvoir être utilisée ; pour ce faire, connectez-vous à votre compte Orange Developer et remplissez ce formulaire pour transmettre l'URL de votre backend à nos équipes. Une fois votre backend configuré sur la plate-forme Orange, notre équipe technique va vous transmettre une IP publique à white-lister de votre côté.

Note importante à propos du SMS DR Status
Si vous recevez un DeliveredToTerminal, cela signifie que le SMS a bien été envoyé et reçu par le téléphone.
Si vous recevez un DeliveryImpossible, votre SMS peut encore être délivré (par exemple si un téléphone n'était pas connecté au réseau et qu'il l'est à nouveau) ou pas (par exemple si votre SMS a été envoyé à un numéro fixe ou désactivé). Orange ne rembourse pas les SMS non délivrés.
Le fait qu'un SMS ne soit pas reçu ne signifie pas que l'API SMS d'Orange dysfonctionne. A partir du moment où vous recevez un retour, quel que soit le statut, cela veut dire que notre API fonctionne.

Exemple d'un SMS DR Request depuis Orange vers votre backend :

POST https://{{dev_host}}:443/orange/smsdr.php HTTP/1.1
Content-Type: application/json
{
    "deliveryInfoNotification":{
        "callbackData":"{{resource_id}}",
        "deliveryInfo":{
            "address":"tel:+{{recipient_phone_number}}",
            "deliveryStatus":"{{delivery_status}}"
        }
    }
}

Exemple de réponse :

HTTP/1.1 200 OK

Votre backend peut extraire 3 informations importantes du corps JSON de la requête venant d'Orange :

• {{resource_id}}: l'ID unique du SMS correctement envoyé
• {{recipient_phone_number}}: le numéro de téléphone (MSISDN) de son destinataire
• {{delivery_status}}: le status du SMS DR

L'attribut {{delivery_status}} peut prendre différentes valeurs :

5. Administration de votre compte

5.1 Votre solde de SMS

Depuis votre application ou votre espace d'administration, vous pouvez consulter votre solde de SMS, c'est-à-dire combien de SMS vous pouvez encore envoyer, mais aussi la date d'expiration de votre pack restant. Pour cela, il suffit de réutiliser votre {{access_token}} avec le endpoint /sms/admin/v1/contracts, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/contracts"

Cette requête retourne les données de votre solde SMS et la date d'expiration au format JSON :

[
    {
        "id": "6368bdba70585131d5454a5a",
        "type": "SELFSERVICE",  // or BROKER
        "developerId": "{{developerId}}",
        "applicationId": "{{applicationId}}",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "availableUnits": 120,
        "requestedUnits": 0,
        "status": "ACTIVE",   // or EXPIRED
        "expirationDate": "2023-01-07T15:04:20.653Z",
        "creationDate": "2022-11-07T08:11:38.220Z",
        "lastUpdateDate": "2022-12-08T15:04:20.656Z"
    }
]

Note : la réponse est un tableau avec un élément par pays. Ce tableau peut contenir plusieurs éléments si vous avez souscrit avec le même compte aux APIs SMS de plusieurs pays. Vous pouvez ajouter un paramètre optionnel pour filtrer la réponse par pays, avec /sms/admin/v1/contracts?country={{country_code}} où {{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici.

5.2 Bilan d'usage des SMS

Depuis votre application ou votre espace d'administration, vous pouvez consulter le nombre de SMS envoyés par application et par pays. Pour cela, il vous suffit de réutiliser votre {{access_token}} en appelant le end-point: /sms/admin/v1/statistics, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/statistics"

Cette requête retourne votre consommation de SMS par application (et par pays) au format JSON :

{
    "partnerStatistics": {
        "developerId": "{{developerId}}",
        "statistics": [
            {
                "service": "SMS_OCB",
                "serviceStatistics": [
                    {
                        "country": "CIV",
                        "countryStatistics": [
                            {
                                "appid": "yf1qyS4gv****",
                                "usage": 2,
                                "nbEnforcements": 2
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Vous pouvez ajouter 2 paramètres optionnels pour filtrer par pays et application : /sms/admin/v1/statistics?country={{country_code}}&appid={{app_id}}

• {{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici
• {{app_id}} est l'ID de votre application que vous pouvez retrouver dans votre tableau de bord sur ce portail.

5.3 Historique des achats

Vous pouvez retrouver l'historique de l'ensemble de vos achats de packs depuis votre compte. Pour cela, il vous suffit de réutiliser votre {{access_token}} en appelant le end-point : /sms/admin/v1/purchaseorders, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/purchaseorders"

Cette requête retourne votre historique d'achat de packs SMS par application (et par pays) au format JSON. Exemple :

[
    {
        "id": "6368bdba70585131d5454a5b",
        "developerId": "{{developerId}}",
        "contractId": "63***",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "bundleId": "6368b9b35455a62e00d9997a",
        "bundleDescription": "Bundle 0 - 20 SMS for 320 FCFA (Starter for 7 days)",
        "price": 320.00,
        "currency": "XOF",
        "purchaseDate": "2022-11-07T08:11:38.260Z",
        "paymentMode": "OTP_SMS_OCB",
        "paymentProviderOrderId": null,
        "payerId": "22507******",
        "type": "BUNDLE_PURCHASE",
        "oldAvailableUnits": 0,
        "newAvailableUnits": 20,
        "oldExpirationDate": "2022-11-07T22:59:59.000Z",
        "newExpirationDate": "2022-11-14T08:11:38.227Z"
    },
   {
        "id": "6391fcf45b1130****",
        "developerId": "{{developerId}}",
        "contractId": "63*****",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "bundleId": "6368b9b35455a62e00d9997d",
        "bundleDescription": "Bundle 1 - 100 SMS for 1 600 FCFA (for 30 days)",
        "price": 1600.00,
        "currency": "XOF",
        "purchaseDate": "2022-12-08T15:04:20.664Z",
        "paymentMode": "NOCHALLENGE_OM",
        "paymentProviderOrderId": "374213*****",
        "payerId": "{{developerEmail}}",
        "type": "BUNDLE_PURCHASE",
        "oldAvailableUnits": 20,
        "newAvailableUnits": 120,
        "oldExpirationDate": "2022-12-13T23:59:59.000Z",
        "newExpirationDate": "2023-01-07T15:04:20.653Z"
    },
]

Vous pouvez filtrer la réponse par pays en utilisant un paramètre optionnel : /sms/admin/v1/purchaseorders?country={{country_code}} où {{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici.

========================================

English version

With Orange SMS APIs and a few lines of code, you can easily send SMS, be notified on delivery receipts and manage your account as admin.

Table of contents

1. Subscribe to the API
2. Buy a bundle
3. Send SMS to your customers
   3.1 Send an SMS with the default senderName
   3.2 Send an SMS with a custom senderName
   3.3 Send on-net SMS
4. About SMS Delivery Receipt
5. Administer your account
   5.1 View your SMS balance
   5.2 View your purchase history
   5.3 SMS usage statistics

1. Subscribe to the API

Before you can send SMS, you must first register on this portal, create an application, subscribe to the API for the country where you want to send SMS, then buy some units (SMS bundle) either with your Orange SIM credit (airtime / DCB) or, in countries where it is available, with Orange Money (watch the tuto).

Once you have subscribed to the API from your application on this portal, in order to use the API you will need to authenticate using an OAuth 2.0 v3 token; the token will only be available for one hour, so please be aware that your application should implement a mechanism to automatically renew it each time the token expires.

The credentials (Client ID, Client secret) to generate the token and use the API can be found in the “MyApps” section of this website as shown in the screenshot below.

curl -X POST \
-H "Authorization: {{authorization_header}}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

Note : -d option implies application/x-www-form-urlencoded format. The response, containing the {{access_token}} will be in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "access_token": "{{access_token}}",
    "expires_in": "3600"
}

Full documentation on how to generate such a token can be found on this page 2-Legged OAuth2.0 Proxy V3.

Note: please do not generate a token for each call; reuse the same token for 60 minutes for all requests you need to make to this API. To do this, you should handle the out-of-date error type and generate a new token each time such an error occurs.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

2. Buy a bundle

Before you can send an SMS, you'll need to buy a bundle. Orange wants to make your integration easier, so we have created a starter bundle with some SMS at a very good price. Please note that this starter bundle can only be bought once per Orange Developer account or per Orange phone number you will be using for payment.

Example

3. Send SMS to your customers

Assuming you've declared your application with the relevant SMS API(s) and purchased your bundle, you can now start sending SMS to your customers.
Here's the technical information you'll need:

Token url: https://api.orange.com/oauth/v3/token
Messaging base-url : https://api.orange.com/smsmessaging/v1
Contract management base-url : https://api.orange.com/sms/admin/v1

Note: You must have a contract with a valid expiry date and a positive balance. If your contract has expired or you have no units left, you should purchase a new bundle as described above, otherwise you will receive an error message.
TPS is limited to 5 SMS per second.

There are two ways to send SMS: either with the default sender name or with a custom sender name.

To send an SMS to a {{recipient_phone_number}}, you just need to use your {{access_token}} and indicate the corresponding {{country_sender_number}} as senderAddress both in the body (prefixed by "tel:+") and in the URL (with "tel:+" URL encoded, i.e. "tel%3A%2B"); this number should be in international format, but without 00 - a table with recommended values for this parameter can be found further down this page.

3.1 Send an SMS with the default senderName

When you first subscribed to our API, we generated a default sender name associated with your account with the following format "SMS 123456" (you can view this by clicking on the Configure button (see above).

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "outboundSMSTextMessage":{ \
        "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

3.2 Send an SMS with a custom senderName

You can request additional sender names via this web form, but please note that this is subject to approval by the local Orange marketing team.

You can use a slightly different call, by adding the senderName parameter in the body, to send SMS from a specific sender name that was previously associated with your account.

Note on sender names:
Sender names are limited to 11 alphanumeric characters or spaces; special characters are not allowed.
You can consult the approved sender name in the Configure screen of your application on this portal.
If you try to use a sender name that hasn't been approved and whitelisted on our platform, you will get an error: 400 requestError.

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "senderName": "MonService", \
        "outboundSMSTextMessage":{ \
        "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

In both cases, the request will return Headers and JSON data with information about the SMS if it was sent successfully or an HTTP error with more information about the error in the JSON data. In case of success, in the response body you'll get a {{resource_id}}; you should save it if you want to correlate it with a Delivery Receipt (DR) later on; {{resource_id}} is a string with the following typical format: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

3.3 Send on-net SMS

In some countries, we have two different SMS offers for on-net and off-net SMS.
If you only need to send SMS to Orange customers, you should subscribe to the "Orange only" offer and buy SMS bundles for this offer.
To use these SMS you'll need to use a slightly different call, by adding the following parameter to your request resource_type_parameter_management=SMS_OCB2.

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "outboundSMSTextMessage":{ \
        "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests?resource_type_parameter_management=SMS_OCB2"

List of country_sender_number by country and standard ISO3 country code (ISO-3166):

4. About SMS Delivery Receipt

Each SMS sent will trigger an SMS DR (Delivery Receipt) over the next 24 hours.
If you want to be notified programmatically about these receipts, you'll need to implement an endpoint to receive and manage this receipt.
This backend should be notified to Orange and should meet the following conditions:

• be secured with a signed certificate and should start with https://

• be accessible via the Internet, on PORT 443 only

• must return an HTTP 200 OK in order to acknowledge the receipt

• must be **whitelisted ** on the Orange SMS API server before being used; to do this, please fill in this web form which will be sent to the technical team

Example:
SMS DR request from Orange to your SMS backend and DR notification endpoint

POST https://{{dev_host}}:443/orange/smsdr.php HTTP/1.1
Content-Type: application/json
{
    "deliveryInfoNotification":{
        "callbackData":"{{resource_id}}",
        "deliveryInfo":{
            "address":"tel:+{{recipient_phone_number}}",
            "deliveryStatus":"{{delivery_status}}"
        }
    }
}
Example: Response by the partner
HTTP/1.1 200 OK

In the JSON body of the Orange request, your backend server receives 3 important pieces of information:

• {{resource_id}}: the unique ID of your previously well sent SMS that you will need to use to correlate the corresponding SMS

• {{recipient_phone_number}}: the MSISDN of your previously well sent SMS

• {{delivery_status}}: the status of the SMS DR

{{delivery_status}} can have several possible values:

Important note about SMS DR Status
In case you get DeliveredToTerminal, you can rely on this information.
However behind a DeliveryImpossible status, your SMS can still be well delivered (e.g. if a phone has not reached a network for more than 24 hours or has no battery); or you may get this status if you are sending an SMS to a landline number or to a number that is no longer in use and has been deactivated.
All these statuses are considered normal behaviour and cannot be subject to opening an incident case.
Orange will not refund any SMS even if you receive a Delivery Impossible status.

5. Administer your account

5.1 View your SMS balance

You can check the number of units left (contract balance) and the expiry date on your application or by calling the following endpoint
https://api.orange.com/sms/admin/v1/contracts.
You'll have to use the {{access_token}} to authenticate.

Example

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/contracts"

This query returns your SMS units balance and their expiration date, in JSON format :

[
    {
        "id": "6368bdba70585131d5454a5a",
        "type": "SELFSERVICE",  // or BROKER
        "developerId": "{{developerId}}",
        "applicationId": "{{applicationId}}",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "availableUnits": 120,
        "requestedUnits": 0,
        "status": "ACTIVE",   // or EXPIRED
        "expirationDate": "2023-01-07T15:04:20.653Z",
        "creationDate": "2022-11-07T08:11:38.220Z",
        "lastUpdateDate": "2022-12-08T15:04:20.656Z"
    }
]

Note: the response is an array with one element per country if you have subscribed to APIs in different countries using the same account. You can add the country as a parameter if you want to filter:
https://api.orange.com/sms/admin/v1/contracts?country={{country_code}} where {{country_code}} is the ISO3 country code.

5.2 View your purchase history

You can also view your bundle purchase history. To do this, you should use your {{access_token}} to authenticate and call en the following endpoint:
https://api.orange.com/sms/admin/v1/purchaseorders

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/purchaseorders"

This query returns the purchase history for the current account by country, in JSON format.

Example :

[
    {
        "id": "6368bdba70585131d5454a5b",
        "developerId": "{{developerId}}",
        "contractId": "63***",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "bundleId": "6368b9b35455a62e00d9997a",
        "bundleDescription": "Bundle 0 - 20 SMS for 320 FCFA (Starter for 7 days)",
        "price": 320.00,
        "currency": "XOF",
        "purchaseDate": "2022-11-07T08:11:38.260Z",
        "paymentMode": "OTP_SMS_OCB",
        "paymentProviderOrderId": null,
        "payerId": "22507******",
        "type": "BUNDLE_PURCHASE",
        "oldAvailableUnits": 0,
        "newAvailableUnits": 20,
        "oldExpirationDate": "2022-11-07T22:59:59.000Z",
        "newExpirationDate": "2022-11-14T08:11:38.227Z"
    },
   {
        "id": "6391fcf45b1130****",
        "developerId": "{{developerId}}",
        "contractId": "63*****",
        "country": "CIV",
        "offerName": "SMS_OCB",
        "bundleId": "6368b9b35455a62e00d9997d",
        "bundleDescription": "Bundle 1 - 100 SMS for 1 600 FCFA (for 30 days)",
        "price": 1600.00,
        "currency": "XOF",
        "purchaseDate": "2022-12-08T15:04:20.664Z",
        "paymentMode": "NOCHALLENGE_OM",
        "paymentProviderOrderId": "374213*****",
        "payerId": "{{developerEmail}}",
        "type": "BUNDLE_PURCHASE",
        "oldAvailableUnits": 20,
        "newAvailableUnits": 120,
        "oldExpirationDate": "2022-12-13T23:59:59.000Z",
        "newExpirationDate": "2023-01-07T15:04:20.653Z"
    },
]

You can add the country as a parameter if you want to filter:
https://api.orange.com/sms/admin/v1/purchaseorders?country={{country_code}} where {{country_code}} is the the ISO3 country code.

5.3 SMS usage statistics

You can also view your bundle purchase history. To do this, you should use your {{access_token}} to authenticate and call en the following endpoint:
https://api.orange.com/sms/admin/v1/statistics

Example :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/statistics"

It returns SMS usage by country, in JSON format:

{
    "partnerStatistics": {
        "developerId": "{{developerId}}",
        "statistics": [
            {
                "service": "SMS_OCB",
                "serviceStatistics": [
                    {
                        "country": "CIV",
                        "countryStatistics": [
                            {
                                "appid": "yf1qyS4gv****",
                                "usage": 2,
                                "nbEnforcements": 2
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

You can filter on the result by using one of the following optional parameters {{country_code}} and/or {{app_id}}
/sms/admin/v1/statistics?country={{country_code}}&appid={{app_id}}

• {{country_code}} is the ISO3 country code

• {{app_id}} is th eID of your application on developer.orange.com portal