NAV
shell

Introduction

The Traitly (formerly Aibl) API is a RESTful web service. You can use our API to access Traitly endpoints, which allow you to create and update records in an intuitive way.

Currently, we offer you the ability to make Curl requests, which is language-agnostic. In future, we will offer client bindings for popular languages.

Authentication

Authentication information must be passed with all API requests. A bearer token is passed as part of the request header. You must be registered and logged in to view your API credentials. You will find your token at our API credentials portal.

# With shell, you can just pass the correct header with each request
curl https://api.aibl.io/api/v1/<end-point>"
  -H "Authorization: Token <insert-token-here>"
  -H "Content-Type: application/json"

Events

Get Events

curl "https://api.aibl.io/api/v1/event"
    -H "Content-Type: application/json"
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "customer_id": "1",
            "name": "Logged in",
            "created_at": "1493933699",
            "success": 1
        },
        {
            "customer_id": "1",
            "name": "Logged in",
            "created_at": "1494020099",
            "success": 1
        }
    ],
    "metadata": {},
    "retrieved": "1500019594",
    "object": "event"
}

This endpoint retrieves all events.

HTTP Request

GET https://api.aibl.io/api/v1/event

Query Parameters

Parameter Description
customer_id If specified, the result will only include events for the customer ID specified.
name If specified, the result set only include events with the name specified.
success If set to 1, the result will only include those events that have been successful

Create an event

curl "https://api.aibl.io/api/v1/event"
    --request POST
    --data '{"name": "Added User", "customer_id": "4", 
            "success": 1, "created_at": "150002040"}'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "4",
        "name": "Added User",
        "created_at": "1500020403",
        "success": 1
    },
    "metadata": {},
    "created_at": "1500060019",
    "object": "event"
}

HTTP Request

POST https://api.aibl.io/api/v1/event

Post Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
name Name of the event being created.
success If set to 1, the customer successfully completed the action. 0 means that the customer failed to successfully complete the action.
created_at Time at which the event occurred. Measured in seconds since the Unix epoch. Defaults to the current Unix timestamp.

Stats

Get Stats

curl "https://api.aibl.io/api/v1/stat"
    -H "Content-Type: application/json"
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "value": "5465.09",
            "customer_id": "4",
            "name": "Weekly Sales",
            "created_at": "1499979213"
        }
    ],
    "metadata": {},
    "retrieved": "1500020806",
    "object": "statistic"
}

This endpoint retrieves all stats matching specified criteria.

HTTP Request

GET https://api.aibl.io/api/v1/stat

Query Parameters

Parameter Description
customer_id If specified, the result will only include events for the customer ID specified.
name If specified, the result set only include events with the name specified.

Create a stat

curl "https://api.aibl.io/api/v1/stat"
    --request POST
    --data '{"value": 9999.99, "customer_id": "4", 
            "name": "Weekly Sales"}'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "value": "9999.99",
        "customer_id": "4",
        "name": "Weekly Sales",
        "created_at": "1500020403"
    },
    "metadata": {},
    "created_at": "1500021086",
    "object": "statistic"
}

HTTP Request

POST https://api.aibl.io/api/v1/stat

Post Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
name Name of the stat being created.
value The value associated with the stat being created, e.g., a weekly sales amount.
created_at Time at which the stat was created. Measured in seconds since the Unix epoch. Defaults to the current Unix timestamp.

Customers

Get Customers

curl "https://api.aibl.io/api/v1/customer"
    -H "Content-Type: application/json"
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "customer_id": "1",
            "name": "Customer A",
            "monthly_payment_amount": 69,
            "engagement": 0.46,
            "location": "Dublin",
            "created_at": "1498740337",
            "last_updated_at": "1500022145",
            "plan": "Plan A",
            "email": "support@company.com",
            "phone_number": "+353 (1) 12345678",
            "is_paying": 1
        },
        {
            "customer_id": "2",
            "name": "Customer B",
            "monthly_payment_amount": 299,
            "engagement": 0.98,
            "location": "Mountain View",
            "created_at": "1498740337",
            "last_updated_at": "1498740337",
            "plan": "Plan B",
            "email": null,
            "phone_number": null,
            "is_paying": 1
        }
    ],
    "metadata": {},
    "retrieved": "1500020806",
    "object": "customer"
}

This endpoint retrieves all companies matching specified criteria.

HTTP Request

GET https://api.aibl.io/api/v1/customer

Query Parameters

Parameter Description
customer_id If specified, the result set will only include customer records for the customer ID specified.
name If specified, the result set will only include customer records with the name specified.
plan If specified, the result set will only include customer records on the plan name specified.

Create a customer

curl "https://api.aibl.io/api/v1/customer"
    --request POST
    --data '{"customer_id": "15", "name": "Customer C",
            "monthly_payment_amount": 99,
            "location": "New York", "plan": "Atom",
            "email": "support@company.com"
            }'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "15",
        "name": "Customer C",
        "monthly_payment_amount": 99,
        "engagement": 0,
        "location": "New York",
        "created_at": "1500023328",
        "plan": "Atom",
        "email": "support@company.com"
    },
    "metadata": {},
    "created_at": "1500023328",
    "object": "customer"
}

HTTP Request

