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

  1. Get all entities in your licence
  2. Get all profile table names for an entity
  3. Get the structure of a profile table
  4. 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 a webservice user for the API authentication, ask our Support Team.

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 /entity

Make sure to provided the following headers:

  • Authorization header with BasicAuth credentials
    Check Authentication section for full details.
  • 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/ActitoWebServices/ws/v4/entity \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic QWN0aXRvSU9EZW1vL1dlYlNlcnZpY2VzX3Rlc3Q6TkJDSkQ0NERMRk5YJA=='

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.

You can test this part or any other API call on your own licence with the “request test maker” below by providing your own credentials in the desired environment. You can either generate the code corresponding to those tests in the coding language you are used to.

Send requests directly from the browser (CORS must be enabled)
$$.env
domain
Environments

Depending on the environment you choose to make your calls on, the domain and context path of the urls are different:

  • PRODUCTION: https://api.actito.com/ActitoWebServices/ws/v4
  • TEST: https://test.actito.be/ActitoWebServices/ws/v4

If you want all request test makers of this documentation to use TEST urls, please add ?domain=apitest.actito.com to any page url. For this quick start page for example.


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 /entity/integrationframeworksandbox/table/

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 /entity/1/table/

Don’t forget the trailing slash at the end of the urls!

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/ActitoWebServices/ws/v4/entity/integrationframeworksandbox/table/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic QWN0aXRvSU9EZW1vL1dlYlNlcnZpY2VzX3Rlc3Q6TkJDSkQ0NERMRk5YJA=='

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.

Send requests directly from the browser (CORS must be enabled)
$$.env
domain

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 /entity/integrationframeworksandbox/table/Contacts/

Don’t forget to include Accept and Authorization headers.

The curl command:

curl -X GET \
  https://api.actito.com/ActitoWebServices/ws/v4/entity/integrationframeworksandbox/table/Contacts/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic QWN0aXRvSU9EZW1vL1dlYlNlcnZpY2VzX3Rlc3Q6TkJDSkQ0NERMRk5YJA=='

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": []
}
Send requests directly from the browser (CORS must be enabled)
$$.env
domain

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 /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/ActitoWebServices/ws/v4/entity/integrationframeworksandbox/table/Contacts/profile/?allowUpdate=false \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic QWN0aXRvSU9EZW1vL1dlYlNlcnZpY2VzX3Rlc3Q6TkJDSkQ0NERMRk5YJA==' \
  -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:

Send requests directly from the browser (CORS must be enabled)
$$.env
domain

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 DATA APIs.