# Context API

Use a user ID to retrieve installation attribution and purchase and churn predictions with the Context API.

Source: https://cue.airbridge.io/docs/en/reference/context-api
Language: en
Updated: 2026-10-15

The Context API accepts an app user ID and returns information about the ad credited with the installation, along with purchase and churn predictions. Before calling the API, confirm that CUE is enabled and prediction data is ready for your app. For testing, use a test user ID with prediction data available. See [Get Started](/docs/en/quickstart) for preparation steps.

## Endpoint

```text
POST https://api.airbridge.io/entry/inference/v1/context
```

Call this endpoint from your server or CRM. The authentication token identifies the app, so omit `appId` from the request body.

## Request

### Complete request

This complete request uses an external user ID. Replace the token and user ID with your own values. For other identifier types, see the [payload examples](#payload-examples) below.

HTTP

```http
POST /entry/inference/v1/context HTTP/1.1
Host: api.airbridge.io
Authorization: Bearer <AIRBRIDGE_APP_TOKEN>
Content-Type: application/json

{
  "airbridgeExternalUserId": "abc-123"
}
```

cURL

If your server has the token in the `AIRBRIDGE_APP_TOKEN` environment variable, you can use the following cURL example. Replace `abc-123` with a real test user ID whose prediction data is ready.

```bash
curl --request POST --include \
  'https://api.airbridge.io/entry/inference/v1/context' \
  --header "Authorization: Bearer ${AIRBRIDGE_APP_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"airbridgeExternalUserId":"abc-123"}'
```

### Headers

`Authorization` (`string`, Required)

Send the app SDK token or web SDK token as `Bearer <AIRBRIDGE_APP_TOKEN>`.

`Content-Type` (`string`, Required)

Send `application/json`.

Find the token under **\[Settings]>\[Tokens]** in the Airbridge dashboard. Store it in secure server or CRM configuration. See the [token guide](https://help.airbridge.io/en/guides/tokens) for details.

### Request body

User identifier

(`object`)

Include exactly one field from this group.

`userId` (`string`)

Send the Airbridge Generated UUID that Airbridge assigned to the app user.

`brazeDeviceId` (`string`)

Send the Device ID from the Braze SDK.

`airbridgeExternalUserId` (`string`)

Send the external user ID your service sent to Airbridge.

The ID must be a string that remains non-empty after leading and trailing whitespace is removed. Use an ID collected for the same app as the token. A lookup by Braze Device ID or external user ID requires a mapping between that ID and an Airbridge user.

> `brazeDeviceId` is the Device ID from the Braze SDK. It is different from Braze's `external_id`.

The maximum request body size is 65,536 bytes. The API returns `422 VALIDATION_ERROR` in these cases:

* The request omits the ID or includes more than one ID.
* The ID is an empty string.
* The request includes undefined fields, such as `appId`.

### Payload examples

Select the tab for your identifier type. Replace the example ID with a real test user ID whose prediction data is ready.

External user ID

```json
{
  "airbridgeExternalUserId": "abc-123"
}
```

Airbridge Generated UUID

```json
{
  "userId": "1b1a2d3e-4f56-7890-abcd-ef0123456789"
}
```

Braze Device ID

```json
{
  "brazeDeviceId": "braze-device-123"
}
```

## Response

A successful request returns HTTP `200` and a JSON body. The `context.lastTouchpoint` object contains information about the ad credited with the installation. The `predictions` object includes both `probability` and `tier` for each of the purchase and churn models.

### Response example

The response below corresponds to a request using the external user ID `abc-123`. All identifiers and values are illustrative.

```http
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a

{
  "requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a",
  "appId": 1234,
  "user": {
    "id": "abc-123",
    "type": "airbridge_external_user_id"
  },
  "context": {
    "lastTouchpoint": {
      "channel": "media_A",
      "campaign": "moving_service",
      "adGroup": "moving_quote",
      "adCreative": "moving_guide_video",
      "term": null
    }
  },
  "predictions": {
    "d3_purchase": {
      "probability": 0.723,
      "tier": "high"
    },
    "d3_churn": {
      "probability": 0.812,
      "tier": "high"
    }
  }
}
```

### Response body

`requestId` (`string`)

The ID assigned to this call, matching the response's `X-Request-Id` header. Use it when investigating errors or requesting help.

`appId` (`integer`)

The Airbridge app ID identified by the server from the token.

User

`user` (`object`)

`user.id` (`string`)

The ID used in the request, with leading and trailing whitespace removed. A request using an external ID returns that external ID.

`user.type` (`string`)

The type of identifier used in the request.

Allowed values

`airbridge_generated_uuid` `braze_device_id` `airbridge_external_user_id`

Attribution context

`context` (`object`)

Installation attribution

`context.lastTouchpoint` (`object | null`)

Information about the ad credited with the app installation on the device identified by the requested user ID. A successful lookup with no installation attribution result returns null.

`context.lastTouchpoint.channel` (`string | null`)

The channel credited with the installation.

`context.lastTouchpoint.campaign` (`string | null`)

The campaign credited with the installation.

`context.lastTouchpoint.adGroup` (`string | null`)

The ad group within the campaign credited with the installation.

`context.lastTouchpoint.adCreative` (`string | null`)

The ad creative credited with the installation.

`context.lastTouchpoint.term` (`string | null`)

The keyword configured for the ad. It is not guaranteed to match the search query the app user entered.

Predictions

`predictions` (`object`)

Purchase prediction

`predictions.d3_purchase` (`object`)

Purchase likelihood within three days after app installation.

`predictions.d3_purchase.probability` (`number`): `0 ≤ value ≤ 1`

The probability of a standard order-completed event occurring within three days after app installation.

`predictions.d3_purchase.tier` (`string`): `low / medium / high`

The tier based on the distribution of predicted probabilities for the purchase model's training data.

Churn prediction

`predictions.d3_churn` (`object`)

Churn likelihood after day three through day 30 after app installation.

`predictions.d3_churn.probability` (`number`): `0 ≤ value ≤ 1`

The probability of no activity events being observed after day three through day 30 after app installation.

`predictions.d3_churn.tier` (`string`): `low / medium / high`

The tier based on the distribution of predicted probabilities for the churn model's training data.

### Interpreting the response

Both models use the app installation time as the reference point for their prediction windows. The purchase model predicts the standard order-completed event, `airbridge.ecommerce.order.completed`.

Probabilities are rounded to three decimal places. A value of `0.723` means 72.3%. Tiers use the unrounded probability and the distribution of predicted probabilities for each model's training data. You can use the returned `tier` as a condition in your service.

The purchase and churn models predict different events. Both tiers can be `high`.

#### Interpreting installation attribution

`context.lastTouchpoint` provides the channel and campaign credited with installation. If no attribution result is found, the entire object is `null`. If only an individual value is missing, that field is `null`. An object always contains all five keys.

CUE returns restricted values, such as `restricted`, unchanged. The value `unattributed` can result from masked information. Both values are different from `null`. These values alone do not indicate whether acquisition was organic. See [Extended Privacy Control (EPC)](https://help.airbridge.io/en/guides/extended-privacy-control) for conditions that restrict data sharing.

[Compare response examples in Using Installation Attribution](/docs/en/guides/install-touchpoint#compare-response-examples) shows the differences between available values, a null object, null fields, `restricted`, and `unattributed`. See [Using Context](/docs/en/guides/using-context) for examples of combining campaign information with predictions to change screens or messages.

### Error response

If the Context API cannot process a request, it returns an HTTP status code for the error and an `error` object. The following response indicates that an identifier mapping or prediction data was not found.

```http
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: 01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a

{
  "requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a",
  "error": {
    "code": "CONTEXT_DATA_NOT_FOUND",
    "message": "Context identifier or features were not found.",
    "retryable": false
  }
}
```

Use `error.code` to identify errors in your application and `error.retryable` to decide whether to retry. Do not use the message text to decide how your application behaves. See [Error Handling](/docs/en/reference/errors) for all error codes and default behavior.