POST https://api.aibl.io/api/v1/customer

Post Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
name Name of the customer being created.
monthly_payment_amount The monthly amount being paid.
location The location of the customer being created.
plan The name of the plan the customer is on.
email An email address associated with the customer being created.
phone_number A phone number associated with the customer being created.
is_paying Specifies whether the customer is a paying customer.

Starts

Get starts

curl "https://api.aibl.io/api/v1/start"
    -H "Content-Type: application/json"
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": [
        {
            "customer_id": "1",
            "created_at": "1499865313",
            "goal": "Trial",
            "plan": "Plan A"
        },
        {
            "customer_id": "2",
            "created_at": "1499867978",
            "goal": "Non-Churn",
            "plan": "Plan A"
        }
    ],
    "metadata": {},
    "retrieved": "1500020806",
    "object": "start"
}

This endpoint retrieves all starts matching specified criteria. A start record associates a customer with a goal.

HTTP Request

GET https://api.aibl.io/api/v1/start

Query Parameters

Parameter Description
customer_id If specified, the result set will only include start records for the customer ID specified.
goal If specified, the result set will only include start records matching the goal name specified.
plan If specified, the result set will only include start records on the plan name specified.

Create a start

curl "https://api.aibl.io/api/v1/start"
    --request POST
    --data '{"customer_id": "11", "goal": "Trial",
            "plan": "Atom"
            }'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "11",
        "created_at": "1500025700",
        "goal": "Trial",
        "plan": "Atom"
    },
    "metadata": {},
    "created_at": "1500025971",
    "object": "start"
}

HTTP Request

POST https://api.aibl.io/api/v1/start

Post Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
goal Name of the goal being started.
plan Name of the plan associated with the goal being started.
created_at Time at which the goal starts for the customer. Measured in seconds since the Unix epoch. Defaults to the current Unix timestamp.

Outcomes

Get outcomes

curl "https://api.aibl.io/api/v1/outcome"
    -H "Content-Type: application/json"
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "11",
        "goal": "Trial",
        "created_at": "1500025700",
        "success": 1,
        "plan": "Atom"
    },
    "metadata": {},
    "created_at": "1500026692",
    "object": "outcome"
}

This endpoint retrieves all outcomes matching specified criteria.

An outcome means that a customer succeeded or failed to reach a goal, for example, conversion.

In order to create an outcome, a corresponding start must first have been created, with a matching customer_id, goal name, and plan name.

HTTP Request

GET https://api.aibl.io/api/v1/outcome

Query Parameters

Parameter Description
customer_id If specified, the result set will only include outcome records for the customer ID specified.
goal If specified, the result set will only include outcome records matching the goal name specified.
plan If specified, the result set will only include outcome records on the name name specified.
success If specified, the result set will only include matching outcome records.

Create an outcome

curl "https://api.aibl.io/api/v1/outcome"
    --request POST
    --data '{"customer_id": "15", "goal": "Test Goal",
            "plan": "Atom", "success": 1,
            }'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "15",
        "goal": "Test Goal",
        "created_at": "1500026865",
        "success": 1,
        "plan": "Atom"
    },
    "metadata": {},
    "created_at": "1500027574",
    "object": "outcome"
}

HTTP Request

POST https://api.aibl.io/api/v1/outcome

Post Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
goal Name of the goal for which an outcome has occurred.
plan Name of the plan associated with the goal for which an outcome has occurred.
created_at Time at which the goal ends for the customer. Measured in seconds since the Unix epoch. Defaults to the current Unix timestamp.
success Whether a customer successfully achieved a goal, e.g., if a customer converts for a goal ‘Conversion’, then success should be 1.

Update an outcome

curl "https://api.aibl.io/api/v1/outcome"
    --request PUT
    --data '{"customer_id": "15", "goal": "Test Goal",
            "plan": "Atom", "success": 1,
            }'
    -H "Authorization: Token <insert-token-here>"

The above command returns JSON structured like this:

{
    "data": {
        "customer_id": "15",
        "goal": "Test Goal",
        "created_at": "1500026865",
        "success": 1,
        "plan": "Atom"
    },
    "metadata": {},
    "created_at": "1500027574",
    "object": "outcome"
}

HTTP Request

PUT https://api.aibl.io/api/v1/outcome

Put Parameters

Parameter Description
customer_id This is your internal representation of a customer ID.
goal Name of the goal for which an outcome has occurred.
plan Name of the plan associated with the goal for which an outcome has occurred.
created_at Time at which the goal ends for the customer. Measured in seconds since the Unix epoch. Defaults to the current Unix timestamp.
success Whether a customer successfully achieved a goal, e.g., if a customer converts for a goal 'Conversion’, then success should be 1.

Errors

API error codes

The following error codes may be returned as part of an Aibl API response:

Code Meaning
api_connection_error Failed to connect to the Aibl API
api_error General API error, e.g., temporary problem with the Aibl platform
api_authentication_error Failed to correctly authenticate the client API token
api_invalid_request_error Invalid API request parameters

The Aibl API uses the following HTTP status codes:

Status Meaning
200 Everything worked as anticipated
400 Bad Request
401 Unauthorized – Your API token is invalid
403 Forbidden – The resource requested is hidden
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many resources. Please increase the time between requests
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.