Skip to main content
All CollectionsConnectors
Ingestion API Guide
Ingestion API Guide
Akooda avatar
Written by Akooda
Updated over a year ago

This article provides instructions for working with Akooda ingestion API. This API endpoint group is used to push data from external systems in order to keep the entities of the platform in sync (such as CRM for Organizations, HRIS for People, and Product Analytics for Interactions). This is especially useful in the case of non-native connectors or even ad-hoc data updates.

Before We Begin

If you wish to implement the integration on your end, and not with the help of the Akooda customer solutions team, make sure to grab your account’s private API key and tenant ID.

Base URL

The base URL of the Akooda API is:

https://dev.akooda.co/

Authentication

All requests must include two headers for authentication x-akooda-tenant-id and x-akooda-authorization with the values mentioned above. If the ID does not match the key, the API will return a 403 status code. In case the tenant ID does not exist, it will return a 404 status code.

Validation

Akooda validates the supplied entities and returns a 400 status code if any of the entities fail validation with details of the error. If some entities pass validation and others fail, we will ingest the ones that pass validation and will return 204 status code.

Each request ingests a batch of entities into Akooda. We accept up to 1000 entities and 1MB uncompressed per request. Entities are represented as array of objects in the request body, which only supports properly formatted Content-Type application/json.

  • Each attribute of type array has up to 255 elements

  • Each attribute of type object has up to 255 keys with a max depth of 3

  • Each attribute of type string has a max length of 100,000 chars

Rate Limiting

The system will return a 429 status code when the rate limit is exceeded.

NOTE: For more information on Akooda’s custom integration services or requests for higher rate limiting, reach out to your Account Manager or to our support team.

Integrating via the API

Organizations API

The Organizations API can be used to sync CRMs such as Hubspot or Salesforce with Akooda's Organizations entities - including enrichment attributes populated throughout the platform. You may also use it ad-hoc to update data from JSON (or spreadsheets converted to a JSON) with an API client such as Postman.

NOTE: In case you need guidance with setting up the authentication method to your CRMs and attaining the field names relevant for the mapping, scroll down to "System Configurations" section.

Request Endpoints

POST /organizations PUT /organizations

This RESTful API provides two interaction patterns via separate HTTP verbs, POST and PUT, however, the structure of the request and the response are the same. The POST action will push organizations to your account, regardless if they were detected automatically by the system (upsert), while the PUT will only push data for pre-existing entities (update).

Request Format

Each request ingests a batch of organizations into Akooda. We accept up to 1000 entities and 1MB uncompressed per request. Organizations are the request body, which only supports properly formatted Content-Type application/json.

Entity Structure

Below are the expected values for an organization entity, that may make the Akooda platform more insightful and can be trickled throughout the platform based on your account configuration:

Attribute

Type

Example

domain (required)

String, domain

“akooda.co”

isEnabled (defaults to true)

Boolean

false

properties.closedAt

Timestamp, ISO8601

"2022-06-08T12:55:24.602Z"

properties.modifiedAt

Timestamp, ISO8601

"2022-06-08T12:55:24.602Z"

properties.renewedAt

Timestamp, ISO8601

"2022-06-08T12:55:24.602Z"

properties.assignedAt

Timestamp, ISO8601

"2022-06-08T12:55:24.602Z"

properties.description

String

“Akooda is on a mission to help employees and managers understand and navigate the digital, hybrid, and remote work world. We aspire to bring back the magic of a few people in a garage to growing companies by utilizing the latest developments in AI and …”

properties.location

String

“Cambridge, United States”

properties.stage

String, Enum (Customer, Lead, Prospect, Partner - see "stage" format)

“Customer”

properties.segments

Array of Strings, <50chars each

[“Technology”]

properties.displayName

String, <50chars

“Akooda”

properties.owners

Object, ey-value whereas key is String of email and value is a String of role Enum (Account Manager, Product Manager, CSM - see "role" format)

{

“[email protected]”: “Account Manager”

}

properties.nicknames

Array of Strings, <50chars each

[“Akooda”, “8801334”]

properties.linkedinUrl

String, URL

“https://www.linkedin.com/company/akooda”

properties.websiteUrl

String, URL

“https://akooda.co”

properties.twitterUrl

String, URL

“https://twitter.com/getakooda”

properties.phone

String, <50chars

“720-343-1234”

properties.objectId

String, <50chars

“8801334”

properties.objectType

String, Enum (Company, Deal, Account - see "objectType" format)

“Company”

properties.objectSource

String, Enum (Hubspot, Salesforce - see "objectSource" format)

“Hubspot”

properties.objectUrl

String, URL

“https://app.hubspot.com/contacts/8801334/company/5226452075”

properties.risk
​

String, Enum (see "risk" format)

MEDIUM

properties.size
​

String, Enum (see "size" format)

LARGE

Enum Types

For organizations, the are some pre-built enums that must be used to allow the system to better understand the ingested data and handle it accordingly. Enums are case-insensitive and will be mapped to their uppercase form (blank space will also be mapped to underscores "_").

stage:

  • "SUBSCRIBER"

  • "LEAD"

  • "AWARE"

  • "OPPORTUNITY"

  • "PIPELINE"

  • "CUSTOMER"

  • "CLOSED_WON"

  • "EVANGELIST"

  • "RENEWAL"

  • "CLOSED_LOST"

  • "CHURN"

role:

  • "ACCOUNT MANAGER"

  • "CUSTOMER SUCCESS MANAGER"

  • "PRODUCT MANAGER"

