Developers

Got questions? Need a demo? We are here to help.

Getting started

#

You can try out the Four/Four platform with a free trial account. If you're interested in becoming a Four/Four developer partner, we can convert your trial account into a sponsored account.

Full API schema information including all endpoints is available in the generated documentation.

OAuth Authentication

#

You must use OAuth2 to authenticate all your API requests to Four/Four. OAuth provides a secure way for your application to access account data without requiring sensitive information such as usernames and passwords be sent with the requests. To use OAuth authentication, you need to register your application with Four/Four by adding an API client. You also need to add some functionality to your application to implement an OAuth authorization flow.

You can use the OAuth client to authenticate access to your instance, and it can be used by other Four/Four customers to allow your service to access their Four/Four instance.

Adding an API client

You must add an API client in Four/Four to generate OAuth credentials for your application.

To add a client

  1. Sign in as an admin into your Four/Four instance. Go to the connections page , then scroll down to "OAuth Clients".
  2. Click Create Client.
  3. Complete the following fields:
    • Client name - The name of your client. This name will be visible to users when they are prompted to grant access to your application.
    • Redirect URLs - Enter the URL or URLs that Four/Four should use to redirect users after they decide whether to authorize your application to access Four/Four. The URL must be absolute, not relative, and should use HTTPS unless you are using localhost.
  4. Click Create.
  5. Upon successful creation, the client id and client secret will be displayed. Take note of these values as you'll need both to create an OAuth access token later.

  6. Save the client secret somewhere safe.

Use the client id (also known as the unique identifier) and the client secret in your application as described in this following section.

Implementing an OAuth Authorization Flow

Four/Four supports the authorization code grant flow, which produces an authorization code after the user grants your app access to their account. Your app can then exchange the authorization code for an access token to use in API requests. Refresh tokens are also issued for the authorization code grant flow.

To implement the authorization code grant flow, you need to add the following functionality to your application:

  • Step 1 - Send the user to the Four/Four authorization page
  • Step 2 - Handle the user's authorization decision
  • Step 3 - Get an access token from Four/Four
  • Step 4 - Use the access token in API calls

Step 1 - Send the user to the Four/Four authorization page

First, your application must send the user to the Four/Four authorization page. The page asks the user to authorize your application to access Four/Four as if it was them. After the user makes a choice, Four/Four sends the choice and a few other bits of information back to your application.

To send the user to the Four/Four authorization page add a link or button in your application that sends the user to the following URL:

https://fourfour.ai/oauth/authorize

The request should be GET, with the following parameters (make sure to URL-encode the parameters):

  • response_type - Required. Four/Four returns an authorization code in the response, so specify code as the response type. Example: response_type=code .
  • redirect_uri - Required. The URL that Four/Four should use to redirect users after they decide whether to authorize your application to access Four/Four. The URL must be absolute, not relative, and should use HTTPS unless you are using localhost. This URL should be one of the URLs you provided during client registration.
  • client_id - Required. The unique identifier you obtained when you registered your application with Four/Four. See the section above.
  • state - An arbitrary string included in the response from Four/Four after the user decides whether to grant access. You can use the parameter to guard against cross-site request forgery (CSRF) attacks. In a CSRF attack, the end-user is tricked into clicking a link that performs an action in a web application where the end-user is still authenticated. To guard against this kind of attack, add some value to the state parameter and validate it when it comes back.
  • scope - The scope your application requires, currently only api:read is supported.

Step 2 - Handle the user's authorization decision

Your application must handle the response from Four/Four indicating the user's decision. When the user authorizes the application, the authorization code will be found in the redirected URL parameters, for example:

{redirect_uri}?code=7xqwtlf3rrdj8uyeb1yf

The authorization code is valid only for a short time.

If the user decides to deny the application, the URL will contain an error parameter.

{redirect_uri}?error=access_denied

Use these values to control the flow of your application. If the URL contains a code parameter, get an access token from Four/Four as described in the following section. This access token is used to make API calls to Four/Four.

Step 3 - Get an access token from Four/Four

If your application received an authorization code from Four/Four in response to the user granting access, your application can call Four/Four to get an access token. To get the access token, make a POST request to the following endpoint:

https://fourfour.ai/oauth/token

