Quick Start

Introduction

This guide covers the basics you need to get started with Actito's Integration Framework. By the end, you'll be able to retrieve your entities, list the profile tables within an entity, inspect a table's structure, and create your first profile.

Steps overview:

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

Prerequisites

Read the Concepts section for background on entities and profile tables.
Make sure at least one entity and profile table exist in your licence (check with your marketer).
You'll need an API Key for authentication. If you don't have one, contact your licence supervisor or our Support Team.

Step 0. Get an authorization token

See the API Key Authentication section for full details.

Step 1. Get all entities

The first call you should make is to retrieve the entities you have access to. Since all Actito resources are scoped to an entity, this tells you what data is available to you.

GET /entities/v5/entities

Required headers:

Header	Value
`Authorization`	`Bearer <your_access_token>`
`Accept`	`application/json`

Example request:

curl -X GET \
  https://api.actito.com/entities/v5/entities \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer '

Possible responses:

Status	Meaning
`200 OK`	Success
`401 Unauthorized`	Missing or invalid credentials
`406 Not Acceptable`	Invalid `Accept` header value

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

Example response (200 OK):

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

Each entity has a numeric id, a unique technical name, and an optional comment describing its purpose. In subsequent API calls, you will always use the entity name (not the id) in the URL.

Step 2. Get all profile table names for an entity

Using the entity name retrieved in Step 1, list its available profile tables:

GET /profile-table-structure/v5/entities/**_integrationframeworksandbox_**/profile-tables

caution

Always use the entity name in the URL, not its numeric ID. Using the ID will return a 404 Not Found.

Example request:

curl -X GET \
  https://api.actito.com/profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer '

Example response (200 OK):

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

The response contains an array of objects, each with a single name property — the technical name of a profile table within the entity.

Step 3. Get the structure of a profile table

Now that you know a Contacts table exists, retrieve its full structure to understand which attributes, subscriptions, and segmentations it contains — and which fields are mandatory before creating a profile.

GET /profile-table-structure/v5/entities/**_integrationframeworksandbox_**/profile-tables/**_Contacts_**

Example request:

curl -X GET \
  https://api.actito.com/profile-table-structure/v5/entities/integrationframeworksandbox/profile-tables/Contacts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer '

Example response (200 OK):

{
  "id": 1,
  "name": "Contacts",
  "attributes": {
    "contactId": {
      "mandatory": true,
      "multiValue": false,
      "unicity": "UNIQUE_FOR_ALL_ELEMENTS",
      "modifiable": true,
      "valueType": "String",
      "possibleValues": [],
      "comment": "contact's unique and mandatory ID"
    },
    "emailAddress": {
      "mandatory": false,
      "multiValue": false,
      "unicity": "NOT_UNIQUE",
      "modifiable": true,
      "valueType": "EmailAddress",
      "possibleValues": [],
      "comment": "e-Mail address"
    },
    "firstName": { "mandatory": false, "valueType": "Name", "comment": "First name" },
    "lastName": { "mandatory": false, "valueType": "Name", "comment": "Last name" },
    "birthDate": { "mandatory": false, "valueType": "Datum", "comment": "Birth date" },
    "sex": { "mandatory": false, "valueType": "Sex", "comment": "Sex" },
    "motherLanguage": { "mandatory": false, "valueType": "Language", "comment": "Mother language" },
    "gsmNumber": { "mandatory": false, "valueType": "PhoneNumber", "comment": "Mobile number" },
    "telephoneNumber": { "mandatory": false, "valueType": "PhoneNumber", "comment": "Home phone number" },
    "addressStreet": { "mandatory": false, "valueType": "String", "comment": "Address street" },
    "addressLocality": { "mandatory": false, "valueType": "String", "comment": "Address locality" },
    "addressPostalCode": { "mandatory": false, "valueType": "String", "comment": "Address postal code" },
    "addressRegion": { "mandatory": false, "valueType": "String", "comment": "Address region" },
    "addressCountry": { "mandatory": false, "valueType": "Country", "comment": "Address country" },
    "source": { "mandatory": false, "valueType": "String", "comment": "Contact's creation source" },
    "companyId": { "mandatory": false, "valueType": "String", "comment": null },
    "shopId": { "mandatory": false, "valueType": "String", "comment": null }
  },
  "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": []
}

Note that contactId is the only mandatory attribute ("mandatory": true) and must be unique across all profiles ("unicity": "UNIQUE_FOR_ALL_ELEMENTS").

Step 4. Create a new profile

You now have everything you need to create a profile in the Contacts table.

POST /profiles/v4/entity/**_integrationframeworksandbox_**/table/**_Contacts_**/profile/?allowUpdate=false

By default, this endpoint uses a create-or-update strategy: if a profile with the same unique attribute already exists, it will be updated. To disable this and strictly create, pass ?allowUpdate=false.

Required headers:

Header	Value
`Authorization`	`Bearer <your_access_token>`
`Accept`	`application/json`
`Content-Type`	`application/json`

Example request body:

{
  "attributes": [
    { "name": "contactId", "value": "123456" },
    { "name": "firstName", "value": "John" },
    { "name": "lastName", "value": "Smith" },
    { "name": "emailAddress", "value": "john.smith@actito.com" },
    { "name": "gsmNumber", "value": "+3242343214" },
    { "name": "telephoneNumber", "value": "+3267675674" },
    { "name": "sex", "value": "M" },
    { "name": "birthDate", "value": "21/02/1961" },
    { "name": "motherLanguage", "value": "FR" },
    { "name": "source", "value": "myWebsite" },
    { "name": "addressCountry", "value": "BE" },
    { "name": "addressPostalCode", "value": "75009" },
    { "name": "companyId", "value": "1" }
  ],
  "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 }
  ]
}

Success response (200 OK):

{
  "profileId": 123456
}

The profileId is the internal technical ID of the created or updated profile.

Error handling:

If a mandatory field is missing or a value fails validation, you'll receive a 400 Bad Request with a descriptive error body. For example, passing "wrongsex" for the sex field returns:

{
  "message": "Bad request. Error with status 400: errors are ValidationErrors{validationErrors=[ValidationErrorImpl{errorCode='InvalidValue', description='Invalid value for field sex: error is BadRepresentationForSex', ...}]}",
  "status": "400 : Bad Request"
}

If allowUpdate=false and a profile with the same unique attribute already exists, you'll receive:

{
  "message": "Bad request. Error with status 400: errors are ValidationErrors{validationErrors=[ValidationErrorImpl{errorCode='DuplicateValue', ...}]}",
  "status": "400 : Bad Request"
}

You've completed the Quick Start! You now know the basics for working with entities, profile tables, and profiles in Actito.

To go further, explore the other use cases or browse the Entities API and Profiles API references.

Introduction​

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​

Introduction

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