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.

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 Add 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.

  5. 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.

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. 

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 @odata.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.

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.

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