Include the following required parameters in the request:

  • grant_type - Specify authorization_code as the value.
  • code - Use the authorization code you received from Four/Four after the user granted access.
  • client_id - Use the unique identifier you received when you registered your application with Four/Four.
  • client_secret - Use the secret value you received when you registered your application with Four/Four.
  • redirect_uri - The URL of the resource that Four/Four should send the access token. It again should be one of the URLs you specified during client registration.

The request must be over HTTPS and the parameters must be URL-encoded.

curl https://fourfour.ai/oauth/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={your_client_secret}&redirect_uri={your_redirect_uri}' \
    -X POST

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo...",
    "refresh_token": "x4AoIVTmaoZmpl25ZX6vTPL2f0aZXHbn...",
    "token_type": "Bearer",
    "expires_in": 86400
}

Step 4 - Use the access token in API calls

The access token is required to make API calls. Set the token in the request's authorization header as follows:

Authorization: Bearer {a_valid_access_token}
For example, a curl request to show your account details would look as follows:
curl https://fourfour.ai/odata/me \
    -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo..."

Step 5 - Refresh your access token

When the access token expires, your API requests will receive a 401 Unauthorized response. To use the refresh token, make a POST request to the service’s token endpoint with grant_type=refresh_token , and include the refresh token, client_id and client_secret.

curl https://fourfour.ai/oauth/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=refresh_token&refresh_token={your_refresh_token}&client_id={your_client_id}&client_secret={your_client_secret}' \
    -X POST

Making API requests

#

The Four/Four REST API uses the OData protocol. OData (Open Data Protocol) is a standardized protocol used to query and manipulate data using RESTful APIs. It was developed to simplify the process of building APIs and to provide a uniform way to expose and access data. OData version 4.01, the latest iteration of the protocol, offers a robust framework for building scalable and efficient data services. This introduction will guide you through the basics of making OData 4.01 requests, covering essential operations such as fetching entity sets, retrieving individual entities by their identifiers, and handling pagination in data queries.

Fetching information about your session

You can retrieve information about the user and tenant that authorized your application for the provided bearer token.

GET /odata/me

An example payload is as follows:

{
    "@context": "https://fourfour.ai/odata/$metadata#me",
    "user_id": "9e0744e1-8410-4bcb-a51c-4225e7d0e72a",
    "user_name": "Chris Lloyd",
    "user_email": "chris@fourfour.ai",
    "tenant_id": "44c8c2c0-5627-4761-80b7-10a089d1b7bb",
    "tenant_name": "SuperCo"
}

The payload includes the tenant_id which is needed when identifying webhooks received from other customer accounts. Note that the user_id s unique to the user identity, but not unique to the tenant - a single user can be a member of multiple tenants. The access token received can only be used to access on behalf of this user, only on the tenant indicated in the response.

Fetching entity sets

An entity set in OData represents a collection of entities of a particular type, similar to a table in a relational database. To retrieve an entire entity set, you can send a simple HTTP GET request to the relevant endpoint. For example, to fetch a list of conversations, you would perform the following request:

GET /odata/Conversations
This will return a JSON response containing an array of conversation entities.

Retrieving single entities by ID

Fetching a specific entity within an entity set requires specifying the unique identifier (ID) of that entity in the URL. This is akin to retrieving a single record from a database table based on its primary key. For instance, to get a conversation with an ID of `5a160c5c-e861-11ef-9289-3b02e438cdf3`, the request would be:

GET /odata/Conversations/5a160c5c-e861-11ef-9289-3b02e438cdf3

This query will return the JSON representation of the conversation with ID `5a160c5c-e861-11ef-9289-3b02e438cdf3`.

Handling pagination

When dealing with substantial amounts of data, enabling pagination can optimize data retrieval performance. OData supports pagination through the `$top` and `$skip` query options, allowing you to control the number of entries returned and to skip over a defined number of results. For example, if you want to retrieve the first 10 conversations, use:

GET /odata/Conversations?$top=10

To fetch the next 10 conversations, skip the first 10 entries and fetch subsequent ones:

GET /odata/Conversations?$top=10&$skip=10

OData responses will include a @nextLink attribute, providing a URI to retrieve subsequent pages, ensuring seamless navigation through paginated data.