objectType:

  • "COMPANY"

  • "DEAL"

  • "ACCOUNT"

  • "OPPORTUNITY"

objectSource:

  • "HUBSPOT"

  • "SALESFORCE"

  • "PIPEDRIVE"

risk:

  • "LOW"

  • "MEDIUM"

  • "HIGH"

risk:

  • "SMALL"

  • "MEDIUM"

  • "LARGE"

NOTE: If you are missing an option that's more representative of your use-case, please share with the team and we'll work together to add it to the collections above.

Request Example

curl --location --request POST 'https://dev.akooda.co/organizations' \ --header 'x-akooda-tenant-id: ACCOUNT_ID \ --header 'x-akooda-authorization: ACCOUNT_KEY' \ --header 'Content-Type: application/json' \ --data-raw '[{   "domain": "hubspot.com",   "isEnabled": true,   "properties": {       "closedAt": null,       "modifiedAt": "2022-05-14T02:50:03.614Z",       "renewedAt": null,       "location": "25 First Street, Cambridge, United States",       "stage": null,       "segments": ["COMPUTER_SOFTWARE"],       "displayName": "HubSpot, Inc.",       "owners": {           "[email protected]": "Account Owner"       },       "nicknames": [],       "objectId": "4802619497",       "objectType": "company",       "objectSource": "hubspot"   } }, {   "domain": "akooda.co",   "isEnabled": false,   "properties": {       "closedAt": null,       "modifiedAt": "2022-06-08T12:55:24.602Z",       "renewedAt": null,       "location": "Cambridge, United States",       "stage": null,       "segments": [],       "displayName": "Akooda",       "owners": {           "[email protected]": "Account Owner"       },       "nicknames": [],       "object”: {“id”: "5226452075",       "objectType": "company",       "objectSource": "hubspot"   } } ] '

System Set-up

Hubspot

To sync Akooda with your Hubspot account, it is recommended to create a daily scheduled service by following these steps:

  1. Log into Hubspot using a System Admin user

  2. Go to the Private Apps page under “Integrations” in the Account Settings section and create a private app with the following scopes

    • crm.lists.read

    • crm.objects.contacts.read

    • crm.schemas.contacts.read

    • crm.objects.companies.read

    • crm.objects.deals.read

    • crm.schemas.companies.read

    • crm.schemas.deals.read

    • crm.objects.owners.read

    • crm.objects.quotes.read

    • crm.schemas.quotes.read

    • crm.objects.line_items.read

    • crm.schemas.line_items.read

  3. On the Access token card, click Show token to reveal your access token. Click Copy to copy the token

  4. Use a client library such as node-hubspot to get the properties for Company and Owner objects - you can also do this manually via the UI

  5. Set up a cron jobthat:

    1. Uses a client library such as hubspot-api-nodejs to:

      • Authenticate connection with the token above

      • Get all the Companies and Owners with the field names required for the mapping process

    2. Maps the response of the queries to the supported Organization attributes mentioned above

    3. Pushes it to Akooda via the POST/PUT endpoint

Akooda also temporarily offers a service in which it sets and creates the crone job on your behalf. If you wish to take this path, contact your your account owner, or [email protected] with the token generated above.

Salesforce

To sync Akooda with your Salesforce account, it is recommended to connect the SalesForce app. Alternatively, you can create a daily scheduled service by following these steps:

  1. Log into Salesforce using a System Admin user

  2. Set up a dedicated Connected Appwith the following configuration:

    • Refresh Token Policy: Refresh token is valid until revoked (or similar)

    • IP Relaxation: Relax IP restrictions (or similar)

    • Permitted Users: All users may self-authorize

    • Application Permissions: Access unique user identifiers, Access content resources, and Perform requests at any time

  3. Go to the “view” page of the abovementioned app from the “App Manager” Page to grab the “Consumer Key” and “Consumer Secret”

  4. Grab your Salesforce workspace “Login Url” (similar to “https://[YOUR_ACCOUNT].salesforce.com”)

  5. Grab the “email” and “password” for the user that will be used to establish an authentication in the integration service

  6. Use a client library such as jsforce to describe the field names for User and Account objects (assuming you are not using custom objects) - you can also do this manually via the UI

  7. Set up a cron job that

    1. Uses a client library such as jsforceto

      • Authenticate connection with the credentials above

      • Query the Accounts and Users with the field names required for the mapping process

    2. Maps the response of the queries to the supported Organization attributes mentioned above

    3. Pushes it to Akooda via the POST/PUT endpoint

Pipedrive

  1. Log into Pipedrive using a System Admin user

  2. Go to "Company settings > Personal preferences > API" to grab your key

  3. Use a client library such as client-nodejs to get fields of Deal and Organization objects (assuming you are not using custom objects)

  4. Set up a cron job that

    1. Uses a client library such as client-nodejsto

      • Authenticate connection with the credentials above

      • Get the Deals with the field names required for the mapping process - they will be enriched with the User (for the owners attribute), Person (for the domain attribute), and Organization fields (for other attributes)

    2. Maps the response of the queries to the supported Organization attributes mentioned above

    3. Pushes it to Akooda via the POST/PUT endpoint

Next Up

Once you’ve got the integration set up, make sure the data is up to date in the platform according to the update cadence of your service. Each data push should not take more than a few minutes to propagate.

If you run into any problems, we’re here to help. Reach out to [email protected] to get assistance for your organization.

Any Feedback?

Was this page helpful? Provide feedback on this article and ways we can improve to [email protected].

Related Articles
People Management
Did this answer your question?