API Documentation

Introduction

Our API runs on HTTP(S) protocol, accepts POST or GET requests (encoded in UTF-8) and receives responses in JSON format. Thus, it can be used by all languages capable of submitting an HTTP(S) request and interpreting JSON as PHP, ASP, Python, Java, etc.

In order to use the HTTPS secure protocol, you much replace "http://" with "https://" in page addresses (URLs) called.

Important : To use our send SMS API service, a Spot-Hit customer account is required (Create a free account). The "key" parameter must be entered for each request. It corresponds to a unique key that can be obtained in your account (different from your password) : Retrieve my API key

If you encounter any problems while using this SMS API, please don’t hesitate to contact us to be put in contact with our technical team.

Return Values

After each request made, you will receive a response formatted in JSON under the following format :

{resultat: [X], id: [unique campaign identifier] or erreurs: [error number]}

Example of accepted request :

{resultat: 1, id: 1337}

Example of rejected request :

{resultat: 0, erreurs: 1,4,2}

Example of use with PHP (POST and GET)

Sending an SMS with the HTTP POST Methodology (cURL must be installed) :

<?php
// Message data
$data = array(
    'key' => 'fe01ce2a7fbac8fafaed7c982a04e229',
    'destinataires' => '+600000000',
    'message' => 'Hello World !',
    'expediteur' => 'Spot-Hit',
    'date' => '',
);

// Initialization of cURL with the call URL
$ch = curl_init('https://www.spot-hit.es/api/envoyer/sms');

// cURL parameters to activate the POST and return a response
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);

// Data movement
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data, '', '&'));

// Calling the Spot-Hit API and obtaining the response in the $responseJson variable
$responseJson = curl_exec($ch);
curl_close($ch);

// JSON conversion into a table with json_decode (http://fr2.php.net/manual/fr/function.json-decode.php)
$responseArray = json_decode($responseJson, true);

// If 'resultat' == 1, the message was sent correctly
if ($responseArray['resultat']) {
    echo 'Message sent successfully! Unique identifier : '.$responseArray['id'].'';
} else {
    echo 'Error(s) : '.$responseArray['erreurs'].'';
}

Sending an SMS with the HTTP GET Methodology (file_get_contents) :

Important: The number of characters in a URL is limited; to send a message to a large number of recipients (>100) or with other long content (e.g. an HTML email), you must use the POST method mentioned above.

The allow_url_fopen PHP parameter must be activated with "1".

<?php
// Message data
$data = array(
    'key' => 'fe01ce2a7fbac8fafaed7c982a04e229',
    'destinataires' => '+600000000',
    'message' => 'Hello World !',
    'expediteur' => 'Spot-Hit',
    'date' => '',
);

// Data conversion for URL parameter
// http://www.php.net/manual/en/function.urlencode.php
foreach ($data as $parametre => $valeur) {
    $requete .= $parametre.'='.urlencode($valeur).'&';
}

// Calling the Spot-Hit API and obtaining the response in the $responseJson variable
$responseJson = file_get_contents('https://www.spot-hit.es/api/envoyer/sms?'.$requete);

// JSON conversion into a table with json_decode
// http://www.php.net/manual/en/function.json-decode.php
$responseArray = json_decode($responseJson, true);

// If 'resultat' == 1, the message was sent correctly
if ($responseArray['resultat']) {
    echo 'Message sent successfully! Unique identifier : '.$responseArray['id'];
} else {
    echo 'Error(s) : '.$responseArray['erreurs'];
}

List of Errors

List of errors associated with the different types of sendings

Acknowledgment of receipt list

URL to call : https://www.spot-hit.es/api/dlr

Parameters

Results

Correspondence

Table of Errors

Receiving status (PUSH) notifications

URL to call : In your account, you must set up the address for our platform to call at each status change. Quick access to settings

Parameters (GET)

List of messages

URL to call : https://www.spot-hit.es/api/campaign/list

Parameters

Results

Correspondence

Modifying a message

URL to call : https://www.spot-hit.es/api/campaign/edit

Parameters

Results

Table of Errors

Deleting a message

