webleads-tracker

Documentos API SMS para envío de SMS por Spot-Hit

API Documentation

1Operation

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' => '+34600000000',
    
'type' => 'premium',
    
'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($chCURLOPT_RETURNTRANSFERtrue);
curl_setopt($chCURLOPT_POST1);

// Data movement
curl_setopt($chCURLOPT_POSTFIELDShttp_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($responseJsontrue);

// 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' => '+34600000000',
    
'type' => 'premium',
    
'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($responseJsontrue);

// 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'];
}

2Sending

Sending an SMS

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

List of SMS API Parameters

Parameter Description
key Your API identification key
message Limited to 160 characters (or see longsms parameter).
Important : The following characters are counted as two : |, ^, , }, {, [, ~, ] and \.
In a GET request, use the \n n character to create a line break.
The %0A, <br>, <br />, <br/> and \n characters are automatically replaced by a line break.
Customized SMS : {Nom de la colonne}, Example : {Nom}
destinataires List of your recipients’ numbers (table or separated by a line break or comma)
e.g. : +34600000000,003460-00-00-00 , 6 00 00 00 00
expediteur Optional
11 characters maximum (including spaces)
If empty, your SMS sender will have a short 5-digit number to which your recipients can reply.

The sender must contain a minimum of 3 characters to be customized and cannot begin by more than 3 consecutive digits before the first letter.

The caller ID depends on the type of phone. For example, on certain iPhones, spaces are removed. In addition, accents and special characters are never taken into account.

International
Certain countries do not accept sender customization. It is strongly advised that you contact us to know more about the specifications of each country concerned.
The recipients will not be able to reply to the SMS when sending outside France & DOM-TOM.
date Optional
Message send date (timestamp format)
If a date is not entered or it precedes the current date, the message will be sent immediately.
smslong Optional
If equal to "1", authorizes sending an SMS longer than 160 characters. You will be billed for one SMS every 153 characters.
Example: for a 300-character message sent to 1,000 recipients, you will be charged for 2,000 SMS.
5 concatenate SMS maximum (765 characters).
smslongnbr Optional
Verifies the size of a long SMS sent. The number of concatenate SMS must be sent as a value. If our counter indicates a different number, your message will be rejected.
tronque Optional
If equal to "1", automatically shortens the message to 160 characters.
encodage Optional
If equal to "auto", conversion of your message to UTF-8 (converting your message to UTF-8 in your application is advised; however, if your message remains cut off after an accented character, you can activate this parameter).
If equal to "ucs2", convert your message to unicode (you can use extra characters like "ê" which is not taken into account in standard SMS, as well as include emojis.) Warning: The number of characters is limited to 70, and 67 in Long SMS).
nom Optional
This information is not visible to recipients, enabling you to identify your campaign (255 characters maximum).
destinataires_type Optional
Enables the selection of contacts already saved in the customer account:
« all » = selection of all account contacts.
« groupe » = selection of all id group contacts provided in the « destinataires » field (a table containing group identifiers is required)
« datas » = allows you to add customized data to « destinataires » to use in your message (e.g.: "Hello {surname} {given name}"). To do so, the « destinataires » field is required, a table in this form : array("+34600000001" => array("surname" => "Surname 1", "given name" => "Given name 1"), "+34600000002" => array("surname" => "Surname 2", "given name" => "Given name 2"), etc.)
url Optional
The URL of your server for receiving delivery status "push" notifications. You should already have an address set up in your account to activate "push". notifications. If this parameter is provided, the URL will be called to send them; if not, the account address will be used.
date_debut Optional, required for the staggered shipment
Start date of sending messages (timestamp format)
date_fin Optional, required for the staggered shipment
End date of sending messages (timestamp format)
creneaux Optional, required for the staggered shipment
Hour(s) of sending
Array 8,9,10,11,12,13,14,15,16,17,18,19
The campaign will be split in proportion to the number of slots between the day and the start time, and the desired end day and time.
creneaux_heure Optional, required for the staggered shipment
1,2,3,4 ou 6
Number of sending per hour
jours Optional, required for the staggered shipment
Array 1,2,3,4,5,6
Sending days (1 equal to Monday). No sending on Sunday.

Sending an Email

URL to call : https://www.spot-hit.es/api/envoyer/e-mail

List of the email API parameters

