Managing Contacts with the REST API

The Akita REST API allows you to create and update contacts using data from your internal systems.For instance, you may:

Add a Contact to Akita when a user signs up for your service;
Update Contact properties in Akita when they change in your system;
Update KPIs for all of your Contacts in Akita in a nightly job.

Contacts are individual users of your application or people who otherwise belong to an Account. You can find our full API documentation here.

Creating and Updating Contacts

To get started, send the following call:

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
        "internal_id": "abc",
        "internal_account_id": "1",
        "first_name": "John",
        "last_name": "Doe"
     }' \
    'https://api.akitaapp.com/v1/contacts'

In this request, internal_id is the identifier you use at your company to identify an individual user. This might be an ID field stored in your 'users' table. The internal_account_id is the identifier that you use at your company to identify the customer the user belongs to. The only required fields are internal_id and internal_account_id but we recommend you include first_name and last_name with every request otherwise your new Contact will not have a name!

If a Contact for the provided internal_id already exists, that Contact will be updated. If it does not yet exist, it will be created.

You will receive a response that looks like this (we've omitted some of the properties for now):

{
  "data": {
    "created_at": "2021-04-04 11:12:11",
    "id": 2114,
    "internal_id": "abc",
    "internal_account_id": "1",
    "first_name": "John",
    "last_name": "Doe",
    "updated_at": "2021-04-04 11:12:11"
  }
}

We have returned the newly create Akita Contact. This includes your own internal_id and internal_account_id as well as an id that is assigned by Akita.

Updating Contacts

You can use the exact same request to update a Contact. Always include your internal_id and internal_account_id as well as additional attributes you would like to update. You can find a list of Contact attributes here.

Updating Contact Information

It can be useful to store contact information with Contacts. With Akita, you can store urls, telephone numbers, and shared email addresses. You can submit this information via the REST API.

To include contact information, use the following request:

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "internal_id": "a",
         "internal_account_id": "1",
          "name": "John Doe",
         "emails": [
             {
                 "label": "Email",
                 "value": "john.doe@my-new-customer.com"
             }
         ],
         "phones": [
             {
                 "label": "Mobile",
                 "value": "+1 404 555 1212"
             }
         ],
         "urls": [
             {
                 "label": "Blog",
                 "value": "https://jd.my-new-customer.com"
             }
         ]
     }' \
    'https://api.akitaapp.com/v1/contacts'

These values will be displayed in the sidebar on the right side of each Contact screen.

Assigning Tags

You can apply manually created tags using the tag's "Api ID" which you can find in the app in Settings / Manual Tags.

To assign tags, include the tags attribute--an array of valid tag ids--with your request:

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "internal_id": "a",
         "internal_account_id": "1",
         "name": "John Doe",
         "tags": [
             345 // A valid Api ID for a Contact Tag
         ]
     }' \
    'https://api.akitaapp.com/v1/contacts'