REST API (simple)

When should I use REST Client API?

Integration through the REST API is recommended when you need to send data from an unsupported platform or if you need low-level details for some reason.

How REST Client API works?

You can find information about the REST architecture on the internet, we will limit the explanation to our use case, that is sending data from your business to Exponea.

To send data to Exponea you basically need to create a HTTP request, send it to our server and then wait for the success reply. There are few options in what data you can send, to which end point on our server and which replies from our server you can get.

Before you start

Before you start integrating your business you should have a clear understanding of how Exponea works. To learn more see How does Exponea work?

When using our REST API there is no need to initialize anything in the code like you would need to if you were using our other SDKs. However there are some important concepts that you should understand before you start the integration. You can skip the next section if you are a seasoned developer.

What is REST?

REST is a simple way to organize interaction between independent systems (for example between your business and Exponea). REST architecture is closely tied to the HTTP protocol. If you have no idea how HTTP works, you can have a look at this excellent tutorial for REST and HTTP as we will cover only the basics.

HTTP and client-server communication

HTTP is the protocol that allows for sending documents back and forth on the web. These documents can be web pages but also structured customer data from your business.

There are two roles in HTTP: client and server. The client (your business) usually starts the conversation while the server (Exponea) replies. HTTP is text based so the documents exchanged are readable. These documents are called messages and they consist of a header and a body. The body contains data you want to send (e.g. purchase) and the header contains important metadata (e.g. HTTP method used).

HTTP Requests

Every message that you will send from your business to Exponea server will have a form of a HTTP request. These requests will look something like this:

POST /endpoint HTTP/1.1 
Host: api.exponea.com
Content-Type: application/json

data-in-json-you-want-to-send

As we mentioned earlier this message consists of two parts, the header and the body.

Request header:

To make sure that the message is correctly recognized on the server you need to include an HTTP verb. Verbs tell the server what to do with the data. In our requests we will be using only one verb: POST.

You also need to specify URL which is the connecting point on the server where you want the message to be delivered. For sending events use /crm/events and for identifying/updating customers use /crm/customers.

Then there is the HTTP version that should be used: HTTP/1.1.

Of course the message can’t be delivered without identifying our server in the internet, this is the hostname api.exponea.com.

And last line in the request header is reserved for specifying content type. As you will be sending data to Exponea in the JSON format, you must use application/json.

Request body:

The body of the request is for now denoted data-in-json-you-want-to-send. We will talk more about the structure of JSON in the following parts of this guide.

HTTP Response

After you send an HTTP request to our server, you should receive a response immediately. This response is in JSON format and should look like this:

{
  "errors": [],
  "success": true
}

Start and end time are only for information purposes, the important things are “success” field (indicates if request was received correctly) and “status” field (indicates if request completed successfully).

You should check if every request that you send is handled correctly at our side. This way you can be sure that the data will be added to your project in Exponea.

Sending data to Exponea

Sending events

To send events to Exponea you will always be using this template HTTP request.

Template HTTP request:

POST /crm/events HTTP/1.1
Host: api.exponea.com
Content-Type: application/json

{  
   "customer_ids": { "registered": "unique ID" } ,
   "project_id":"project token",
   "type": "event name",
   "properties": {
       "event property name": "event property value",
   },
   "timestamp": 1465906739
}
  • /crm/events is address on Exponea server that will handle HTTP request for sending events.
  • customer_ids is object with customer ids. Events originate from customers, this way we can assign them using unique ID usually email.
  • project_id is your project token which can be found in Project -> Overview
  • type is used to store event name such as purchase, click, session start…
  • properties object with event properties. This field is not required.
  • timestamp unix time stamp. If not provided, timestamp will be automatically generated on our servers. timestamp can be used to add events from past.

Identifying/updating customers

For identification and updating customers in Exponea you will always be using this template HTTP request.

Template HTTP request:

POST /crm/customers HTTP/1.1
Host: api.exponea.com
Content-Type: application/json

{  
   "ids": { "registered": "unique ID" },
   "project_id":"project token",
   "properties": {
       "customer property name": "customer property value"
   }
}
  • ids is object with customer ids. Each customer should have unique id, for example email.
  • project_id is your project token which can be found in Project -> Overview
  • properties object with customer properties, for example email, name, birthday… This field is not required.

Handling HTTP responses

Whenever you send an HTTP request to Exponea API you should wait for a response.

The response is in a JSON format and contains “results” array. This array contains a list of responses for every command you sent in the request. The sequence of responses in this array is the same as the sequence of commands sent in the request.

Example response:

{
  "errors": [],
  "success": true
}

There are three possible “status” values:

  • “ok” – the command was executed successfully
  •  “error” – the command failed and a list of error messages is returned in the errors key
  • “retry” – the command was not processed, retry submitting it later. A list of error messages is returned in the errors key.

Only response “ok” means that the command was executed and handled correctly so it will be available in your project. If you keep getting “error” messages please write to our support at support@exponea.com.

Key descriptions

In the following table you can find the description of all keys (fields) used for sending data through our REST Client API.

Key (field) Description
customer_ids
  • customer identifiers ( “cookie” for identifying anonymous customers or “registered” for identifying known customers)
  • required (when tracking an event)
 ids
  • customer identifiers ( “cookie” for identifying anonymous customers or “registered” for identifying known customers)
  • required (when identyfing a customer or when setting/updating a customer attribute)
project_id
  • project token (you can find it in the Overview section of your project)
  • required
type
  • event name (type), should be human readable (e.g. “item view”, “purchase”)
  • required (when tracking an event)
 properties
  • attributes that specify either event (when you are using attributes in the event tracking) or customer (when you are setting/updating customer attributes)
  • not required
 timestamp
  • a UNIX timestamp from the time the event was generated (can be a float)
  • each event per customer should have a unique timestamp so the order of events is not random when analysing event flow (if there are two events with the same timestamp it is sufficient to increment one by one thousandth)
  • not required (if omitted from the command, our server will add the timestamp to the event automatically with the time of when is the request received)