Parameter Description
key Your API identification key
sujet Email subject that will be displayed in your recipients’ inboxes.
message Content of your email (HTML format).
destinataires List of your recipients’ emails (table or separated by a line break or comma
expediteur Sender’s email address. Important: for better differentiability you must use a domain referenced on Spot-Hit. By default, we provide you with a n1xmail.com domain. Example : [email protected]
nom_expediteur Appears in addition to the sender’s email address, corresponding to the display of your Surname and Given name when you send a personal email.
email_reponse Optional
Email for forwarding replies.
date Optional
Message send date (timestamp format)
If a date is not entered or it precedes the current date, the message will be sent immediately.
type_message Optional
Enables the selection of a template already saved in the customer account :
«creation» = template selection with the template id provided in the « message » field
destinataires_type Optional
Enables the selection of contacts already saved in the customer account :
« all » = selection of all account contacts.
« groupe » = = selection of all id group contacts provided in the « destinataires » field
« datas » = allows you to add customized data to « destinataires » to use in your message (example: "Hello {surname} {given name}"). To do so, the « destinataires » field is required, a table in this form : array("[email protected]" => array("surname" => "Surname 1", "given name" => "Given name 1"), "[email protected]" => array("surname" => "Surname 2", "given name" => "Given name 2"), etc.)
nom Optional
This information is not visible to recipients, enabling you to identify your campaign.
date_debut Optional, required for the staggered shipment
Start date of sending messages (timestamp format)
date_fin Optional, required for the staggered shipment
End date of sending messages (timestamp format)
creneaux Optional, required for the staggered shipment
Hour(s) of sending
Array 8,9,10,11,12,13,14,15,16,17,18,19
The campaign will be split in proportion to the number of slots between the day and the start time, and the desired end day and time.
creneaux_heure Optional, required for the staggered shipment
1,2,3,4 ou 6
Number of sending per hour
jours Optional, required for the staggered shipment
Array 1,2,3,4,5,6
Sending days (1 equal to Monday). No sending on Sunday.

List of Errors

Error Code Description
1 Message type not specified or incorrect ("type" parameter)
2 The message is empty
3 The message contains more than 160 characters
4 No valid recipient is provided
5 Blocked number
6 Invalid recipient number
7 Your account has no set contract
8 SMS | The sender is invalid.
EMAIL | The sender’s email is invalid.
MMS | The subject contains more than 16 characters.
9 The system has encountered an error, please contact us.
10 You do not have enough SMS available for your message to be sent.
11 The option to send messages has been deactivated for demonstration purposes.
12 Your account has been suspended. Please contact us for more information
13, 14, 15 Your set sending limit has been reached. Please contact us for more information.
16 The "smslongnbr" parameter does not match the size of the message sent.
17 The sender is not authorized.
18 EMAIL | The subject is too short.
19 EMAIL | The reply email is invalid.
20 EMAIL | The sender’s name is too short.
21 Invalid token. Please contact us for more information.
22 Length of message not authorized. Please contact us for more information.
23 No variable date was found in your list of recipients.
24 Your campaign has not been validated as it is missing the "STOP" mention in your message. As a reminder, in order to meet CNIL’s legal requirements, it is imperative to include an unsubscribe option. You can click on "Modify campaign" and check the "STOP" mention at the bottom of the message.
25 Scaling: start date empty
26 Scaling: end date empty
27 Scaling: start date later than end date
28 Scaling: no slots available
30 API key not recognized.
36 You can not have emojis in your message.
38 You must include "Stop" in your SMS.
45 This product is not enabled.
50 The specified time zone is not valid.
51 The date has already passed after calculates the time zone.
52 You have reached the maximum limit of 50 draft campaigns. If you want to add more, please contact us.
99 Your account has been suspended.

3Follow-up

Acknowledgment of receipt list

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

Parameters

Parameter Description
key Your API identification key
id Message ID

Results

Result
[
["+34600000000","1","1323257035","1323257040", "178", "245645656", "20801"],
["+34600000000","1","1323257035","1323257040", "178", "245645656", "20801"]
...
]
{resultat: 0, id:, erreurs: "1"}

Correspondence

Components Description
[numero] Recipient’s number
[statut] Message status :
1 = Sent and received
2 = Sent and not received
3 = In progress
4 = Failed
5 = Expired
(Statuses 1, 4 and 5 are definitive.)
[date_emission] Date message sent (UNIX timestamp)
[date_mise_a_jour] Date of last message status change (UNIX timestamp)
[statut_detaille] Detailed message status (available from your account manager. Not available in Low Cost).
[id_message] Message identifier.
[operateur] MCCMNC code corresponding to the recipient’s provider (not available in Low Cost).

Table of Errors

Number Description
1 Invalid ID

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)