URL to call : https://www.spot-hit.es/api/campaign/delete

Parameters

Results

Table of Errors

List of templates

URL to call : https://www.spot-hit.es/api/sms/models

Parameters

Results

Correspondence

Adding a template

URL to call : https://www.spot-hit.es/api/sms/model/add

Parameters

Results

Table of Errors

Modifying a template

URL to call : https://www.spot-hit.es/api/sms/model/edit

Parameters

Results

Table of Errors

Deleting a template

URL to call : https://www.spot-hit.es/api/sms/model/delete

Parameters

Results

Table of Errors

List of medias

URL to call : https://www.spot-hit.es/api/medias/lister

Parameters

Results

Correspondence

Get the html of an email template

URL to call : https://www.spot-hit.es/api/media/get-html

Parameters

Results

Table of Errors

List of contacts

URL to call : https://www.spot-hit.es/api/contacts/get

Parameters

Results

Adding a contact

URL to call : https://www.spot-hit.es/api/contacts/import

Parameters

Results

Table of Errors

Modifying a contact

URL to call : https://www.spot-hit.es/api/contacts/edit-contact

Parameters

Results

List of Errors

Modifying contacts

URL to call : https://www.spot-hit.es/api/contacts/edit-contacts

Parameters

Results

List of Errors

Deleting a contact

URL to call : https://www.spot-hit.es/api/contact/supprimer

Parameters

Results

Table of Errors

Deleting many contacts

URL to call : https://www.spot-hit.es/api/contacts/supprimer

Parameters

Results

Table of Errors

List of columns

URL to call : https://www.spot-hit.es/api/columns

Parameters

Results

Correspondence

Adding a column

URL to call : https://www.spot-hit.es/api/column/add

Parameters

Results

Table of Errors

Modifying a column

URL to call : https://www.spot-hit.es/api/column/edit

Parameters

Results

Table of Errors

Deleting a column

URL to call : https://www.spot-hit.es/api/column/delete

Parameters

Results

Table of Errors

List of replies

URL to call : https://www.spot-hit.es/api/responses

Parameters

Results

Correspondence

List of stops

URL to call : https://www.spot-hit.es/api/stops

Parameters

Results

Correspondence

Adding stops

URL to call : https://www.spot-hit.es/api/contacts/blacklist

Parameters

Results

Table of errors

Receiving replies (PUSH notifications)

URL to call: In your account, you must set up the address for our platform to call upon reception of each reply to one of your messages. Quick access to settings

Parameters (GET)

Receiving stops (PUSH notifications)

URL to call: In your account, you must set up the address for our platform to call upon reception of a "STOP" reply to one of your messages. Quick access to settings

Parameters (GET)

List of groups

URL to call : https://www.spot-hit.es/api/groupe/lister

Parameters

Results

Adding a group

URL to call : https://www.spot-hit.es/api/groupe/creer

Parameters

Results

Table of Errors

Renaming a group

URL to call : https://www.spot-hit.es/api/groupe/renommer

Parameters

Results

Table of Errors

Deleting a group

URL to call : https://www.spot-hit.es/api/groupe/supprimer

Parameters

Results

Table of Errors

Checking balance

URL to call : https://www.spot-hit.es/api/credits

Parameters

Results

Checking statistics by period

URL to call : https://www.spot-hit.es/api/statistiques

Parameters

Results

List of sub-accounts

URL to call : https://www.spot-hit.es/api/sous-compte/get

Parameters

Results

Adding a sub-account

URL to call : https://www.spot-hit.es/api/sous-compte/add

Parameters

Results

Modifying a sub-account

URL to call : https://www.spot-hit.es/api/client/set

Parameters

Results

Table of Errors

Retrieve list of sub-account items

URL to call : https://www.spot-hit.es/api/client/get

Parameters

Results

Correspondence

Table of Errors

Disabling a sub-account

URL to call : https://www.spot-hit.es/api/sous-compte/desactiver

Parameters

Results

Table of Errors

Suspending a sub-account

URL to call : https://www.spot-hit.es/api/sous-compte/suspendu

Parameters

Results

