SPLIO Customer Platform - DATA API 1.9 - EN - 2018-08-20- v1.docx

Data API v1.9

Splio Customer Platform

2018-08-20

2

Data API 1.9

Table of Contents Introduction ............................................................................................................... 4

Access ....................................................................................................................... 4

Base URL .....................................................................................................................................4

Europe hosting ................................................................................................................................................... 4

Asia hosting ........................................................................................................................................................ 4

Authentication ..........................................................................................................................5

Request format..........................................................................................................................5

Response format .......................................................................................................................5

Error Codes & Responses ................................................................................................................................. 5

Unique Customer ID .................................................................................................................6

Default cases ..................................................................................................................................................... 6

Custom cases .................................................................................................................................................... 7

Specific cases .................................................................................................................................................... 7

Endpoints ....................................................................................................................................7

All editions: Contact, Connect, Omnicommerce ....................................................................................... 7

Only Connect and Omnicommerce ............................................................................................................. 7

Examples ................................................................................................................... 8

Lists, blacklist and contacts’ data .........................................................................................8

Get all lists ........................................................................................................................................................... 8

Get all fields........................................................................................................................................................ 9

Get a contact.................................................................................................................................................... 9

Create a new contact ................................................................................................................................... 10

Update a contact ........................................................................................................................................... 11

Delete a contact ............................................................................................................................................ 12

Double Opt-in .................................................................................................................................................. 13

Check if an email address is in the blacklist ............................................................................................... 14

Add an email address in the blacklist ......................................................................................................... 14

Sales data ............................................................................................................................... 14

Get a product.................................................................................................................................................. 14

Create a new product ................................................................................................................................... 15

Update a product ........................................................................................................................................... 16

Get a store ....................................................................................................................................................... 16

3

Data API 1.9

Create a new store ......................................................................................................................................... 17

Update a store ................................................................................................................................................. 17

Get an order (also known as “receipt”) ..................................................................................................... 18

Create a new order or abandoned cart ................................................................................................... 19

Update an order or abandoned cart ......................................................................................................... 21

Loyalty data ............................................................................................................................ 21

Get a contact.................................................................................................................................................. 21

Create a new contact with a loyalty subscription ................................................................................... 22

Update a contact with loyalty subscription ............................................................................................... 23

Get an order (“receipt”) linked to a loyalty member .............................................................................. 23

Create a new order linked to a loyalty member ...................................................................................... 25

Update an order to link it to a loyalty member ......................................................................................... 26

PHP code to generate API calls ......................................................................................... 26

GET query.......................................................................................................................................................... 26

PUT query .......................................................................................................................................................... 27

API Call generation with Postman ..................................................................................... 28

4

Data API 1.9

Introduction The SPRING Data API provides resources for Splio customers or partners to insert or update database entries within their SPRING 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 DELELETE method.

The SPRING 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://api.spl4cn.com/api/data/1.9/

In the next pages of this document, 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.

5

Data API 1.9

Example:

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)

Example:

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 response

6

Data API 1.9

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

7

Data API 1.9

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 (receipt) Object of order

POST /api/data/1.9/order Create a new order -

PUT /api/data/1.9/order/<extid> Update an order -

8

Data API 1.9

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, blacklist 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" } ] }

9

Data API 1.9

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

10

Data API 1.9

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

11

Data API 1.9

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.

12

Data API 1.9

¤ Unsubscribe action: If there is an optional « action » attribute with value ‘unsubscribe’, the contact will be removed from the associated list.

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

13

Data API 1.9

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

14

Data API 1.9

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 blacklisted. 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

15

Data API 1.9

¤ 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",

16

Data API 1.9

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

{

17

Data API 1.9

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

18

Data API 1.9

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 “receipt”)

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"

19

Data API 1.9

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

20

Data API 1.9

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": "53205961", "customer": "new@s3s.fr", "id_store": 1, "shipping_amount": 5.00, "total_price": 96.00, "order_completed": 0,

"tax_amount": "0.00", "currency": "EUR", "salesperson": "Tom",

"fields": [ { "id": "0", "name": "subtotal", "value": "29.00" }, { "id": "1", "name": "order_type", "value": "order" } ], "products": [

{ "extid": "637488", "unit_price": 91.00, "quantity": 1.00

"discount_amount": "0.00", "tax_amount": "0.00", "total_line_amount": "91.00", "currency": "EUR", "fields": [ { "id": "0", "value": "best seller" } ]

} ]