Parameter Description
id_accuse Unique message identifier for this number.
id_message Common identifier if sending a group message.
numero Optional, recipient’s telephone number (only if SMS, Voice or Fax message type).
email Optional, recipient’s email (only if email message type).
statut SMS message status :
0 = Pending
1 = Delivered
2 = Sent
3 = In progress
4 = Failed
5 = Expired
(Statuses 1 and 4 are definitive.)

Email message status:
0 = Pending
2 = Sent
3 = Clicked on
4 = Error
5 = Blocked
6 = Spam
7 = Unsubscribed
8 = Opened
date_envoi Date message sent (timestamp).
date_update Date of last status update (timestamp).
statut_code Detailed status from 0 to 9,999 (ask your account manager for more details).
nom Your message’s title or personal identifier
liens List of links clicked on

List of messages

URL to call : https://www.spot-hit.es/manager/inc/actions/liste_messages.php

Parameters

Parameter Description
key Your API identification key
date_debut Optional, selection start date timestamp. (default : account creation date)
date_fin Optional, selection end date timestamp. (default : today)
limit Optional, maximum number of results in the selection. (max : 10,000)
start Optional, starting point of the selection.
id Optional, unique selection of the message corresponding to the identifier provided.

Results

Result
[
[455]["Message content"]["+34600000000,+34600000000"][2][15805646456][2]["Sender"]["premium"][15805646456]["My campaign"]
[55]["Message content"]["+34600000000,+34600000000"][2][15805646456][2]["Sender"]["premium"][15805646456]["My campaign 2"]
...
]

Correspondence

Components Description
[id] Unique identifier
[message] Message content
[liste_destinataires] List of recipients separated by commas
[nbr_destinataires] Number of recipients
[date] Send date timestamp
[statut] Message delivery status [0 = Scheduled, 1 = In Progress, 2 = Sent, 3 = Failed]
[expediteur] Message sender
[type] Type of message
[date_ajout] Date added timestamp
[nom] Your message identifier

Modifying a message

URL to call : https://www.spot-hit.es/manager/inc/actions/modifier_message.php

Parameters

Parameter Description
key Your API identification key
date New send date (timestamp)
If empty or invalid = send immediately
id ID of contact to be modified

Results

Result Description
{resultat: 1} resultat = 1 = Component successfully modified
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered

Table of Errors

Number Description
1 ID does not exist
2 Message already sent, thus cannot be modified

Deleting a message

URL to call : https://www.spot-hit.es/manager/inc/actions/supprimer_message.php

Parameters

Parameter Description
key Your API identification key
id ID of message to be deleted

Results

Result Description
{resultat: 1} resultat = 1 = Component successfully deleted
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during deletion.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 ID does not exist
2 Message already sent, this cannot be deleted

4Templates

List of templates

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[
[455]["Template 1"]["Template example"]
[575]["Template 2"]["Template example"]
...
]

Correspondence

Components Description
[id] Unique identifier
[nom] Template name
[message] Template content

Adding a template

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

Parameters

Parameter Description
key Your API identification key
nom Template name
message Template content
Customized SMS : {Nom du critère}

Results

Result Description
{resultat: 1, id: 45498} resultat = 1 = Component successfully added.
id = Component’s unique identifier.
{resultat: 0, erreurs: "1,2,3,4"} resultat = 0 = Error occurred during addition.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 The title is empty
2 The message contains more than 160 characters
3 The message is empty
4 The system has encountered an error, please contact us

Modifying a template

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

Parameters

Parameter Description
key Your API identification key
message Template content
id Identifier of template to be modified

Results