Table of Errors

Transferring credits

URL to call : https://www.spot-hit.es/api/sous-compte/transferer-credits

Parameters

Results

Setting PUSH Url parameters

URL to call : https://www.spot-hit.es/api/urls/edit

Parameters

Results

Table of Errors

Campaign details

URL to call : https://www.spot-hit.es/api/client/details_campagnes

Parameters

Modifying billing

URL to call : https://www.spot-hit.es/api/billing/edit

Parameters

Results

Adding a customer (White Label)

URL to call : https://www.spot-hit.es/api/client/creer

Important: you must replace https://www.spot-hit.es by your white label’s domain.

Parameters

Results

Listing short links

URL to call : https://www.spot-hit.es/api/liens-courts/lister

Parameters

Results

Adding short links

URL to call : https://www.spot-hit.es/api/liens-courts/creer

Parameters

Results

Table of Errors

Deleting a short link

URL to call : https://www.spot-hit.es/api/liens-courts/supprimer

Parameters

Results

Table of Errors

Short link statistics

URL to call : https://www.spot-hit.es/api/liens-courts/statistiques

Parameters

Results

Table of Errors

Sending an SMS via email

Operation

Messages must be sent from the following address : [email protected].

The parameter syntax is the same as for sending a message via HTTP request.

Writing an email :

• Subject : apiKey=0000000000000&sender=Expediteur&truncate=0&smslong=1&phoneNumbers=+336xxxxxxxxx,+336xxxxxxxxx
  
  

  Parameter	Description
  apiKey	Your API identification key
  phoneNumbers	SMS recipient(s).
  sender	Optional if empty, the sender of your SMS will be the sender name of the email 11 characters maximum (including spaces)
  truncate	Optional If equal to "1", automatically shortens the message to 160 characters. default = 1
  smslong	Optional If equal to "1", authorizes sending an SMS longer than 160 characters. default = 0

• Content = SMS content.

For more flexibility, we recommend using our HTTP API.

Sending a letter via email

Sending an electronic version of your account management letters: bills, estimates, reminders, welcome letters, etc.

Important : this method cannot be used for your mass marketing mailings; you must use the online interface.

Operation

Messages must be sent to the following address : [email protected]. They must be sent from the email address registered as the account identifier (special configuration available, contact us).

Example of French rates :

• Printing a document (A4 80gr color), 2 folds and placement in double window C6 envelope. (cost of €0.27 ex-Tax, contact us for quantities greater than 1,000 letters per month)
• Additional page(s) : A document can include up to 5 pages maximum per envelope (cost per additional page: €0.15 ex-Tax, contact us for quantities greater than 1,000 letters per month)
• Stamped letters sent via the "Ecopli Grand Compte" service to arrive within 4 business days at €0.567. (Faster postage ("LG2 service", arrival within 2 business days) available upon request at a cost of €0.60/unit.)
• Same-day drop off at the post office at 4:30pm if documents are received by 3:00pm (from Monday to Friday).
• Product currently only available for customers billed monthly (usage viewable by clicking on 'View details' on the homepage of the customer login area).

Mandatory requirements for the first page :

• Recipient’s address must be standardly placed on the first page (40mm from the top margin, 20mm from the right margin, max. size of the address field: 100x45mm).
• Sender’s address must be standardly placed on the first page (20mm from the top margin, 10mm from the left margin, max. size of the address field: 90x35mm).

Writing an email :

• Expéditeur = Your account email
• Destinataire = [email protected]
• Sujet = Free field (not processed)
• Pièce(s) jointe(s) = A PDF to be mailed (5 pages max).

Sending a FAX via email

Operation

Messages must be sent to the following address : [email protected]. They must be sent from the email address registered as the account identifier.

The parameter syntax is the same as for sending a message via HTTP request.

Writing an email :

• Sujet = Fax recipient(s).
• Pièce jointe = Fax PDF content (10 pages max).
• Nom de l'expéditeur = Fax sender

Set parameters to be modified with your account manager :

• Sender (default = Email sender’s name. May be set to always be the same.)

For more flexibility, we recommending using our HTTP API.