To review all the available endpoints and query parameters, check out the full documentation.

Data warehousing

#

The API can feed a data warehouse on a schedule. The data falls into three areas, described here in the order most consumers need them:

  1. Conversations : the calls, meetings and message threads, with their Participants and the transcript Fragments . This is the simplest area to sync, and many consumers need nothing else.
  2. CRM data : your accounts, contacts, leads, opportunities and owners, and their links to conversations.
  3. Insights, topics and topic models : the knowledge graph that Four/Four builds from your conversations. This is the largest and most involved area, so sync it last, once the first two are working.

The API is a standard OData service, so any OData client works with it. This section is about using the standard query options efficiently for a warehouse. All three areas use the same techniques: load each set in full once, paging by id ; then pull only what has changed, paging by timestamp and id ; ask only for the fields you need; and list identifiers now and then to find deleted records.

A scheduled job needs a credential that does not depend on a person signing in. We recommend a personal access token for this: create one with the API read scope from the personal tokens on the connections page of your Four/Four instance, and send it as a bearer token. It lasts a year, so replace it before it expires. The OAuth flow also works, but it is more involved. Requests are limited to 600 a minute for each user, and a request over the limit receives a 429 Too Many Requests response, so back off and retry.

Time columns are in UTC. The churn in a day can be large, particularly in the links between topics and insights, so it is worth syncing no more often than once an hour, and potentially for the previous hour rather than the current one.

Rows saved late

A row's timestamp is set when it is saved, and a long-running update can become visible a little after its timestamp has passed. To pick these up, start each run slightly before the highest timestamp from the previous run, for example an hour earlier, and merge the rows by id rather than appending, so a row you have seen before replaces the old copy. InsightTopics has no id , so merge it by insight_id and topic_id together.

Full sync

Start with a full load of each top level entity set. Note the time before you begin, because it becomes the starting point for your first incremental sync. Pages hold 200 rows by default. Ask for the maximum of 500 with $top to keep the number of requests down, and a larger value is limited to it. Page by id : request the first page sorted by id , then ask for the rows after the last id you received, and repeat until a page returns fewer rows than your $top :

GET /odata/Conversations?$top=500&$orderby=id&$select=id,updated_at
GET /odata/Conversations?$top=500&$orderby=id&$filter=id gt 6F9619FF-8B86-D011-B42D-00C04FC964FF

Identifiers are time-ordered UUIDs, so they increase in the order records are created, and records created while your load is running are reached later in the same sweep. Each page then takes the same time however far through the set you are. Paging by keyset is sequential within one set, so to speed up the first load of a very large set, split it into ranges of id and read the ranges in parallel, each paged as above, for example id ge 00000000-0000-0000-0000-000000000000 and id lt 40000000-0000-0000-0000-000000000000 . For InsightTopics , split on created_at instead. Responses also include a @nextLink , which pages with $skip . It works, but each page takes longer than the last on a large set, and it is slow for the service as well as for you. A $skip of more than 1,000,000 is rejected.

Incremental sync

After the full sync, ask only for rows changed since the last run, and page by keyset in the same way. Sort by the timestamp column and then id . Ask for the first page at or after the highest timestamp you have already received. For each later page, ask for the rows after the timestamp and id of the last row you received:

GET /odata/Conversations?$top=500&$orderby=updated_at,id&$filter=updated_at ge 2026-11-01T00:00:00Z
GET /odata/Conversations?$top=500&$orderby=updated_at,id&$filter=updated_at ge 2026-11-03T08:15:00Z and (updated_at gt 2026-11-03T08:15:00Z or (updated_at eq 2026-11-03T08:15:00Z and id gt 6F9619FF-8B86-D011-B42D-00C04FC964FF))

The id is part of the condition because many rows can share one timestamp. Always repeat the timestamp as an at-or-after condition in front of the rest, as in the second example. It lets the service start from the right place in its index. Without it, each page takes longer than the last, even though it returns the same rows. As a loop:

cursor = highest timestamp from the previous run, less an hour
last = none
repeat
    page = next page (at or after cursor the first time, otherwise after last)
    merge page into the warehouse by id
    last = final row of page
