Managing Accounts with the REST API

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

Add an Account to Akita when a new business signs up for your service;
Update Account properties in Akita when they change in your system;
Update KPIs for all of your Accounts in Akita in a nightly job.

Accounts are your Customers and are organizations (as opposed to individual users which we call Contacts). You can find our full API documentation here.

Creating and Updating Accounts

To get started, send the following call:

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "internal_id": "1",
         "name": "My New Customer"
     }' \
    'https://api.akitaapp.com/v1/accounts'

In this request, internal_id is the identifier you use at your company to identify a customer organization. This might be an ID field stored in your 'customers' table. The only required field is internal_id but we recommend you include name with every request otherwise your new Account will not have a name!

NOTE: By default, the "is_tracked" attribute will be set to TRUE when an Account is created via the API. If you are entering churned or prospective Accounts, set is_tracked to FALSE.

If an Account for the provided internal_id already exists, that Account 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": 1114,
    "internal_id": "1",
    "name": "My New Customer",
    "updated_at": "2021-04-04 11:12:11"
  }
}

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

Updating Accounts

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

Setting an Account to "Churned"

You can set an Account to "churned" two ways:

Set is_churned = TRUE; or
Set customer_end_date to a date equal to or before today's date.

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "internal_id": "1",
         "name": "My Churned Customer",
         "is_churned": true, 
         "customer_end_date": "2021-01-05"
     }' \
    'https://api.akitaapp.com/v1/accounts'

Updating Contact Information

It can be useful to store contact information with accounts. 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": "1",
         "name": "My New Customer",
         "emails": [
             {
                 "label": "Billing Email",
                 "value": "billing@my-new-customer.com"
             }
         ],
         "phones": [
             {
                 "label": "Billing",
                 "value": "+1 303 555 1212"
             }
         ],
         "urls": [
             {
                 "label": "Helpdesk",
                 "value": "https://helpdesk.my-new-customer.com"
             }
         ]
     }' \
    'https://api.akitaapp.com/v1/accounts'

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

Assigning the Customer Success Manager

You can assign each Account an Akita user to serve the role of Customer Success Manager for that Account.

PREREQUISITES:

The user must exist in Akita;
You must know email address of the Akita user; and
The user must be assigned the role of "Customer Success Manager".

Akita Account Owners and Administrators can configure this in Settings / Users.

To assign ownership, include the roles attribute with your request:

curl --request POST \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "internal_id": "1",
         "name": "My New Customer",
         "roles": [
             {
                 "role_id": 6, // CSM is always role_id 6
                 "email": "john.csm@my-company.com"
             }
         ]
     }' \
    'https://api.akitaapp.com/v1/accounts'

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": "1",
         "name": "My New Customer",
         "tags": [
             123 // A valid Api ID for an Account Tag
         ]
     }' \
    'https://api.akitaapp.com/v1/accounts'