Result Description
{resultat: 1} resultat = 1 = Component modified successfully
{resultat: 0, erreurs: "1,2,3,4"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 Identifier does not exist
2 The message contains more than 160 characters
3 The message is empty
4 The system has encountered an error, please contact us

Deleting a template

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

Parameters

Parameter Description
key Your API identification key
id Identifier of component to be deleted

Results

Result Description
{resultat: 1} resultat = 1 = Component deleted successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during deletion.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 Identifier does not exist
2 The system has encountered an error, please contact us

5Medias

List of medias

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

Parameters

Parameter Description
key Your API identification key
output Optional
Filter the type of media :
0 : Mobile Website
1 : Model Email
3 : Imported Model
get-html Optional
Allows you to recover the html of each email template

Results

Result
[

{"id":"455","thumbnail":"https://www.spot-hit.es/uploads/outilmedia/thumbnails/no-thumbnail-available.png","output":"1","name":"Model 1","date_creation":"1327843894","date_update":"1327843894","is_online": true },

{"id":"575","thumbnail":"https://www.spot-hit.es/uploads/outilmedia/thumbnails/no-thumbnail-available.png","output":"0","name":"Model 2","date_creation":"1327843894","date_update":"1327843894","is_online": true },
...

]

Correspondence

Components Description
[id] Unique identifier
[thumbnail] Url of thumbnail
[output] 0: Mobile Website
1: Model email
[name] Name of media
[date_creation] Date of creation of the media
[date_update] Date of update of the media
[is_online] Mobile Website online or not

Get the html of an email template

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

Parameters

Parameter Description
key Your API identification key
id Id of media

Results

Result Description
{"resultat": 1, "preview": "!DOCTYPE[...]"} resultat = 1 = Html of the recovered media successfully.
preview = Html of media content
{"resultat": false, "erreurs": "1,2"} resultat = 0 = Error retrieving the html from the media.
errors = List of errors encountered

Table of Errors

Number Description
1 This is not an email template
2 This email template does not exist.

6Contacts

List of contacts

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

Parameters

Parameter Description
key Your API identification key
format "json" (or "html", not recommended)
nbr The maximum number of contacts that you wish to retrieve (do not fill in to use all contacts)
groupe Provide the ID of one of your groups if you wish to target only contacts that are in this group.

Results

Result
{
"total":2,
"colonnes":{"9696":"Given name","9697":"Surname","27728":"Custom field"},
"donnees":
[

{"id":"28577127","numero":"+34600000001","groupe":"30522","email":"[email protected]","fixe":"","fax":"","groupe_nom":"Test group","c_champs personnalise":"Custom field content""c_nom":"Surname 1""c_prenom":"Given name 1"},

{"id":"28577128","numero":"+34600000002","groupe":"30522","email":"[email protected]","fixe":"","fax":"","groupe_nom":"Test group","c_champs personnalise":"Custom field content""c_nom":"Surname 2""c_prenom":"Given name 2"}
...

]
}

Adding a contact

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

Parameters

Parameter Description
key Your API identification key
contacts Table of contacts
contacts[0][nom]=Surname 1
contacts[0][given+name]=Given name 1
contacts[0][mobile]=+34600000001
contacts[0][fixe]=+34100000001
contacts[0][fax]=+34200000001
contacts[0][email][email protected]
contacts[0][custom_id]=123456
contacts[0][Custom+Field]=Custom field content
contacts[0][Custom+Field+2]=Custom field content
contacts[1][given+name]=Given name 2
contacts[1][mobile]=+34600000002
contacts[1][fixe]=+34100000002
contacts[1][fax]=+34200000002
contacts[1][email][email protected]
contacts[1][custom_id]=123457
contacts[1][Custom+Field]=Custom field content
contacts[1][Custom+Field+2]=Custom field content
groupe_id ID of the group contacts should be in
Enter 0 if creating a new group
groupe_nom Optional, name of group to create.
groupe_id must be entered as 0
remplacer_groupe Default = 0, if equal to 1, replace contacts already in the group
ajouter_autres_groupes Default = 0, if equal to 1, add contacts even if they are already in another group
supprimer_intenationaux Default = 0, if equal to 1, delete any non-French numbers
indicatif Default = 34 (national), code for numbers without code provided

Results

Result Description
{resultat: 1, nbr_ajouts: 2, groupe: 1000, contacts_id: {123456478,132465464} resultat = 1 = Component added successfully
nbr_ajouts = Number of contacts added
groupe = Group ID
contacts_id = Id list of contacts added
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during import
erreurs = List of errors encountered

Table of Errors

Number Description
1 Impossible to create group or group already exists
2 Contacts empty or illegible

Modifying a contact

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

Parameters

Parameter Description
key Your API identification key
id ID of contact to modify
colonnes Table with the the name of the column and the new value.
Example of column names:
"mobile"
"fixe"
"email"
"custom_id"
"Field + Customize"
custom_id Set to 1 if the id is customized
groupe Group id to target the custom id

Results

Result Description
{resultat: true, id : XXX, contact : {colonne : XXX} } resultat = true = Component changed successfully
{resultat: false, erreurs: "No column has been found", code_erreurs: {1}} resultat = false = Error while updating the contact.
erreurs = Error message
code_erreurs = Array of errors

List of Errors

Error Code Description
1 No contact has been found
2 No column has been found
3 No id entered

Modifying contacts

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

Parameters

Parameter Description
key Your API identification key
contacts Table of contacts with id in the key and for value a table with the the name of the column and the new value.
It not create column that does not exist
custom_id Set to 1 if the ids are customized

Results

Result Description
{ 0: {resultat: true, id : XXX, contact : {colonne : XXX} } } resultat = true = Component changed successfully
{ 0: {resultat: false, erreurs: {1}} } resultat = false = Error while updating the contact.
erreurs = Array of errors

List of Errors

Error Code Description
1 "Contacts" need to be an array
2 No column has been found
3 No id entered

Deleting a contact

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

Parameters

Parameter Description
key Your API identification key
id ID of contact to be deleted
custom_id Set to 1 if the id is custom.
groupe Group ID to find the custom id

Results

Result Description
{resultat: true} resultat = true = Component deleted successfully
{resultat: false, erreurs: {1,2}} resultat = false = Error occurred during deletion.
erreurs = Array of errors encountered.

Table of Errors

Number Description
1 ID empty or does not exist
2 The system has encountered an error, please contact us

Deleting many contacts

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

Parameters

Parameter Description
key Your API identification key
ids Id of contact to be deleted, as an array or separated by a comma.
custom_id Set to 1 if the ids are custom. (delete from all the groups)

Results

Result Description
{resultat: true, contacts: {id: {'resultat' => true}}}} resultat = true = Component deleted successfully
contacts = Informations for every contacts
{resultat: false, contacts: {id: {'resultat' => false, 'erreurs' => {2}}}} resultat = false = Error occurred during deletion.
contacts = Informations for every contacts
erreurs = Array of errors encountered.

Table of Errors

Number Description
1 ID empty or does not exist
2 The system has encountered an error, please contact us

7Columns

List of columns

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[
[455]["Criterion 1"][1]
[575]["Criterion 2"][2]
...
]

Correspondence

Components Description
[id] Unique identifier
[nom] Criterion name
[numero] Criteria ranking position

Adding a column

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

Parameters

Parameter Description
key Your API identification key
nom Criterion name

Results

Result Description
{resultat: 1, id: 45498} resultat = 1 = Component added successfully.
id = Component’s unique identifier.
{resultat: 0, erreurs: "1,2,3,4"} resultat = 0 = Error occurred during addition.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 The name is empty
2 The name contains more than 11 characters
3 The number of criteria is limited to 6
4 The system has encountered an error, please contact us

Modifying a column

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

Parameters

Parameter Description
key Your API identification key
nom Criterion name
id Identifier of criterion to be modified

Results

Result Description
{resultat: 1} resultat = 1 = Component modified successfully
{resultat: 0, erreurs: "1,2,3,4"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered.

Table of Errors

Number Description
1 Identifier does not exist
2 The name is empty
3 The name contains more than 11 characters
4 The system has encountered an error, please contact us

Deleting a column

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

Parameters

Parameter Description
key Your API identification key
id Identifier of the component to be deleted

Results

Result Description
{resultat: 1} resultat = 1 = Component deleted successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during deletion.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Identifier does not exist
2 The system has encountered an error, please contact us

8Replies

List of replies

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

Parameters

Parameter Description
key Your API identification key
date_debut Optional, selection start date timestamp. (default: account creation date)
date_fin Optional, selection end date timestamp. (default: today)
limit Optional, maximum number of results in the selection. (max: 10,000)
start Optional, starting point of the selection.
id Optional, unique selection of the message corresponding to the identifier provided.

Results

Result
[
['id']['numero']['message']['date_envoi']['source_id']
...
]

Correspondence

Components Description
[id] Unique identifier
[numero] Caller’s telephone number
[message] Reply message content
[date_envoi] Reply send date timestamp
[source_id] Source message’s unique identifier

List of stops

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[
['id']['numero']['date_envoi']['source_id']
...
]

Correspondence

Components Description
[id] Unique identifier
[numero] Caller’s telephone number
[date_envoi] Reply send date timestamp
[source_id] Source message’s unique identifier

Adding stops

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

Parameters

Parameter Description
key Your API identification key
numeros Table of numbers
numeros[0]=+34600000001
numeros[1]=+34100000002

Results

Result Description
{resultat: X} resultat = X = Number of added numbers
{resultat: 0, erreurs: "30"} resultat = 0 = Error while adding
erreurs = Listof encountered errors

Table of errors

Number Description
30 API key not recognized.

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)

Parameter Description
id Unique identifier
numero Caller’s telephone number
date Reply send date timestamp
message Reply message content
source Source message’s unique identifier

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)