until page has fewer rows than $top
cursor = highest timestamp seen

Starting at or after the cursor means the rows at the boundary are returned again, which merging by id handles. Which column to use depends on the kind of data, as described in the sections below.

Choosing fields and related records

Use $select to return only the columns you need, which makes each response smaller and faster. Always include id and the timestamp column. Use $expand to fetch related records in the same request instead of one request per row, and $select inside it to limit the related columns:

GET /odata/Conversations?$top=100&$filter=updated_at ge 2026-11-01T00:00:00Z&$orderby=updated_at,id&$select=id,start,updated_at&$expand=participants($select=id,email,role),accounts($select=id,name)

The filter applies to the records you request, not to the related records. Expanded collections are paged with the same default and maximum page size, and when a row has more related records than fit in a page, it includes a next link for that property, for example participants @nextLink , which you follow until it is no longer returned. Expanding multiplies the work of a request, so use a smaller $top on the request itself, as above, when you expand collections that can be large.

Detecting deletions

Records can be removed rather than flagged, and no entity set reports a deletion. To detect deletions, list only the identifiers of a set and remove anything from your warehouse that is no longer present. This reads every row of the set, so do it infrequently, for example once a day, rather than on every sync:

GET /odata/Conversations?$top=500&$orderby=id&$select=id

Conversations

A conversation holds the metadata for a call, meeting or message thread, such as when it happened, its type and its summary. The people who took part are held as Participants , and the transcript as Fragments . A conversation also relates to CRM records, and can carry labels.

How to sync

  1. Load Conversations incrementally on updated_at , expanding only the related records you need: participants , fragments , accounts , contacts , leads , opportunities , owners and labels . Fragments hold the transcript and are by far the largest, so leave them out unless you need the text.
  2. For each conversation that appears, follow any next links on its related records, then replace the related records you hold for it with everything returned, removing any that are no longer returned.
  3. Periodically list the identifiers of Conversations and remove any you hold that are no longer returned.

Things to know

  • A conversation's updated_at changes when the conversation changes, when its transcript or participants change, when its links to accounts, contacts, leads, opportunities or owners change, and when a label is added or removed.
  • Participants and Fragments belong to a conversation. Load them through the conversation, as above, and not as sets of their own, so that you always hold the conversation they belong to.
  • A change to a CRM record itself, such as an account being renamed, does not change the conversations related to it. Get those changes through the CRM route.
  • When a transcript expires under your retention settings the conversation remains available, with a pipeline_status of expired and no fragments.

CRM data

Accounts , Contacts , Leads , Opportunities and Owners are the records from your CRM that conversations and insights relate to.

How to sync

  1. Load each set incrementally on updated , the time the record last changed in your CRM, paging by keyset in the same way as for conversations.
  2. Periodically list the identifiers of each set and remove any you hold that are no longer returned.
  3. Get the links between CRM records and conversations as described below. The links to insights arrive with the insights, as described in the next section.

CRM identifiers are text, so quote them in id filters:

GET /odata/Accounts?$top=500&$orderby=updated,id&$filter=updated ge 2026-11-01T00:00:00Z
GET /odata/Accounts?$top=500&$orderby=updated,id&$filter=updated ge 2026-11-03T08:15:00Z and (updated gt 2026-11-03T08:15:00Z or (updated eq 2026-11-03T08:15:00Z and id gt '0015g00000AbCdEFGH'))

Links to conversations

There are two ways to read the links between conversations and CRM records. You can expand accounts , contacts , leads , opportunities and owners on Conversations , as described above. This reads the links of the conversations that changed, so it suits a large data set.

Or you can read the links as sets of their own: ConversationAccounts , ConversationContacts , ConversationLeads , ConversationOpportunities and ConversationOwners . Each row is one link, for example a conversation_id and an account_id . Links have no timestamp, so there is no delta: read the whole set on every run and replace what you hold, which also removes the links that are gone. For a small data set this is cheaper than expanding, because it is a single pass with nothing to compare. As the data set grows, expanding becomes cheaper, because it only follows what changed. Page by keyset on the two columns, as for InsightTopics :

