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

https://s3s.fr/api/data/1.9

Asia hosting

https://spli2.cn/api/data/1.9

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"}

{"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"}

{"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."}

{"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));

API Call generation with Postman

Articles in this section

Introduction

Access

Europe hosting

Asia hosting

Authentication

Request format

Response format

Error Codes & Responses

Unique Customer ID

Default cases

Custom cases

Specific cases

Endpoints

All editions: Contact, Connect, Omnicommerce

Only Connect and Omnicommerce

Examples

Lists, blacklists and contacts’ data

Get all lists

Get all fields

Get a contact

Create a new contact

Update a contact

Delete a contact

Double Opt-in

Check if an email address is in the blacklist

Add an email address in the blacklist

Sales data

Get a product

Create a new product

Update a product

Get a store

Create a new store

Update a store

Get an order (also known as “order”)

Create a new order or abandoned cart

Update an order or abandoned cart

PHP code to generate API calls

GET query

PUT query

API Call generation with Postman

Related articles