Parameter Description
id Unique identifier
numero Caller’s telephone number (can remain empty if the email field is filled in)
email Sender’s email (can remain empty if the number field is filled in)
date_envoi Reply send date timestamp
source_id Source message’s unique identifier

Reinstating STOPs

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

Parameters

Parameter Description
key Your API identification key
numero Number to reinstate (can remain empty if the email field is filled in)
email Email to reinstate (can remain empty if the number field is filled in)

Results

Result Description
{resultat: 1} resultat = 1 = Component deleted successfully
{"resultat":0,"erreurs":[3]} resultat = 0 = Error occurred during deletion.
erreurs = List of errors encountered

Table of Errors

Number Description
0 The system has encountered an error, please contact us
1 Empty parameter
2 Incorrect parameter
3 No Number or Email

9Groups

List of groups

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[{"id":"1","commercant":"1","groupe":"Groupe 1","total":"10"},{"id":"2","commercant":"1","groupe":"Group 2","total":"25"}]

Adding a group

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

Parameters

Parameter Description
key Your API identification key
nom Group name (100 characters max)

Results

Result Description
{resultat: 1, id: 45498} resultat = 1 = Component added successfully.
id = Component’s unique identifier
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during addition.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Impossible to create group / Verify that the group is unique
2 The name is empty or contains more than 100 characters