GET /odata/ConversationAccounts?$top=500&$orderby=conversation_id,account_id
GET /odata/ConversationAccounts?$top=500&$orderby=conversation_id,account_id&$filter=conversation_id ge 6F9619FF-8B86-D011-B42D-00C04FC964FF and (conversation_id gt 6F9619FF-8B86-D011-B42D-00C04FC964FF or (conversation_id eq 6F9619FF-8B86-D011-B42D-00C04FC964FF and account_id gt '0015g00000AbCdEFGH'))

Insights, topics and topic models

This is the advanced part of the sync. An insight is a single finding extracted from a conversation, such as a pain, a need or a request. Insights are grouped into topics, which are themes, and each topic belongs to a topic model. Insights relate to CRM records and can carry labels, and so can topics. There are many more insights than conversations, and the memberships of insights in topics are the largest set of all, so follow the steps below closely.

How to sync

Do these steps in this order on every run. Memberships in InsightTopics refer to both topics and insights, so load those first. The memberships are the largest part of this data, so read them from InsightTopics directly, not by expanding topics on insights or insights on topics.

  1. Load TopicModels in full on each run, and replace what you hold. There are far fewer than topics, so this is cheap.
  2. Load Topics incrementally on updated_at . Topics can carry labels, which you can fetch with $expand=labels . A topic that has been merged into another returns the identifier of the other in merged_into_id :
GET /odata/Topics?$top=500&$orderby=updated_at,id&$filter=updated_at ge 2026-11-01T00:00:00Z
  1. Load Insights incrementally, as two separate keyset-paged passes, each with its own highest value: one on generated_at to find new insights, and one on updated_at to find changed ones. Expand the related records you need, such as accounts , contacts , opportunities and labels . An insight can appear in both passes, so merge by id . These requests use a smaller $top because they expand:
GET /odata/Insights?$top=100&$orderby=generated_at,id&$filter=generated_at ge 2026-11-01T00:00:00Z&$expand=accounts($select=id)
GET /odata/Insights?$top=100&$orderby=updated_at,id&$filter=updated_at ge 2026-11-01T00:00:00Z&$expand=accounts($select=id)
  1. For each insight that appears, replace the related records you hold for it with those returned.
  2. Load InsightTopics incrementally on created_at . Each row is one insight in one topic, and a row is never changed after it is added, so on the first load simply start from an early date. Sort by created_at , then insight_id , then topic_id , and page by keyset on all three, because one step can add many rows with the same time:
GET /odata/InsightTopics?$top=500&$orderby=created_at,insight_id,topic_id&$filter=created_at ge 2026-11-01T00:00:00Z
GET /odata/InsightTopics?$top=500&$orderby=created_at,insight_id,topic_id&$filter=created_at ge 2026-11-03T08:15:00Z and (created_at gt 2026-11-03T08:15:00Z or (created_at eq 2026-11-03T08:15:00Z and (insight_id gt 6F9619FF-8B86-D011-B42D-00C04FC964FF or (insight_id eq 6F9619FF-8B86-D011-B42D-00C04FC964FF and topic_id gt 0B7E1F3A-2C54-4D9E-9A61-5E8C2D4F7B10))))
  1. Remove memberships when a topic has a merged_into_id , because they are now rows for the other topic and arrive through step 5, and when a topic or an insight is no longer returned by the periodic list in step 7.
  2. Periodically list the identifiers of TopicModels , Topics and Insights and remove any you hold that are no longer returned, along with their memberships.

Things to know

  • A topic can hold hundreds of thousands of insights, and insights are added to topics throughout the day. Adding an insight to a topic changes neither the insight nor the topic. It appears as a new row in InsightTopics , so you only ever read the memberships you have not yet seen.
  • A new topic model has a new identifier. A regenerated topic model keeps its identifier, but all of its topics are new and have new identifiers. The old topics are no longer returned, and the new ones appear in your incremental load of Topics , with their memberships in InsightTopics .
  • An insight comes from a moment in a conversation, so its created_at and updated_at start out as the time of that moment, not the time Four/Four produced the insight. generated_at is the time Four/Four produced it and never changes, which is why you read insights on both columns. When an insight later changes, including a change to its links to CRM records or its labels, its updated_at moves to the time of the change.
  • Do not assume a topic in one topic model corresponds to a topic in another.
  • Insights are deleted when they pass your retention limit.

