Data API v1.2. SPRING Contact & Campaign SPLIO - SPRING Contact and Campaign DATA API EN v1.3.

Transcription

1 v1.2 SPRING Contact & Campaign SPLIO - SPRING Contact and Campaign DATA API EN v1.3.docx

2 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 SPRING Contact and Campaign... 7 SPRING Campaign only... 7 Examples... 8 Usages and samples of returned data...8 Get all lists... 8 Get all fields... 9 Get a contact... 9 Create a new contact Update a contact Double Opt-in Check if an address is in the blacklist Add an address in the blacklist Get a product Create a new product Update a product Get an order (also known as receipt ) Create a new order or abandoned cart

3 Update an order or abandoned cart Get a store Create a new store Update a store PHP code to generate API calls GET query PUT query API Call generation with Postman

4 Introduction The SPRING Data API provides resources for 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, And updating data requires the use of the PUT 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 Asia hosting 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. 4

5 Example: GET /api/data/1.2/ HTTP/1.1 ( ) HTTP/ OK ( ) "name":"data_api","version":"1.2" 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: 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. 5

6 Examples of response "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 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 address of your customer, or the cellphone number if address is not available. (Keep in mind that by default, the deduplication key is the address, so multiple contacts can share the same cellphone number and identifying customers by the cellphone number 6

7 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 ( , or ). 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. SPRING Contact and Campaign METHOD ENDPOINT USAGE RETURNS GET /api/data/1.2/lists Get all lists Array of lists GET /api/data/1.2/fields Get all custom fields Array of fields GET /api/data/1.2/contact/<customer ID> Get a contact Object of contact POST /api/data/1.2/contact Create a new contact - PUT /api/data/1.2/contact/<customer ID> Update a contact - GET /api/data/1.2/blacklist/<customer ID> Check if an address is in the blacklist PUT/POST /api/data/1.2/blacklist/<customer ID> Add an address in the blacklist HTTP 200 or SPRING Campaign only METHOD ENDPOINT USAGE RETURNS GET /api/data/1.2/product/<extid> Get a product Object of product POST /api/data/1.2/product Create a new product - PUT /api/data/1.2/product/<extid> Update a product - 7

8 GET /api/data/1.2/order/<extid> Get an order (receipt) Object of order POST /api/data/1.2/order Create a new order - PUT /api/data/1.2/order/<extid> Update an order - GET /api/data/1.2/store/<extid> Get a store Object of store POST /api/data/1.2/store Create a store - PUT /api/data/1.2/store/<extid> Update a store - Examples Usages and samples of returned data Get all lists GET /api/data/1.2/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" 8

9 Get all fields GET /api/data/1.2/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.2/contact/<customer ID> Returns all known attributes for a contact identified by <customer ID>. Example call: Basic example with Primary Key is cellphone Example with an alternate Primary Key 9

10 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 Mind to remove the leading + from the cellphone value Default known attributes are « », «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, ) «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: " ":"user@s3s.fr", "date":" :44:17", "firstname":"joshua", "lastname":"slocum", "lang":"fr", "cellphone":" ", "fields":[ "id":"0", "name":"champ1", "value":"", "id":"4", "name":"champ5", "value":"", "lists":[ "id":"0", "name":"recent members" 10

11 Create a new contact POST /api/data/1.2/contact Creates a new contact. The only mandatory value will be the 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: " ":"user@s3s.fr", "firstname":"joshua", "lastname":"slocum", "fields":[ "id":"0", "value":"abcd", "id":"1", "value":"1234", "lists":[ "id":"0", "id":"1" 11

12 Update a contact PUT /api/data/1.2/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 list. Example query data: " ":"new @s3s.fr", "firstname":"new First name", "lastname":"new Last name", "fields":[ "id":"0", "value":"xyz", "lists":[ "id":"1", "action": "unsubscribe", "id":"3" 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: 12

13 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: " ":"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 address is in the blacklist GET /api/data/1.2/blacklist/<customer ID> Returns current blacklist status of <customer ID> A 200 HTTP response means the address is blacklisted. No will be sent to it. A 404 HTTP response means the address isn t currently in any blacklist. 13

14 Examples of response: "code":404,"name":"not Found","description":" not blacklisted." Or "code":200,"name":"ok","description":" blacklisted." Add an address in the blacklist PUT /api/data/1.2/blacklist/<customer ID> Blacklist <customer ID> in your universe. Get a product GET /api/data/1.2/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": " :01:01", "date_updated": " :01:49", "name": "N 5 Eau de Parfum", "brand": "Chanel", "description": "Eau de Parfum Vaporisateur 50 ml", 14

15 "price": 91.00, "fields":[ "id":"0", "name":"pid", "value":"p23605", "id":"1", "name":"url", "value":" Create a new product POST /api/data/1.2/product Creates a new product. See GET method for accepted attributes. Example query data: "extid": "B00BIYAO3K", "name": "PlayStation 4", "brand": "Sony", "description": "Standard", "price": , "fields":[ "id":"2", "value":"b00biyao3k" 15

16 Update a product PUT /api/data/1.2/product/<extid> Updates an existing product identified by <external ID>. Only new or updated data is required. Example query data: "price": , "fields":[ "id":"2", "value":"z00biyao3k" Get an order (also known as receipt ) GET /api/data/1.2/order/<extid> Returns all known attributes for an order identified by <external ID>. Example response: "extid": "637488", "date_added": " :00:01", "date_order": " :09:19", "customer": "new@s3s.fr", "id_store": 1, "shipping_amount": 5.00, "discount_amount": 10.00, "total_price": , "order_completed": 1, "fields": [ 16

17 "id": "0", "name": "subtotal", "value": "199.00", "id": "1", "name": "order_type", "value": "order", "products": [ "extid": "B00BIYAO3K", "unit_price": , "quantity": 1.00 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.2/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. 17

18 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": " ", "customer": "id_store": 1, "shipping_amount": 5.00, "total_price": 96.00, "order_completed": 0, "fields": [, "id": "0", "name": "subtotal", "value": "29.00" "id": "1", "name": "order_type", "value": "order" "products": [ "extid": "637488", "unit_price": 91.00, "quantity":

19 Update an order or abandoned cart PUT /api/data/1.2/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": "order_completed": 1, Get a store GET /api/data/1.2/store/<extid> Returns all known attributes for a store identified by <external ID>. Example response: "extid": "1", "date_added": " :00:00", "date_updated": " :00:00", "name": "Versailles Flagship Store", "latitude": , "longitude": , "fields": [ "id": 0, "name": "phone", 19

20 "value": " ", Create a new store POST /api/data/1.2/store Creates a new store. Example query data: "extid": "2", "name": "Paris Concept Store", "latitude": "longitude": , "fields": [ "id": 0, "value": " ", Update a store PUT /api/data/1.2/store/<extid> Updates an existing store identified by <external ID>. Only new or updated data is required. Example query data: 20

21 "name": "Global Headquarters", "fields": [ "id": 0, "value": " ", 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 = " $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"; $ = "old@s3s.fr"; $service_url = " $curl = curl_init($service_url); 21

22 $query = array ( ' ' => '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)); 22

23 API Call generation with Postman 23

24 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 SPLIO - SPRING Contact and Campaign DATA API EN v1.3.docx