Renaming a group

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

Parameters

Parameter Description
key Your API identification key
nom Group name (100 characters max)
id Identifier of group to be modified

Results

Result Description
{resultat: 1} resultat = 1 = Component modified successfully
{resultat: 0, erreurs: "1,2,3"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Impossible to rename group
2 The name is empty or contains more than 100 characters
3 Group ID not specified or nonexistent/td>

Deleting a group

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

Parameters

Parameter Description
key Your API identification key
id Identifier of component to be deleted

Results

Result Description
{resultat: 1} resultat = 1 = Component deleted successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during deletion.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Error occurred during deletion of group
2 Group ID not specified or nonexistent

10Accounts

Checking balance

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

Parameters

Parameter Description
key Your API identification key

Results

Result Description
{resultat: true, pre_paye: false, post_paye: false, euros: "0", premium: "1000", lowcost: "1000", mms: "5", mobile: "50", fixe: "50", direct_classique: "50", direct_premium: "50", email: "100", vocalisation: "3600", fax: "100"} Query result + prepaid option in euros + postpaid option + number of credits remaining (by type) in your account (only if the postpaid option is not activated).

Checking statistics by period

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

Parameters

ParameterDescription
keyYour API identification key
date_debutOptional, selection start date timestamp (default: start date of current month).
date_finOptional, selection end date timestamp (default: today).
sous_compteOptional, Boolean 1/0 to take into account the usage of sub-accounts (default: 0).

Results

Result
{resultat: true, statistiques:{"premium":0, "lowcost":0, "direct_classique":0, "direct_premium":0, "mobile":0,"fixe":0, "html":0, "fax":0, "hlr":0, "vocalisation":0, "mms":0, "courrier_gestion":{"affranchissement":0,"routage":0,"supplement":0},"pays":[]}}

11Sub-accounts

List of sub-accounts

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[
{"id":"1","email":"[email protected]","civilite":"M","nom":"Surname 1","prenom":"Given name 1","nom_entreprise":"Business 1","nom_commercial":"Business name 1","adresse":"Test street","ville":"Test city","code_postal":"Test Zip code","pays":"Metropolitan France","date_inscription":"1327843894","api_cle":"subaccountapikey","solde_premium":"0","solde_lowcost":"125","solde_email":"10","solde_fax":"10","solde_fixe":"10","solde_mobile":"10","solde_direct_repondeur":"10"}
...
]

Adding a sub-account

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

Parameters

Parameter Description
civilite (Mr, Mrs)
nom Surname
prenom Given name
nom_entreprise Business name
nom_commercial Commercial name
raison (business, association, administration)
adresse Address
code_postal Zip code
ville City
telephone_personnel Personal phone
telephone_entreprise Business phone
email Email
motdepasse Your password
confirmation Please re-enter your password

Results

Result Description
{resultat: 1, id: 400045, key: 3c6e0b8a9c15224a8228b9a98ca1531d} resultat = 1 = Component added successfully
id = Account unique identifier
key = Account API key
{resultat: 0, erreur: "Votre erreur"} resultat = 0 = Error occurred during addition.
erreur = Your error

Modifying a sub-account

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

Parameters

Parameter Description
client Sub-account unique identifier
element Component that you wish to modify (nom, prenom, raison_sociale, nom_entreprise, nom_commercial, mot_de_passe, indicatif_defaut, email)
valeur The new value you want to assign

Results

Result Description
{resultat: 1} resultat = 1 = Component modified successfully
{resultat: 0, erreur: [1,2]} resultat = 0 = Error occurred during modification.
erreurs = Table of errors encountered

Table of Errors

Number Description
1 Component cannot be modified.
2 Value invalid/Email already in use.
5 Customer cannot be found/No permission to modify the customer.
99 SQL error.

Retrieve list of sub-account items

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

Parameters

Parameter Description
key Your API identification key
id The Unique Account Identifier
elements Optional
Items you want (first_name, last_name, civility, company_name, commercial_name, address, zip_code, city, country, email, business_phone, language, api_key)
Syntaxe : ["first_name", "last_name", ...]

Results

Result Description
{resultat: true, data: {"first_name": "John", "last_name": "Doe", ...}} Data array.
{resultat: false, erreurs: [1, 2, 3]} resultat = false = Error occurred during retrieving data.
erreurs = List of errors encountered.

Correspondence

Elements Description
first_name Surname
last_name Given name
civility Civility
company_name Business name
commercial_name Commercial name
address Address
zip_code Zip code
city City
country Country
email Email
business_phone Business phone
language Language
api_key API key

Table of Errors

Number Description
1 Incorrect ID value.
2 Incorrect elements value.
3 Account not found.

Disabling a sub-account

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

Parameters

Parameter Description
key Your API identification key
id Sub-account identifier

Results

Result Description
{resultat: 1} resultat = 1 = Sub-account disabled successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during disabling.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Missing Id.
2 Customer cannot be found/No permission to modify the customer.

Transferring credits

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

Parameters

Parameter Description
key Your API identification key
id_sous_compte Sub-account identifier
act Action Type : "credit" or "debit"
type Credit Type : "premium", "email",
credits Number of credits to be transferred

Results

Result Description
{resultat: 1} resultat = 1 = Component added successfully
{resultat: 0, message: "Error message"} resultat = 0 = Error occurred during transfer.
message = Message of error encountered

Setting PUSH Url parameters

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

Parameters

Parameter Description
key Your API identification key
accuses URL for receiving acknowledgement of receipts
stops URL for receiving stops
reponses URL for receiving replies

Results

Result Description
{resultat: 1} resultat = 1 = Component added successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered

Table of Errors

Number Description
1 Internal error.

Campaign details

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

Parameters

Parameter Description
format json or csv (default : json)
debut Selection beginning Timestamp unix (default: the 1st of last month)
fin Selection end Timestamp unix (default: the 31st of last month)

Modifying billing

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

Parameters

Parameter Description
key Your API identification key
id Customer account ID
facturation (0 = Prepaid, 1 = Postpaid)

Results

Result Description
{resultat: 1} resultat = 1 = Component added successfully
{resultat: 0, erreurs: "1,2"} resultat = 0 = Error occurred during modification.
erreurs = List of errors encountered

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

Parameter Description
key Your API identification key
raison Account company type : "entreprise", "association" ou "administration"
nom_entreprise Account business name
adresse Account address
code_postal Account zip code
ville Account city
pays Account country
civilite Account holder title : "M" ou "Mme"
nom Account holder surname
prenom Account holder given name
email Account email
telephone_entreprise Account business phone
telephone_personnel Account personal phone
mdp_decrypte Decrypted password
premium Premium SMS credits (default 0)
credit_email Email credits (default 0)
direct_classique Direct voicemail credits (default 0)
fixe Landline minutes (default 0)
mobile Mobile minutes (default 0)
fax Fax credits (default 0)
valider_cgvu Automatically validate Terms and Conditions of Sale and Use: 1 or 0

Results

Result Description
{resultat: 1, id: 999} resultat = 1 = Customer added successfully + customer ID
{resultat: 0, erreur: "Erreur en texte"} resultat = 0 = Error occurred during modification.
erreur = Error encountered

Regenerate an API key

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

Parameters

Parameter Description
key Your API identification key
id Id of subaccount compte to target

Results

Result Description
{resultat: true, cle_api: "2d1a18835cadd5944030bxx"} resultat = true = Clé api regénérée avec succès
cle_api = nouvelle clé api
{resultat: false, erreurs: {1,2} resultat = false = Error occurred during regeneration of the API key of the sub-account.
erreurs = Array of errors encountered

Table of Errors

Number Description
1 Id empty or sub-account does not exist
2 The system has encountered an error, please contact us

Regenerate multiple API keys

URL to call : https://www.spot-hit.es/api/sous-compte/regenerer-cle-apis

Parameters

Parameter Description
key Your API identification key
ids Id of subaccount compte to target as an array or separated by a comma

Results

Result Description
{resultat: true, sub_accounts: {id: {resultat: true, cle_api: "2d1a18835cadd5944030bxx"}}} resultat = true = Api key successfully regenerated
sub_accounts = Array of sub-accounts
cle_api = nouvelle clé api
{resultat: false, sub_accounts: {id: {resultat: false, erreurs: {1,2} }}} resultat = false = Error occurred during regeneration of the API key of the sub-account.
sub_accounts = Array of sub-accounts
erreurs = Array of errors encountered

Table of Errors

Number Description
1 Id empty or sub-account does not exist
2 The system has encountered an error, please contact us

12Short links

Listing short links

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

Parameters

Parameter Description
key Your API identification key

Results

Result
[
{"id":"1", "nom":"Redirection1", "is_online":false, "domaine_id":null, "sous_domaine":null, "extension":null, "url":null, "adresse_cible":"http:\/\/my-website.com"},
{"id":"2", "nom":"Redirection2", "is_online":true, "domaine_id":"1", "sous_domaine":"www", "extension":"promo", "url":"www.my-website.com\/promo", "adresse_cible":"http:\/\/my-website.com"}
]

Adding short links

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

Parameters

Parameter Description
key Your API identification key
adresse_cible URL targeted by the short link
extension Short link extension
nom Optional, short link name. (default: redirection)
domaine_id Optional, ID of domain name to be used. (default: sm-s.es)
sous_domaine Optional, sub-domain to be used. (default: none)

Results

Result Description
{resultat: 1, id: 58489} resultat = 1 = Component added successfully
id = Short link identifier
{resultat: 0, erreurs: 1} resultat = 0 = Error occurred during addition.
erreurs = Code of error encountered

Table of Errors

Number Description
1 Internal error.
2 Use of domain not permitted.
3 Extension already taken.
4 Target address not entered.
5 Extension not entered.
6 Domain not found.

Deleting a short link

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

Parameters

Parameter Description
key Your API identification key
id Identifier of component to be deleted

Results

Result Description
{resultat: 1, id: 58489} resultat = 1 = Component deleted successfully
id = Short link identifier
{resultat: 0, erreurs: 1} resultat = 0 = Error occurred during deletion.
erreurs = Code of error encountered

Table of Errors

Number Description
1 Error occurred during deletion of short link.
2 Short link ID not entered or does not exist.

Short link statistics

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

Parameters

Parameter Description
key Your API identification key
id Component identifier

Results

Result Description
{resultat: 1, statistiques: {...}, cliqueurs: {...}} resultat = 1 = Component deleted successfully
statistiques = All available short link statistics
cliqueurs = All short link clickers
{resultat: 0, erreurs: 1} resultat = 0 = Error occurred while retrieving statistics.
erreurs = Code of error encountered

Table of Errors

Number Description
1 Internal error.
2 Short link ID not entered or does not exist.

13Annexes

Sending an SMS via email

Operation

Messages must be sent from 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 = SMS recipient(s).
  • Contenu = SMS content.
  • Nom de l'expéditeur = SMS sender

Set parameters to be modified with your account manager :
  • Tronque (default = 1)
  • SMSlong (default = 0)
  • Type de SMS (default = premium)
  • Mail confirmation d'envoi (default = 1)
  • Mail en cas d'erreur (default = 1)
  • Expéditeur (default = Email sender’s name. May be set to always be the same.)

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.