Custom CRM Importer

#

If you have a custom CRM that Four/Four does not support then the CRM importer lets you bulk import your own records so they can be matched against conversations and surfaced throughout the platform. You submit records as CSV, one record per row, and Four/Four creates or updates them as needed. It is recommended that you first push all records, and then deltas periodically as the content changes. The importer supports the following record types, but you do not have to use them all:

Record type Type identifier
Account account
Contact contact
Opportunity opportunity
Lead lead
User user
Object object

Authentication

The CRM Importer is authenticated with a bearer token issued by Four/Four. Navigate to connections and create a Personal Access Token with the Import data scope. Once you have it, send it in the Authorization header on every request:

Authorization: Bearer {your_token}

Requests with a missing or invalid token receive a 401 Unauthorized response.

Standard and additional fields

Each record type has a set of standard fields that map directly onto the corresponding fields in a Four/Four CRM record. The first column of every CSV must be id , which is your own unique identifier for the record and is used to create, update, and delete it. The standard fields available for each record type are listed in the generated API documentation.

Any column in your CSV that is not a standard field is stored as an additional field. Additional fields let you attach your own custom data to a record without it needing to map onto a standard Four/Four field. They are preserved exactly as submitted and returned alongside the standard fields when you read a record back. There is no need to declare additional fields in advance, simply include the columns you want. Additional fields can be configured as custom filters in Four/Four.

Data type encoding

The following rules should be followed to map data types into CSV:

  • Fields declared in the header but missing in the record are stored as null values (ie, when updating a record, send all field values your header declares)
  • Dates and timestamps should be provided in ISO 8601 format in the UTC timezone
  • Booleans should be provided as the literal strings 'true' or 'false' (lowercase)
  • 'currency' fields should use ISO 4217 currency codes

Submitting records

To create or update records, send an HTTP PUT request to the import endpoint for the record type, with the CSV as the raw request body. The first row is the header containing your column names, and each subsequent row is a record. Records are matched on the id column: an unrecognised id creates a new record, while an existing one updates it.

There is no hard limit on the number of records in a single request, but your client must keep the connection open until the upload completes and Four/Four returns the 202 Accepted response. If your client disconnects before then, the upload is incomplete and the import is not queued. Once accepted, the records are processed in the background regardless of your connection. We recommend importing around 10,000 records at a time to keep uploads and individual import jobs manageable.

In the example below, name , website , and industry are standard account fields, while crm_segment is an additional field:

curl https://fourfour.ai/import/crm/account \
    -X PUT \
    -H "Authorization: Bearer {your_token}" \
    -H "Content-Type: text/csv" \
    --data-binary $'id,name,website,industry,crm_segment\nacc-001,Acme Industries,https://acme.test,Robotics,Enterprise\nacc-002,TechCorp,https://techcorp.test,Software,Mid-Market'

A successful submission returns 202 Accepted with a JSON body containing the job id, and a Location header pointing to the status endpoint for that job. Records are validated and processed asynchronously, so the response confirms the import was accepted.

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://fourfour.ai/import/job/9e259d7a-8dd2-42ce-beb8-ef637eda7ef7

{
    "job": "9e259d7a-8dd2-42ce-beb8-ef637eda7ef7"
}

Use the job id to poll the status endpoint for progress and to discover any problems with the CSV.

Checking import status

Because records are processed asynchronously, both submitting and deleting return a job id. Send an HTTP GET request to the job endpoint, using the Location header returned with the 202 Accepted response to track progress and confirm completion.

curl https://fourfour.ai/import/job/9e259d7a-8dd2-42ce-beb8-ef637eda7ef7 \
    -H "Authorization: Bearer {your_token}"

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "completed",
    "processed": 2,
    "error": null,
    "error_line": null,
    "created_at": "2025-02-06T14:41:38+00:00",
    "updated_at": "2025-02-06T14:41:40+00:00",
    "started_at": "2025-02-06T14:41:39+00:00",
    "completed_at": "2025-02-06T14:41:40+00:00"
}

The status field is one of pending , processing , completed , or failed , and processed is the number of records handled so far. If the CSV could not be processed the status is failed , error describes the problem, and error_line indicates the offending row where applicable.