21

Data API 1.9

}

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

1) Only new or updated data are required FOR THE SOLELY ORDER FIELDS 2) 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, }

Loyalty data

When Loyalty is activated on your universe, Loyalty data are added to these following APIs.

Get a contact

GET /api/data/1.9/contact/<customer ID>

Returns all known attributes for a contact identified by <customer ID>.

Example response:

{ "email":"user@s3s.fr", "date":"2016-01-01 11:44:17", "firstname":"Joshua",

22

Data API 1.9

"lastname":"Slocum", "lang":"fr", "cellphone":"+33660200000", "fields":[ { "id":"0", "name":"champ1", "value":"" } ], "lists":[ { "id":"0", "name":"Recent members" } ],

"loyalty": [ { "card_code": "CC0003", "id_program": "1" } ]

}

Create a new contact with a loyalty subscription

POST /api/data/1.9/contact

Creates a new contact. The only mandatory value will be the email address.

You can directly subscribe this new contact in a Loyalty program by adding the program_id and the wanted card_code in the query.

Example query data:

{ "email":"user@s3s.fr", "firstname":"Joshua", "lastname":"Slocum",

“program_id”:”1”, “card_code”:”XXXX”,

"fields":[ { "id":"0", "value":"abcd" },

23

Data API 1.9

{ "id":"1", "value":"1234" } ], "lists":[ { "id":"0" }, { "id":"1" } ] }

Update a contact with loyalty subscription

PUT /api/data/1.9/contact/<customer ID>

Updates an existing contact identified by <customer ID> and subscribes him to a loyalty program (if program_id and card_code are added to the query).

Example query data:

{ "email":"newemail@s3s.fr", "firstname":"New First name", "lastname":"New Last name",

"card_code":"XXX00001", "program_id":"1",

"fields":[ { "id":"0", "value":"xyz" } ] }

Get an order (“receipt”) linked to a loyalty member

GET /api/data/1.9/order/<extid>

Returns all known attributes for an order identified by <external ID> with the card_code and program_id used for this order.

24

Data API 1.9

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

} ] ,

"loyalty": [ {

25

Data API 1.9

"card_code": "CC0003", "id_program": "1" } ]

}

Create a new order linked to a loyalty member

POST /api/data/1.9/order

Creates a new order linked to a loyalty member (using its card_code)

Example query data:

{ "extid": "53205961", "customer": "new@s3s.fr",

“card_code”:”0001”, "id_store": 1, "shipping_amount": 5.00, "total_price": 96.00, "order_completed": 1,

"tax_amount": "0.00", "currency": "EUR", "salesperson": "Tom",

"fields": [ { "id": "0", "name": "subtotal", "value": "29.00" }, { "id": "1", "name": "order_type", "value": "order" } ], "products": [

{ "extid": "637488", "unit_price": 91.00, "quantity": 1.00

"discount_amount": "0.00", "tax_amount": "0.00",

26

Data API 1.9

"total_line_amount": "91.00", "currency": "EUR", "fields": [ { "id": "0", "value": "best seller" } ]

} ] }

Update an order to link it to a loyalty member

PUT /api/data/1.9/order/<extid>

Updates an existing order identified by <external ID>.

If the loyalty member was not set at the order creation, the order can be updated to add the link.

Example query data on order fields only:

{ "extid": "53205961", "card_code": “00001” }

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

27

Data API 1.9

$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));

28

Data API 1.9

API Call generation with Postman

SPLIO Customer Platform - DATA API 1.9 - EN - 2018-08-20- v1.docx

www.splio.com

www.splio.com.br - www.splio.cn - www.splio.es www.splio.fr - www.splio.it - www.splio.pl

SPLIO is a SaaS marketing software company specialized in Retail. Our SaaS Customer Experience Platform ties together all essential components to implement a digital customer hub orchestrating processes of realtime omnichannel strategies. Building on 15 years of vision, partnerships and understanding of the needs of 500+ global and local retailers, SPLIO has developed a unique intuitive platform that allows marketers to unleash their strategy and aligns all departments of a company ensuring a consistent customer centric approach.

SPLIO has offices in Paris, Barcelona, Milan, Beijing, Shanghai, Warsaw and São Paulo.