API Documentation

The Attributable APIs allow authorized users to post and retrieve data asynchronously for use in their own client applications. The APIs are a continual work in progress, so as new versions of the APIs become available, old versions will be retired (after a suitable transition period). If you notice that your API calls have stopped returning data, please check the returned status messages to ensure that your API URL hasn't become deprecated.

In general, sub-incremental versions are forwards-compatible (e.g. 1.2 will accept the same parameters as 1.1), but incremental versions will not (e.g. 2.0 will require different configuration than 1.0).

Accessing the APIs requires a private, unique, application-specific access key. Please keep this key secure (e.g. do not add it to browser-viewable code).

SDKs

Looking for a shortcut to working directly with the Attributable APIs? Try the Attributable SDKs (currently available for PHP users only).

iFrames

In addition to the Attributable API, users can leverage the customizable Attributable iFrames to display real-time Attributable events on an external website.




Capture API

POST

The Capture API allows you to post data associated with an event, generally (not not strictly necessarily) user-initiated. Typical events include a user updating his/her profile, an administrator approving a registration, or even a given IP address hitting an unauthorized interface.

The user (whether identified by a user_id or other attributes like IP, email or phone number) is called the "author" of the event. The more information you can provide on the author, the more useful Attributable becomes as it analyzes patterns and discovers anomalous behavior.

URL Structure

https://api.attributables.com/1-0/ API KEY /capture

Input parameters are expressed in well-formed JSON, e.g.

{
  "event" : "John Smith logged in",
  "occurred_on" : "2017-01-01 12:00:00",
  "author" : {
    "user_id" : "123",
    "ip" : "127.0.0.1"
  }
  "tags" : {
    "company_id" : "456",
    "transaction_id" : "ABC"
  }
}

Input Parameters

Req? Field Data type Maxlength Format Restricted to Comments
Y event Alphanumeric 255
Y occurred_on DateTime 19 YYYY-MM-DD HH:MM:SS Please rationalize timezone prior to sending
author {
user_id Alphanumeric 25 Unique identifier
first_name Alphanumeric 25
last_name Alphanumeric 25
ip Alphanumeric 45
latitude Float 10,6
longitude Float 10,6
user_agent Alphanumeric 255
email Alphanumeric 255 Unique identifier
phone Alphanumeric 18 COUNTRY-AREA-SUBSCRIBER E.164 standard (numbers and hyphens only) Unique identifier
is_blacklisted Boolean 1 1 or 0
is_whitelisted Boolean 1 1 or 0
is_greylisted Boolean 1 1 or 0
}
tags {
(key) Alphanumeric 40 (value)
}
is_error Boolean 1 1 or 0
is_resolved Boolean 1 1 or 0
execution_time_in_seconds Integer 3
comments Alphanumeric 1000

Note that user_id, email and phone are considered unique identifiers; they cannot be shared by more than one author. This enables Attributable to associate events which are initially not attributed to a known user with events which are associated with a subsequently known user. For example, a single user may do certain things in your client application that require an email address or phone number but not registration; upon registering, you'll want that pre-registration data to become associated with the newly registered user_id.

Response

If the posted data is successfully accepted by the API, the header will show 200 (success) and the response will contain an alphanumeric event_id. Warning codes may also be provided. Warning codes are listed on the Attributable website and while additional warning codes may be added in the future, existing warning codes will not change.

{
  "success" : {
    "event_id" : "123AbC"
  },
  "warnings" : {
    "2000" : "Approaching maximum number of API interactions"
  }
}

If the interaction with the API is unsuccessful, the header will show 400 (bad request) and one or more error codes will be returned. Error codes are listed on the Attributable website and while additional error codes may be added in the future, existing error codes will not change.

{
  "errors" : {
    "1000" : "Unable to authenticate",
    "1010" : "Unable to identify user"
  }
}

Measure API

POST

The Measure API is used to post internal metrics for analysis and visualization purposes. Note that measurements are timestamped so that you can analyze trending patterns.

URL Structure

https://api.attributables.com/1-0/ API KEY /measure

Input parameters are expressed in well-formed JSON, e.g.

{
  "metric" : "Number of registrations",
  "value" : "+1",
  "occurred_on" : "2017-01-01 12:00:00"
}

Input Parameters

Req? Field Data type Maxlength Format Restricted to Comments
Y metric Alphanumeric 100
Y value Numeric 10 Numbers optionally preceeded by a + or - A + prefix increments by the amount specified, a - prefix decrements by the amount specified, and a = prefix (or no prefix) sets the value to the amount specified
Y occurred_on DateTime 19 YYYY-MM-DD HH:MM:SS Please rationalize timezone prior to sending

Response

If the posted data is successfully accepted by the API, the header will show 200 (success) and the response will contain an alphanumeric measurement_id. Warning codes may also be provided. Warning codes are listed on the Attributable website and while additional warning codes may be added in the future, existing warning codes will not change.

{
  "success" : {
    "measurement_id" : "123AbC"
  },
  "warnings" : {
    "2000" : "Approaching maximum number of API interactions"
  }
}