Reading back a single record

To check what Four/Four has stored for a record, useful when testing your submissions, send an HTTP GET request to the endpoint for the record type, with your record id appended to the path. The response is a CSV containing a header row and a single data row, with both standard and additional fields merged together.

curl https://fourfour.ai/import/crm/account/acc-001 \
    -H "Authorization: Bearer {your_token}"

Example response:

HTTP/1.1 200 OK
Content-Type: text/csv

id,name,website,industry,crm_segment
acc-001,Acme Industries,https://acme.test,Robotics,Enterprise

If no record exists for that id , the endpoint returns 404 Not Found .

Deleting records

To delete records, send an HTTP DELETE request to the endpoint for the record type. The body is a CSV that only needs an id column; any other columns are ignored. Each row identifies a record to delete.

curl https://fourfour.ai/import/crm/account \
    -X DELETE \
    -H "Authorization: Bearer {your_token}" \
    -H "Content-Type: text/csv" \
    --data-binary $'id\nacc-001\nacc-002'

As with submitting, a successful request returns 202 Accepted with a job id you can poll for status. Only records that you imported are affected; records that originated from other connected services are left untouched.

Webhooks

#

Four/Four supports notifying your service of changes via signed, HTTP POST webhooks.

Set Up Your Webhook Endpoint

Set up a URL on your server where the webhook provider will send HTTP POST requests. This URL will act as your webhook endpoint. For example, https://yourdomain.com/webhook

Configure the webhook in Four/Four

  1. Sign in as an admin into your Four/Four instance. Go to the connections page , then scroll down to "Webhooks".
  2. Click Add Webhook.
  3. Complete the following fields:
    • Endpoint - The HTTP endpoint that will receive the POST requests.
    • Events - The types of event you want your webhook to receive.
    • Linked OAuth client - (Optional) The OAuth client this webhook is linked to. When a webhook is linked to a client, it will receive notifications for all Four/Four tenants that have authorized your application for API access. With no linked client the webhook will only receive events for the tenant it was created in.
  4. Click Create.

Upon successful creation, the webhook secret will be displayed. Take note of this value as you'll need it to validate the authenticity of the webhook messages you receive.

Listen for Incoming Requests

Set up a route or controller action on your server to listen for POST requests on the webhook endpoint.

Parse the Request

When a request is received, parse the payload, which comes in JSON format. Ensure you handle it correctly to avoid errors related to incorrect data types or format issues.

An example payload is as follows:

{
    "timestamp": "2025-02-06T14:41:38+00:00",
    "event": "conversation_processing_complete",
    "tenant": "9e1f42e6-dda6-46c6-9740-f51fac539cf8",
    "payload": {
"id": "9e259d7a-8dd2-42ce-beb8-ef637eda7ef7"
    }
}

The payload contains the timestamp, the event being described, the ID of the tenant that the event originated from and the payload. The payload is event-specific, in this case the ID refers to the conversation ID that has finished processing.

Validate the Webhook Signature

The webhook request will include a signature header named Signature which contains the HMAC signature of the payload to verify its authenticity.

Use the SHA-256 hashing algorithm provided by your platform and compute a hash of the payload using the secret key provided earlier. This is generally done as follows:

HMAC_SHA256(SECRET_KEY, JSON_PAYLOAD)

Compare your computed signature with the signature from the webhook header. If the signatures match, proceed to process the payload. - If they do not match, discard the request and optionally log an error or alert for further investigation.

Respond to the Webhook

Send an appropriate HTTP response status to acknowledge receipt of the webhook. Typically, a 200 OK status code if everything is successful or 40x/50x if there's an error. If we receive an error status we will retry sending the webhook up to three times using an exponential backoff algorithm.

Services

#

Four/Four integrates and aggregates many conversation sources. In entity sets such as Conversations the API presents a service to identify the originating service and service_id as the ID that service used to identify it internally.

The list of service identifiers Four/Four uses is:

Service Identifier
3CX 4d2c8aae-0e1f-4f44-9c7c-2b1f7a3d4ee6
Aircall 4b5ad3f0-acde-11ef-b2fd-fb8bbf6b0760
Alchemer ff4dc696-8b4a-11f1-8660-66539a87c87a
Amazon Connect 8686f1bf-7d6e-4918-b826-55f5f0249aa4
Attention 8d2f5e10-8a1a-4f6b-b3c1-1cdb27a47e93
Attio 3b8f2c10-1607-11f1-a2d4-8b3e9c7f5a21
Avoma 85307a92-2067-11f0-8f61-2b404342a9a1
Chorus 2d29be9e-a8f3-11ef-98ee-071763940244
Clari c5990584-582c-11f0-aff2-e35b634f5d88
Craft.io 2c6bdfbd-85dd-4ac8-afd0-4f93effa7fb7
Dovetail 9d742b80-1834-11ef-9d63-37de81059583
Dynamics 365 a8c7e1f0-a9a3-11f0-972a-cf2d40de4700
Fireflies a4535e3e-2b35-11f0-b47d-070e8f0f4ba8
Four/Four Notetaker 9a6a9d3a-ff29-11ee-bf05-e3647beb6dd1
Genesys Cloud 9c1e5d24-9c2a-11f1-9e4e-66539a87c879
Gong 2ced8f92-354e-11ee-8b1e-6f08dcfc80c2
Google Calendar d8dffa84-11e8-11ef-9459-f75cbaa47af3
Google Mail 650383d0-c6e4-11f0-bd4c-6b8dd6eff051
Google Meet 255cab90-5ae8-11ee-8ed5-0fe58e1eacd7
Halo 6f73048f-daa3-480c-8701-6afb68303835
HubSpot 2a587d15-0bb5-49bd-86e4-67730b94c3f7
Intercom f65905b6-b7c8-11ef-9ae0-476e68765d45
Jiminny e3b03a44-83c3-11ef-8ba1-c7ed1de301db
Jira 1fb75b16-7534-435c-9bfb-58452232cd76
Manual Upload 66f8a52a-1908-11ef-a0d6-475211cce46c
Marketo 5a67a228-44a4-4826-aebb-db554d5448cf
Microsoft Teams 196a746a-0f3b-4bec-b33c-70147ac53961
NiCE CXone b2bcea10-4ba1-11f1-b2b7-f0190254f384
Notion 4a4b4a37-1f30-4ef7-a5cf-bf3d18af9186
Odoo da49d2c0-6c0a-4d2f-b54d-df3147f9d953
Outlook Calendar d55968dc-fefb-11ee-b004-6b1c6108891d
Outlook Mail 47b6429a-f876-11f0-a6c8-cbf1683dbd2d
Outreach fbd68c58-92f6-11ef-a8ee-cbb9775642bb
Planhat 27a9c86c-1f7f-11f0-8874-b708ff163df8
ProductBoard 0e66679e-594a-11ef-a2b0-bfcbc852de8e
Pylon 73191d08-d676-11f0-bbc3-66539a87c87a
RingCentral 261de476-f236-11f0-88e3-cf91d1e58952
Salesforce b9d1c5a8-bd2d-45bb-b394-bb6c70bee099
Salesloft c175af54-4f03-4d48-8ee6-da8cd6837eb4
ServiceNow 13a48542-3ddc-11f1-9583-66539a87c879
Slack e25731da-68a0-11f0-a8cb-a3d84b86fcc8
Twilio d6cac050-b01d-11f1-8e59-66539a87c87a
Webex 6140fce4-c23a-11f1-b648-66539a87c879
Weflow 590fe43a-3416-471e-8d7e-720b92348c44
Zendesk eb778e68-ab0e-11ef-b5a1-672f26fa0665
Zoom 98bb866e-44f5-4e5e-8a6d-e4610b2d6a03

Model Context Protocol (MCP)

#

Four/Four exposes a native MCP server, allowing AI agents like Claude, ChatGPT, and custom LLM applications to query your customer intelligence directly. The MCP server provides structured tools for searching conversations, insights, accounts, and contacts - grounding AI workflows in real customer data without building custom integrations.

Connecting to the MCP server

The MCP server url is https://fourfour.ai/mcp

Authentication is automatic via OAuth discovery.

We use cookies as specified in our Privacy Policy. You agree to consent to the use of these technologies by clicking Allow Cookies.