OxiSMS API User Guide

1. SMS Sending
2. Get access to user account information

1. SMS Sending

URL to use : https://www.oxisms.com/api/1.0/send.php

For coverage zone details and SMS delivery restrictions, refer to : international-coverage

a. Parameters list

Parameters must be addressed to the API with an HTTP request using GET or POST type.

Parameter name	Required? (Mandatory / Optional)	Description	Note
api_key	Mandatory	API ID
api_password	Mandatory	API Password
message	Mandatory	Message to be sent via SMS	Message must be encoded in UTF-8 format
recipients	Mandatory	Table of recipients’ phone numbers, use a comma (“,”) to separate numbers	Limitation to max. 250 recipients per API request
encoding	Optional	Value : « unicode » or « gsm ». GSM 7-bits GSM alphabet. 160 characters max. per sending; 153 characters max. if concatenation Unicode allow special characters sending (other than regular GSM standards). 70 characters max. per sending; 67 characters if concatenation.
sender	Optional	SMS Sender name or number	Follow instructions detailed on the international coverage webpage (see link above)
type	Optional	Value : « notification » or « commercial ». Type of the message	Default value : « commercial ». In accordance with the applicable regulation in Europe, SMS sending for commercial purpose are not allowed, between 9.00pm and 8.00am, from Monday through Saturday and on Sunday (whole day) and local bank holidays too.They are automatically postponed to another authorized slot.
credit_max	Optional	Credit max. accepted for the sending. If the required credit for the sending is higher than this value, the operation is denied.	Ensure complete awareness of the cost required for the sending
test	Optional	Block effective sending of the SMS but simulate the operation and gather / return detailed information for each SMS	Allows to test the API without any impact on the available credits.

b. API Feedbacks

OxiSMS API collects and returns JSON formatted data :

Parameter	Type	Description
success	Booléen	Boolean TRUE if SMS were attempted to be sent FALSE if an error occurs when attempting to proceed to the sending
message	Character String	Short description of the error (when occurring)
details	Table	Table including information for each SMS.

Definition of a SMS included in the table « details » :

Parametre	Type	Description
id	Character String	SMS ID for OxiSMS.
original_recipient	Character String	Number stated in the « recipients » parameter.
recipient	Character String	Formatted number used for the sending.
sent	Boolean	TRUE if the SMS was sent effectively FALSE if an issue prevented the sending
return_code	Character String	Code describing the error which occurred during sending.
description	Character String	Description of the error.

c. Example of API call using HTTP GET method

URL example : https://www.oxisms.com/api/1.0/send.php?api_key=IdentifiantAPI&api_password=MotDePasseAPI&message=Message&recipients=0033601234567

The message « Message » will be sent to “0033601234567” if API access ID are valid.

{
  "success": true,
  "message": "success",
  "details": [
    {
      "id": "5e8404c725276d07f3f4fe246f2acc",
      "original_recipient": "0606060606",
      "recipient": "0606060606",
      "sent": true,
      "return_code": "NOT_REALLY_SENT",
      "description": "Le SMS n'a pas été réellement envoyé car le paramètre 'test' était présent"
    },
    {
      "id": null,
      "original_recipient": "pas_un_numero",
      "recipient": null,
      "sent": false,
      "return_code": "INVALID_RECIPIENT",
      "description": "Invalid recipient value: 'pas_un_numero'"
    }
  ]
}

2. Get access to user account information

URL to use : https://www.oxisms.com/api/1.0/account.php

a. Parameters list

Parameters must be addressed to the API with an HTTP request using GET or POST type.

Parameter name	Required ?	Description	Note
api_key	Mandatory	API ID
api_password	Mandatory	API Password

b. API Feedbacks

OxiSMS API collects and returns JSON formatted data :

Parameter	Type	Description
success	Boolean	TRUE if no error occurred during the process. FALSE if an error occurred.
message	Character String	Short description of the error (when occurring).
details	Table	Table with account information.

Description of parameters included in the table « details » :

Parameter	Type	Description
customer_name	Character String	Name and company name associated with the account.
expiration_date	Character String	Expiry date of the credits (YY-mm-dd format).
expiration_date_unix	Integer	Expiry date of the credits timestamp UNIX format
credit	Integer	Remaining credits.

c. Example of API call using HTTP GET method

URL example : https://www.oxisms.com/api/1.0/account.php?api_key=IdentifiantAPI&api_password=MotDePasseAPI

Account information will be displayed if API access ID are valid.

{
  "success": true,
  "message": "success",
  "details": {
    "customer_name": "M. Jean DUPONT",
    "expiration_date": "2020-07-20",
    "expiration_date_unix": 1595196000,
    "credit": 123.45
  }
}