If the interaction with the API is unsuccessful, the header will show 400 (bad request) and one or more error codes will be returned. Error codes are listed on the Attributable website and while additional error codes may be added in the future, existing error codes will not change.

{
  "errors" : {
    "1000" : "Unable to authenticate",
    "1010" : "Unable to identify user"
  }
}

Events API

POST

The Events API can be used to extract filtered event data for use in dashboards or to perform complex local analysis. To ensure high performance, output of the Events API is paginated.

https://api.attributables.com/1-0/ API KEY /events

Input parameters are expressed in well-formed JSON, e.g.

{
  "start_date" : "2017-01-01 12:00:00",
  "end_date" : "2017-02-01 12:00:00",
  "author" : {
    "user_id" : "123",
    "also_search_tags" : 1
  }
}

Input Parameters

Field Data Type Format Restricted to Comments
event_id Alphanumeric Must be a previously returned ID
author {
author_id Alphanumeric Must be a previously returned ID
user_id Alphanumeric
ip Alphanumeric
email Alphanumeric
phone Alphanumeric COUNTRY-AREA-SUBSCRIBER E.164 standard (numbers and hyphens only)
is_blacklisted Boolean 1 or 0
is_greylisted Boolean 1 or 0
is_whitelisted Boolean 1 or 0
also_search_tags Boolean 1 or 0 Will search tags for user_id to provide a complete record of all events related to this author
}
tags {
(key) Alphanumeric (value)
}
start_date Datetime YYYY-MM-DD HH:MM:SS
end_date Datetime YYYY-MM-DD HH:MM:SS
is_alert Boolean 1 or 0
is_resolved Boolean 1 or 0
page Integer

Response

If the URL is successfully accepted by the API, the header will show 200 (success) and the response will contain a JSON result set.

{
  "number_of_results" : 1,
  "number_of_results_on_this_page" : 1,
  "page" : 1,
  "events" : {
    "abc123" : {
      "event" : "John Smith registered",
      "occurred_on" : "2017-01-01 12:00:00",
      "author" : {
        "author_id" : "123abc",
        "user_id" : "456def",
        "first_name" : "John",
        "last_name" : "Smith",
        "ip" : "127.0.0.2",
        "latitude" : "43.7",
        "longitude" : "-79.4",
        "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36",
        "email" : "john@smith.com",
        "phone" : "555-555-5555",
        "is_blacklisted" : 0,
        "is_greylisted" : 0,
        "is_whitelisted" : 1
      },
      "is_error" : 0,
      "is_resolved" : 0,
      "execution_time_in_seconds" : 0,
      "comments" : ""
    }
}

If the interaction with the API is unsuccessful, the header will show 400 (bad request) and one or more error codes will be returned.

{
  "errors" : {
    "1000" : "Unable to authenticate",
    "1010" : "Unable to identify user"
  }
}

User API

POST

The User API retrieves one or many authors from the database, and is intended primarily for scertaining the status of a particular user so that the calling application can respond appropriately. For instance, if an IP is queried through the User API, it might find that the same IP was used in a previous event to trip a honeypot and has therefore been blacklisted or greylisted. Likewise, the User API could help ascertain that suspicious behavior associating with an IP is acceptable because the IP has been previously linked with a known and trusted user of the calling application.

URL Structure

https://api.attributables.com/1-0/ API KEY /user

Input parameters are expressed in well-formed JSON, e.g.

{
  "ip" : "127.0.0.0"
}

Input Parameters

Field Data Type Format Restricted to Comments
author_id Alphanumeric Must be a previously returned ID
user_id Alphanumeric
ip Alphanumeric
email Alphanumeric
phone Alphanumeric COUNTRY-AREA-SUBSCRIBER E.164 standard (numbers and hyphens only)
is_blacklisted Boolean 1 or 0
is_greylisted Boolean 1 or 0
is_whitelisted Boolean 1 or 0
page Integer

Response

If the URL is successfully accepted by the API, the header will show 200 (success) and the response will contain a JSON result set.

{
  "number_of_results" : 1,
  "number_of_results_on_this_page" : 1,
  "page" : 1,
  "authors" : {
    "123abc" : {
      "user_id" : "456def",
      "first_name" : "John",
      "last_name" : "Smith",
      "email" : "john@smith.com",
      "phone" : "555-555-5555",
      "is_blacklisted" : 0,
      "is_greylisted" : 0,
      "is_whitelisted" : 1
      "ips" : {
        [0] : 192.168.0.1
      }
    }
}

If the interaction with the API is unsuccessful, the header will show 400 (bad request) and one or more error codes will be returned.

{
  "errors" : {
    "1000" : "Unable to authenticate",
    "1010" : "Unable to identify user"
  }
}

Error Codes

Code Error
1000 Unable to authenticate
1010 Unable to identify user
1020 Exceeded allowable number of API interactions
1030 Malformed input structure
1040 Missing required parameters
1050 Malformed input format(s)
1060 Invalid sending IP

Warning Codes

Code Warning
2000 Approaching maximum number of API interactions