This API is deprecated. We strongly advise you to use the Splio Customer Platform API instead. Please note that Loyalty features for data coming through DATA API are not supported anymore.
Introduction
The Splio Data API provides resources for Splio customers or partners to insert or update database entries within their Splio universe.
The API intends to be mostly RESTful and entirely HTTP-based
Retrieving data requires the use of the GET method, Inserting data requires the use of the POST method, Updating data requires the use of the PUT method,
And deleting data requires the use of the DELETE method.
The SPLIO Data API does not change the customer’s data structure (neither adding a field nor changing the field types). The database structure must be defined prior to invoking the API.
Access
Base URL
Like other SPRING APIs, the base URL depends on the hosting location of the universe.
If you’re unsure about the hosting location of your universe, please ask your Customer Success Manager.
Europe hosting
Asia hosting
In the next paragraphs of this article, the examples are using either of the base URLs. However, you need to stick to the one relevant to your own case.
HTTPS is both required and enforced. Any request to the http (non-secured) address will be rejected without any automatic redirection to the secured URL.
GET /api/data/1.9/ HTTP/1.1
(…)
HTTP/1.1 200 OK
(…)
{"name":"DATA_api","version":"1.9"}
Authentication
All requests need to be authenticated through standard HTTP credentials.
These credentials are generated and communicated to the customer upon request.
- universe id (e.g.: my_universe_id)
- password (e.g.: my_api_key)
https://my_universe_id:my_api_key@s3s.fr/api/data/1.9/lists
Request format
Parameter values should use UTF-8 encoding and JSON formatting. Plain HTTP POST data is also supported.
Response format
Data returned in response messages is always UTF-8 encoded and JSON formatted. The unique response language is English.
Error Codes & Responses
Responses are returned as JSON objects that contain "code", "name" and "description" attributes. "code" and "name" are the HTTP code and name response.
Examples of responses:
{"code":200,"name":"OK","description":"ok"}
or
{"code":404,"name":"Not Found","description":"specified resource does not exist"}
Response list
- 200 => OK
- 201 => Created
- 202 => Accepted, The request has been accepted for processing
- 204 => No Content
- 304 => Not Modified
- 400 => Bad Request
- 401 => Unauthorized, You must enter a valid ID and password to access this resource
- 403 => Forbidden
- 404 => Not Found
- 405 => Method Not Allowed
- 406 => Not Acceptable, Requested data format not supported
- 500 => Internal Server Error, Something is broken
- 501 => Not Implemented
Unique Customer ID
By default, a SPRING Campaign universe is set up with the email address of a contact being the deduplication key in the customer database.
You can ask to have your universe configured with a custom unique key (your own customer ID, or the cellphone, for example), later named customer ID, to fit with your own database schema.
Default cases
“Customer ID” will have to be replaced with the email address of your customer, or the cellphone number if email address is not available. (Keep in mind that by default, the deduplication key is the email address, so multiple contacts can share the same cellphone number and identifying customers by the cellphone number could cause unexpected results). Also, please make sure the cellphone number is always written in the international format (“00” or “+” prefix, followed by the country prefix) when using it as a customer ID (+33600000000, or 0033600000000).
Custom cases
“Customer ID” will have to be replaced with the unique key (custom field) you have chosen with your Account Manager.
Specific cases
In the unlikely situation where your universe has been set up with a set of multiple custom fields as a unique key (customer ID + contract ID for example), “Customer ID” will have to be replaced with values joined by a comma in the specific order).
Endpoints
The following table lists the available endpoints and their usage. Examples are provided later in the document.
All editions: Contact, Connect, Omnicommerce
METHOD |
ENDPOINT |
USAGE |
RETURNS |
||||
GET |
/api/data/1.9/lists |
Get all lists |
Array of lists |
||||
GET |
/api/data/1.9/fields |
Get all custom fields |
Array of fields |
||||
GET |
/api/data/1.9/contact/<customer ID> |
Get a contact |
Object of contact |
||||
POST |
/api/data/1.9/contact |
Create a new contact |
- |
||||
PUT |
/api/data/1.9/contact/<customer ID> |
Update a contact |
- |
||||
DELETE |
/api/data/1.9/contact/<customer ID> |
Delete a contact |
HTTP 200 or 404 |
||||
GET |
/api/data/1.9/blacklist/<customer ID> |
Check if an email address is in the blacklist |
HTTP 200 or 404 |
||||
PUT/POST |
/api/data/1.9/blacklist/<customer ID> |
Add an email address in the blacklist |
- |
Only Connect and Omnicommerce
METHOD |
ENDPOINT |
USAGE |
RETURNS |
GET |
/api/data/1.9/product/<extid> |
Get a product |
Object of product |
POST |
/api/data/1.9/product |
Create a new product |
- |
PUT |
/api/data/1.9/product/<extid> |
Update a product |
- |
GET |
/api/data/1.9/order/<extid> |
Get an order (order) |
Object of order |
POST |
/api/data/1.9/order |
Create a new order |
- |
PUT |
/api/data/1.9/order/<extid> |
Update an order |
- |
GET |
/api/data/1.9/store/<extid> |
Get a store |
Object of store |
POST |
/api/data/1.9/store |
Create a store |
- |
PUT |
/api/data/1.9/store/<extid> |
Update a store |
- |
Examples
Lists, blacklists and contacts’ data
Get all lists
GET /api/data/1.9/lists
Returns all lists defined for your universe. Example response:
{
"lists":[
{
"id":"0",
"name":"first list",
"members":"7487"
},
{
"id":"1",
"name":"VIP",
"members":"45"
},
{
"id":"3",
"name":"members", "members":"10245"
}
]
}
Get all fields
GET /api/data/1.9/fields
Returns existing custom fields in the given universe. Example response:
{
"fields":[
{
"id":"2",
"name":"custom reserved field"
},
{
"id":"5",
"name":"refererId"
},
{
"id":"6",
"name":"78"
}
]
}
Get a contact
GET /api/data/1.9/contact/<customer ID>
Returns all known attributes for a contact identified by <customer ID>. Example call:
Basic example with Primary Key is cellphone:
https://myUniverse:myAPIkey@s3s.fr/api/data/1.9/contact/341234550284 Example with an alternate Primary Key
assuming you altered the default primary key of the universe into two fields composing the primary key, then the customer id is specified with the two fields values separated with a comma, not enclosed with quotes nor double-quotes
https://myUniverse:myAPIkey@s3s.fr/api/data/1.9/contact/12,341234550284
Mind to remove the leading + from the cellphone value
Default known attributes are « email », « date », « firstname », « lastname », « lang »,
« cellphone », « fields » and « lists ».
Attribute « cellphone » is displayed only if it is not empty. It is formatted as an international telephone number (for instance, +33660200000)
« fields » attribute is a list of all the custom fields defined for the universe and their associated values. Field attributes are « id », « name » and « value ».
« lists » attribute is the full membership list for the contact. List attributes are « id » and « name ».
Example response:
{
"email":"user@s3s.fr", "date":"2018-07-12 11:44:17",
"firstname":"Joshua", "lastname":"Slocum", "lang":"fr", "cellphone":"+33660200000", "fields":[
{
"id":"0",
"name":"champ1",
"value":""
},
{
"id":"4",
"name":"champ5",
"value":""
}
],
"lists":[
{
"id":"0",
"name":"Recent members"
}
]
}
Create a new contact
POST /api/data/1.9/contact
Creates a new contact. The only mandatory value will be the email address. See GET method for accepted attributes.
Please note:
- A “fields” element requires an “id” or a “name”, along with the “value”.
- A “lists” element requires an “id” or a “name”.
We strongly recommend you use the id instead of the name, since renaming a field or a name from SPRING’s interface would break your API calls.
Example query data:
{
"email":"user@s3s.fr", "firstname":"Joshua", "lastname":"Slocum", "fields":[
{
"id":"0",
"value":"abcd"
},
{
"id":"1",
"value":"1234"
}
],
"lists":[
{
"id":"0"
},
{
"id":"1"
}
]
}
Update a contact
PUT /api/data/1.9/contact/<customer ID>
Updates an existing contact identified by <customer ID>.
The recommendations for POST requests also apply for PUT ones.
- Unsubscribe action: If there is an optional « action » attribute with value ‘unsubscribe’, the contact will be removed from the associated
Example query data:
{
"email":"newemail@s3s.fr", "firstname":"New First name", "lastname":"New Last name", "fields":[
{
"id":"0",
"value":"xyz"
}
],
"lists":[
{
"id":"1",
"action": "unsubscribe"
},
{
"id":"3"
}
]
}
Delete a contact
DELETE /api/data/1.9/contact/<customer ID>
Deletes all data on the contact (system and custom fields) but keeps and anonymizes its activities and sales data:
A 200 HTTP response means the contact has been deleted.
A 404 HTTP response means the contact is unknown and has not been deleted.
Examples of response:
{"code":404,"name":"Not Found","description":"contact not found in database"}
or
{"code":200,"name":"ok","description":"ok
Double Opt-in
If you want to require subscribing contacts to confirm their subscription by sending a confirmation request first, you can use the “double opt-in” option available in both POST and PUT methods.
Just add a “doubleoptin” section with the following parameters:
- “message”: id of the message that must be sent. This message must contain a link to $confirmUrl$
- “reminder_delay”: if you want a reminder to be sent, specify the number of days between the first message and the reminder
- “reminder”: id of the reminder message. This message must contain $confirmUrl$ as well
Example query data:
{
"email":"user@s3s.fr", "firstname":"Joshua", "lastname":"Slocum", "fields":[
{
"id":"0",
"value":"abcd"
}
],
"lists":[
{
"id":"0"
}
],
"doubleoptin":{ "message":"6UMY3a5bk", "reminder":"6UOydaa3F", "reminder_delay":10
}
}
Check if an email address is in the blacklist
GET /api/data/1.9/blacklist/<customer ID>
Returns current blacklist status of <customer ID>
A 200 HTTP response means the address is in blacklist. No email will be sent to it. A 404 HTTP response means the address isn’t currently in any blacklist.
Examples of response:
{"code":404,"name":"Not Found","description":"email not blacklisted."}
or
{"code":200,"name":"OK","description":"email blacklisted."}
Add an email address in the blacklist
PUT /api/data/1.9/blacklist/<customer ID>
blacklist <customer ID> in your universe.
Sales data
Get a product
GET /api/data/1.9/product/<extid>
Returns all known attributes for a product identified by <external ID> (this ID being the unique identifier, chosen during the setup of your universe).
Examples of external IDs:
- Product’s SKU
- E-commerce database’s product ID
Example response:
{
"extid": "637488",
"date_added": "2018-06-12 15:01:01",
"date_updated": "2018-07-12 02:01:49", "name": "N°5 Eau de Parfum",
"brand": "Chanel",
"description": "Eau de Parfum Vaporisateur 50 ml", "price": 91.00,
"sku": "1258998746",
"category": "Parfum",
"img_url": "http://www.store.com/?media=1258998746.jpeg", "fields":[
{
"id":"0",
"name":"pid",
"value":"P23605"
},
{
"id":"1",
"name":"url", "value":"http://www.store.com/?PID=P23605&SKU=637488"
}
]
}
Create a new product
POST /api/data/1.9/product
Creates a new product.
See GET method for accepted attributes.
Example query data:
{
"extid": "B00BIYAO3K",
"name": "PlayStation 4", "brand": "Sony", "description": "Standard", "price": 349.00,
"sku": "1258998746",
"category": "Parfum",
"img_url": "http://www.store.com/?media=1258998746.jpeg", "fields":[
{
"id":"2", "value":"B00BIYAO3K"
}
]
}
Update a product
PUT /api/data/1.9/product/<extid>
Updates an existing product identified by <external ID>. Only new or updated data is required.
Example query data:
{
"price": 399.00,
"fields":[
{
"id":"2", "value":"Z00BIYAO3K"
}
]
}
Get a store
GET /api/data/1.9/store/<extid>
Returns all known attributes for a store identified by <external ID>.
Example response:
{
"extid": "1",
"date_added": "2013-02-01 10:00:00",
"date_updated": "2013-02-01 10:00:00", "name": "Versailles Flagship Store", "channel": "offline",
"store_type": "Flagship", "manager": "Tom", "fields": [
{
"id": 0,
"name": "phone",
"value": "01 84 73 11 30",
}
]
}
Create a new store
POST /api/data/1.9/store
Creates a new store.
Example query data:
{
"extid": "2",
"name": "Paris Concept Store", "channel": "offline", "store_type": "Flagship", "manager": "Tom",
"fields": [
{
"id": 0,
"value": "01 84 73 11 10",
}
]
}
Update a store
PUT /api/data/1.9/store/<extid>
Updates an existing store identified by <external ID>. Only new or updated data is required.
Example query data:
{
"name": "Global Headquarters", "fields": [
{
"id": 0,
"value": "01 84 73 11 11",
}
]
}
Get an order (also known as “order”)
GET /api/data/1.9/order/<extid>
Returns all known attributes for an order identified by <external ID>.
Example response:
{
"extid": "637488",
"date_added": "2015-11-23 18:00:01",
"date_order": "2015-11-23 18:09:19",
"customer": "new@s3s.fr", "id_store": 1,
"shipping_amount": 5.00,
"discount_amount": 10.00,
"total_price": 344.00,
"order_completed": 1,
"tax_amount": "0.00",
"currency": "EUR", "salesperson": "Tom", "fields": [
{
"id": "0",
"name": "subtotal",
"value": "199.00"
},
{
"id": "1",
"name": "order_type", "value": "order"
}
],
"products":
[
{
"extid": "B00BIYAO3K",
"unit_price": 349.00,
"quantity": 1.00,
"discount_amount": "0.00",
"tax_amount": "0.00",
"total_line_amount": "349.00", "currency": "EUR",
"fields": [
{
"id": "0",
“name”:”type”, "value": "best seller"
}
]
}
]
}
Note: “date_added” is the date and time the order was inserted in database. “date_order” is the date and time the order was updated as “completed”. These fields can therefore share the same value if completed orders are submitted in one API call.
Create a new order or abandoned cart
POST /api/data/1.9/order
Creates a new order.
Note: This data structure is designed to receive both completed and uncompleted orders. Uncompleted orders can be considered as “abandoned baskets”* and trigger automatic follow-up campaigns.
When submitting a new order, if omitted, the “order_completed” parameter will be set to 1 by default.
The parameters “date_added” and “date_order” are optional; if not provided, they will be set with the time of the API call.
*A.k.a. Abandoned Carts
Example query data:
{ "extid": "54291632", "customer": "jdoe@test.com", "id_store": 1, "shipping_amount": 5.00, "total_price": 96.00, "order_completed": 0, "tax_amount": 1.00, "currency": "EUR", "salesperson": "Tom", "fields": [ { "id": "0", "name": "subtotal", "value": "29.00" }, { "id": "1", "name": "order_type", "value": "order" } ], "products": [ { "extid": "B00BIYAO3K", "unit_price": 91.00, "quantity": 1.00, "discount_amount": 3.00, "tax_amount": 2.00, "total_line_amount": 91.00, "currency": "EUR", "fields": [ { "id": "0", "value": "best seller" } ] } ] }
Update an order or abandoned cart
PUT /api/data/1.9/order/<extid>
Updates an existing order identified by <external ID>. Beware of the API behavior with regards to the update
- Only new or updated data are required FOR THE SOLELY ORDER FIELDS
- If you intend to apply changes on the products, then the ENTIRE DATA IS MANDATORY because the API will replace all values on the lines.
Example query data on order fields only:
{
"customer": "news@s3s.fr", "order_completed": 1,
}
PHP code to generate API calls
GET query
Getting lists using PHP with the curl library:
$universe = "testapi";
$pass = "my secret api key";
$resource = "lists";
$service_url = "https://$universe:$pass@s3s.fr/api/data/1.9/$resource";
$curl = curl_init($service_url);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // just for the example. curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_setopt($curl,CURLOPT_HTTPHEADER,array("Expect:"));
$curl_response = curl_exec($curl); curl_close($curl); var_dump($curl_response);
var_dump(json_decode($curl_response, true));
PUT query
Updating a contact using PHP with the curl library:
$universe = "testapi";
$pass = "my secret api key";
$resource = "contact";
$email = "old@s3s.fr";
$service_url = "https://$universe:$pass@s3s.fr/api/data/1.9/$resource/$email";
$curl = curl_init($service_url);
$query = array (
'email' => 'newmail@s3s.fr', 'lang' => 'de',
'fields' => array (
array ( 'id' => '0', 'value' => 'bl10'),
array ( 'name' => 'field2', 'value' => 'myothercustomfield_value')
),
'lists' => array (
array ( 'name' => 'Test Api' ),
array ( 'id' => '5', 'action' => 'unsubscribe' )
)
);
$qstring = json_encode($query);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // just for the example. curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "PUT"); curl_setopt($curl, CURLOPT_POSTFIELDS,$qstring); curl_setopt($curl,CURLOPT_HTTPHEADER,array("Expect:"));
$curl_response = curl_exec($curl); curl_close($curl); var_dump($curl_response);
var_dump(json_decode($curl_response, true));