Documentation

API to integrate Sophia

Sophia defines the DMP platform of the poder.IO stack. The purpose of this documentation is to expose the services included in our API available for all the poder.IO’s clients to connect their platforms to the DMP.

Over the document, we will use curl commands to illustrate the interaction with Sophia’s endpoints.

Authentication

It’s mandatory to authenticate to the DMP API in order to obtain the session token to be used when calling Sophi’as endpoints defined in this documentation. To authenticate into Sophia’s API use this command:

curl -H "Content-Type: application/json" -X POST -d '{"email":"<email>","password":"<password>"}' https://api.poder.io/api/v1/users/authenticate

Where email and password will be supplied by poder.IO’s Customer Success department.

If the authentication is successful, a response like this will be returned:

{"user_id": <integer describing user id>, "auth_token":"<the token>"}

The auth_token parameter gives the token that should be used to call the endpoints defined in this document.

If the authentication is NOT successful a json with the error message will be sent, for example:

{error: “Invalid password”}

Create buyer persona

In order to export offline data of identified personas (in a CRM context those are the leads/contacts registered in the system) into poder.io, the following end point should be used:

curl -H "Content-Type: application/json" -H "Authorization: <session token>" -X POST –d '{"attributes": "email":"hernan@poder.io", "first_name":"Hernan", ….}}' http://api.poder.io/api/v1/personas

With this parameters:

auth_token - The token obtained in the authentication phase
attributes - An json object containing the data of the persona to be inserted should be passed in the body of the request. This json object should have a structure like this:

{
“attributes” : {
“first_name”: “Hernan”,
“last_name”: "Velasquez",
“email”: the_boss@poder.io”,
“phone”:”xxx-xxx-xxx”,
“city”: “Miami”
}
}

The only required attributes are email, first_name and last_name. Any other attribute can be passed with any key -> value pair. Sophia is agnostic in the name or type of the attributes received except for the required ones. For example, the “phone” attribute can be also called “telefono” (if you’re using a platform in Spanish for example), and the endpoint consumer may insert all the attributes he wants.

The response will be:

On success, STATUS: 200 and the new persona created:

{"id":318,"email":"hernan@poder.io", "first_name":"Hernan", ...}

The id returned may be used later to update this record. All the attributes created will be returned.

On error, STATUS 500 and the message:

{"error": "Unable to save persona"}

Synchronizing contacts or leads - Update buyer persona

In order to update a persona in poder.io, the following endpoint should be called:

curl -H "Content-Type: application/json" -H "Authorization: <session token>" -X PATCH –d '{"attributes": "email":"theslave@poder.io", "first_name":"Hernan", ….}}' http://api.poder.io/api/v1/personas/:id

Where :id is the id of the persona to be updated in poder.io. This id was given if when the persona was created if the previous endpoint was called.

All the attributes should be passed, no matter if they have the same value recorded before. Any attribute that is not passed, will be deleted on the platform.

The response will be: