Quick Start

Introduction

This guide will bring you basic knowlegde needed to enter ACTITO Integration Framework. Once you've successfully completed this guide, you'll be able to retrieve a list of entities, retrieve the list of profile tables linked to the first entity found and create a profile in the first table found.

Step by step

Get an authorization token
Get all entities in your licence
Get all profile table names for an entity
Get the structure of a profile table
Create a new profile in this profile table

Prerequisites

Take a look at our concepts section for few explanations on entities and profile tables in ACTITO.
Make sure some entities and linked profile tables exist in your licence (check with your marketeer).
If you don't already have an API Key for the API authentication, ask your licence supervisor or our Support Team.

Step 0. Get an authorization token

Check API Key Authentication section for full details.

Step 1. Get all entities

The first ever call you should make on ACTITO API is to check the ACTITO entities you have access to. As resources in ACTITO are linked to an entity, you will only be able to retrieve resources linked to an entity you have access to.

To get all entities, you need to make an HTTP call to

GET /entities/v5/entities

Make sure to provided the following headers:

Authorization header with generated Bearer access token
Accept header with value application/json to tell the API to return a plain json response.

Below is a curl command for the corresponding call with all needed parameters:

curl -X GET \
  https://api.actito.com/entities/v5/entities \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA'

In case you missed the credentials or if you provide wrong credentials, you will get a 401 Unauthorized http response status.

If you provide an incorrect or not accepted value in the Accept header, you will get a 406 Not acceptable http response status.

If everything is ok, you should receive a 200 OK http response. The response should have a Content-type header with value application/json and the body should be something like:

{
  "entities": [
    {
      "id": 1,
      "name": "integrationframeworksandbox",
      "comment": null
    }
  ]
}

As you can see, the json response is a plain json object, with an entities attribute which is an array of entity.

An entity has an id, a name and possibly a comment. The id is the technical id and the name is the technical name. Both are unique for your licence. Comment should contain a description of what is the purpose of this entity, who should have access to it etc.

Step 2. Get all profile table names for an entity

It's now time to retrieve the available profile tables in the first entity we found in Step 1.

That can be done be making a call to:

GET /profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables

Here you can see that the "integrationframeworksandbox" in the url is the technical name of the first entity we got at Step 1.

Please note that for now, you can not use the technical id of the entity in the urls. In consequence, a call with following url will return a 404 NOT FOUND http response status:

GET /profile-table-structure/v5/entities/1/profile-tables

As for retrieving entity list and for any API call, you should include Accept and Authorization headers. See above.

Here is the full curl command:

curl -X GET \
  https://api.actito.com/profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA'

If everything is ok, you should receive a 200 OK http response. The response should have a Content-type header with value application/json and the body should be something like:

{
  "profileTableNames": [
    {
      "name": "Contacts"
    }
  ]
}

The json response is a plain json object, with an profileTableNames attribute which is an array of object with single property name.

Those names stand for the technical names of existing profile tables within the provided entity.

Step 3. Get the structure of a profile table

Now you know since Step 2. that a Contacts profile table exists, you can get the structure of that profile table to check the attributes you should provide when creating a new profile (see Step 4.).

You have now to call the following url:

GET /profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables/Contacts

Don't forget to include Accept and Authorization headers.

The curl command:

curl -X GET \
  https://api.actito.com/profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables/Contacts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA'

When all parameters ok, you'll receive a 200 OK http response. The response should have a Content-type header with value application/json and the body will be something like:

{
  "id": 1,
  "name": "Contacts",
  "attributes": {
    "addressCountry": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Country",
      "possibleValues": [],
      "comment": "Address country"
    },
    "lastName": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Name",
      "possibleValues": [],
      "comment": "Last name"
    },
    "telephoneNumber": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "PhoneNumber",
      "possibleValues": [],
      "comment": "Home phone number"
    },
    "contactId": {
      "mandatory": true,
      "multiValue": false,
      "unicity": "UNIQUE_FOR_ALL_ELEMENTS",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "contact's unique and mandatory ID"
    },
    "sex": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Sex",
      "possibleValues": [],
      "comment": "Sex"
    },
    "source": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "contact's creation source"
    },
    "birthDate": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Datum",
      "possibleValues": [],
      "comment": "Birth date"
    },
    "firstName": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Name",
      "possibleValues": [],
      "comment": "First name"
    },
    "addressPostalCode": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "Address postal code"
    },
    "emailAddress": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "EmailAddress",
      "possibleValues": [],
      "comment": "e-Mail address"
    },
    "companyId": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": null
    },
    "addressStreet": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "Address street"
    },
    "addressLocality": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "Address locality"
    },
    "shopId": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": null
    },
    "addressRegion": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "contact's address (region)"
    },
    "motherLanguage": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "Language",
      "possibleValues": [],
      "comment": "Mother language"
    },
    "gsmNumber": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "PhoneNumber",
      "possibleValues": [],
      "comment": "Mobile number"
    }
  },
  "subscriptions": [
    {
      "name": "optinEmailNL",
      "id": 1
    },
    {
      "name": "optinEmailPromo",
      "id": 2
    },
    {
      "name": "optinSMS",
      "id": 3
    },
    {
      "name": "optinEmailPartners",
      "id": 4
    },
    {
      "name": "cinemaPreference",
      "id": 5
    },
    {
      "name": "artPreference",
      "id": 6
    },
    {
      "name": "newsPreference",
      "id": 7
    },
    {
      "name": "sciencePreference",
      "id": 8
    }
  ],
  "segmentations": []
}

Step 4. Create a new profile

You have now everything you need to create a profile in the Contacts profile table, knowing the attributes you should provide.

The call should be a POST request with a json body that matches the structure of a profile of the Contacts table. The Content-type header will have to contain the value application/json to specify to the API that you will send the body as a json object.

Please note that the following route is by default implementing a "create or update" behavior. This default behavior can be changed by passing the allowUpdate query param with value false

The API call will then be:

POST /profiles/v4/entity/integrationframeworksandbox/table/Contacts/profile/?allowUpdate=false

With a body like in the following example:

{
  "attributes": [
    {
      "name": "addressCountry",
      "value": "BE"
    },
    {
      "name": "lastName",
      "value": "Smith"
    },
    {
      "name": "telephoneNumber",
      "value": "+3267675674"
    },
    {
      "name": "contactId",
      "value": "123456"
    },
    {
      "name": "sex",
      "value": "M"
    },
    {
      "name": "source",
      "value": "myWebsite"
    },
    {
      "name": "birthDate",
      "value": "21/02/1961"
    },
    {
      "name": "firstName",
      "value": "John"
    },
    {
      "name": "addressPostalCode",
      "value": "75009"
    },
    {
      "name": "emailAddress",
      "value": "john.smith@actito.com"
    },
    {
      "name": "companyId",
      "value": "1"
    },
    {
      "name": "motherLanguage",
      "value": "FR"
    },
    {
      "name": "gsmNumber",
      "value": "+3242343214"
    }
  ],
  "subscriptions": [
    {
      "name": "optinEmailNL",
      "subscribe": true
    },
    {
      "name": "optinEmailPromo",
      "subscribe": true
    },
    {
      "name": "optinSMS",
      "subscribe": true
    },
    {
      "name": "cinemaPreference",
      "subscribe": true
    },
    {
      "name": "sciencePreference",
      "subscribe": true
    },
    {
      "name": "optinEmailPartners",
      "subscribe": false
    },
    {
      "name": "artPreference",
      "subscribe": false
    },
    {
      "name": "newsPreference",
      "subscribe": false
    }
  ]
}

If you miss one mandatory attribute in the request body or if you provide a wrong value for an attribute that has value constraints (check mandatory and constraints aspect in your profile table structure), you will receive a 400 BAD REQUEST http response.

A bad request response always contains a body that describes the reason of the reject. The idea is to provide enough info to allow the developer to understand the reason and to take measures to avoid it.

Below you'll find an example of bad call and reject response when providing a wrong value for the sex attribute:

curl -X POST \
  https://api.actito.com/profiles/v4/entity/integrationframeworksandbox/table/Contacts/profile/?allowUpdate=false \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA' \
  -H 'Content-Length: 1324' \
  -H 'Content-Type: application/json' \
  -d '{
  "attributes": [
    {
      "name": "addressCountry",
      "value": "BE"
    },
    {
      "name": "lastName",
      "value": "Smith"
    },
    {
      "name": "telephoneNumber",
      "value": "+3267675674"
    },
    {
      "name": "contactId",
      "value": "123456"
    },
    {
      "name": "sex",
      "value": "wrongsex"
    },
    {
      "name": "source",
      "value": "myWebsite"
    },
    {
      "name": "birthDate",
      "value": "21/02/1961"
    },
    {
      "name": "firstName",
      "value": "John"
    },
    {
      "name": "addressPostalCode",
      "value": "75009"
    },
    {
      "name": "emailAddress",
      "value": "john.smith@actito.com"
    },
    {
      "name": "companyId",
      "value": "1"
    },
    {
      "name": "motherLanguage",
      "value": "FR"
    },
    {
      "name": "gsmNumber",
      "value": "+3242343214"
    }
  ],
  "subscriptions": [
    {
      "name": "optinEmailNL",
      "subscribe": true
    },
    {
      "name": "optinEmailPromo",
      "subscribe": true
    },
    {
      "name": "optinSMS",
      "subscribe": true
    },
    {
      "name": "cinemaPreference",
      "subscribe": true
    },
    {
      "name": "sciencePreference",
      "subscribe": true
    },
    {
      "name": "optinEmailPartners",
      "subscribe": false
    },
    {
      "name": "artPreference",
      "subscribe": false
    },
    {
      "name": "newsPreference",
      "subscribe": false
    }
  ]
}'

Resulting response:

{
  "message": "Bad request. Error with status 400: errors are ValidationErrors{validationErrors=[ValidationErrorImpl{errorCode='InvalidValue', description='Invalid value for field sex: error is BadRepresentationForSex', path='sex', idPath='null', id='null', parameters={error=BadRepresentationForSex, param1=WRONGSEX}}, ValidationErrorImpl{errorCode='InvalidValue', description='Invalid value for field sex: error is BadRepresentationForSex', path='sex', idPath='null', id='null', parameters={error=BadRepresentationForSex, param1=WRONGSEX}}]} in path: //entity/integrationframeworksandbox/table/Contacts/profile",
  "status": "400 : Bad Request"
}

When using this route, ACTITO will check the existence of a profile by checking all the unique attributes (unicity is mentioned in the profile table structure, see above).

If you specify allowUpdate=true then the found profile will be updated. But if you pass allowUpdate=false then the API response will be a 400 BAD REQUEST http response with a body like:

{
  "message": "Bad request. Error with status 400: errors are ValidationErrors{validationErrors=[ValidationErrorImpl{errorCode='DuplicateValue', description='Invalid request', path='null', idPath='null', id='null', parameters={}}]} in path: //entity/integrationframeworksandbox/table/Contacts/profile/",
  "status": "400 : Bad Request"
}

With a correct request, you'll receive a 200 OK http response with following json body:

{
  "profileId": 123456
}

The response object contains a profileId attribute that is the technical unique id of the created/updated profile.

You can test creating profiles with the following request test maker:

PERFECT !

You have completed the Quick start guide, and you now know the basis to operate entities, profile tables and profile creations.

To dig in more complex operations on those concepts, check the other use-cases or make a tour on our ENTITY and PROFILES APIs.

Introduction​

Step by step​

Step 0. Get an authorization token​

Step 1. Get all entities​

Step 2. Get all profile table names for an entity​

Step 3. Get the structure of a profile table​

Step 4. Create a new profile​