Skip to contentAirbridgeCUEDocs

Context API

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

Last updated

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 for preparation steps.

Endpoint

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

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

{
  "airbridgeExternalUserId": "abc-123"
}

Headers

Authorizationstring

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

Content-Typestring

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 for details.

Request body

User identifier

object
userIdstring

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

brazeDeviceIdstring

Send the Device ID from the Braze SDK.

airbridgeExternalUserIdstring

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.

{
  "airbridgeExternalUserId": "abc-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/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

requestIdstring

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

appIdinteger

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

userobjectUser
idstring

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

typestring

The type of identifier used in the request.

Allowed values

airbridge_generated_uuid braze_device_id airbridge_external_user_id

contextobjectAttribution context
lastTouchpointobject | nullInstallation attributionInformation 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.
channelstring | null

The channel credited with the installation.

campaignstring | null

The campaign credited with the installation.

adGroupstring | null

The ad group within the campaign credited with the installation.

adCreativestring | null

The ad creative credited with the installation.

termstring | null

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

predictionsobjectPredictions
d3_purchaseobjectPurchase predictionPurchase likelihood within three days after app installation.
probabilitynumber0 ≤ value ≤ 1

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

tierstringlow / medium / high

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

d3_churnobjectChurn predictionChurn likelihood after day three through day 30 after app installation.
probabilitynumber0 ≤ value ≤ 1

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

tierstringlow / 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) for conditions that restrict data sharing.

Compare response examples in Using Installation Attribution shows the differences between available values, a null object, null fields, restricted, and unattributed. See 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/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 for all error codes and default behavior.

Overview

Previous Page

Error Handling

Next Page

On this page