Get Treatments - Auxia Docs

Two endpoints — check which one your project usesAuxia serves the Get Treatments API from two different endpoints. Each project is provisioned against one of them, so you must use the endpoint assigned to your project — calls to the wrong endpoint will fail.To find your project’s endpoint, open the Auxia Console and go to Configurations → Experience Delivery → API Integrations.

API Definition

Use the endpoint that matches your project (see note above). All other request parameters, headers, and response fields are identical between the two.

POST https://apis.auxia.io/v1/GetTreatments

POST https://apis-xsa4.auxia.io/v1/GetTreatments

Path Parameters

Name	Type	Description
api_key	String	A string API key that is issued to each project or company that uses Auxia. This can either be set in the request parameters or in the header.

Headers

Name	Type	Description
x-api-key	String	A string API key that is issued to each project or company that uses Auxia. This API key should have permission to call this API. This can either be set in the request parameters or in the header.

Status Codes

200: OK The treatments will be returned successfully.
401: Unauthorized Please ensure you have added the correct API key, projectId, and any other parameters in the request.

Raw request body

{
    "projectId": "1250",
    // This is an example user ID. Actual user ID can be obfuscated. See
    // documentation below
    "userId": "gGTE8CWUIgpzPivCejVk7JN284V",
    "contextualAttributes": [
        {
            "key": "profile_id",
            "stringValue": "pr1234"
        },
        {
            "key": "last_action",
            "stringValue": "button_x_clicked"
        }
    ],
    "surfaces": [
        {
            "surface": "HOME_SCREEN",
            "maximumTreatmentCount": 1
        },
        {
            "surface": "CART_SCREEN",
            "maximumTreatmentCount": 3,
            "minimumTreatmentCount": 1
        }
    ],    
    // Optional. Defaults to "en".
    "languageCode": "en"
}

Example curl

curl --location --request POST 'https://apis.auxia.io/v1/GetTreatments' \
--header 'Content-Type: application/json' \
--header 'x-api-key: *********************' \
--data-raw '{
    "projectId": "1250",
    "userId": "gGTE8CWUIgpzPivCejVk79JN284V",
    "contextualAttributes": [
        {
            "key": "profile_id",
            "integerValue": 10
        },
        {
            "key": "last_action",
            "stringValue": "button_x_clicked"
        }
    ],
    "surfaces": [
        {
            "surface": "HOME_SCREEN",  
            "maximumTreatmentCount": 1          
        },
        {
            "surface": "CART_SCREEN",
            "maximumTreatmentCount": 3,
            "minimumTreatmentCount": 1
        }
    ]
}'

Response

{
   "responseId": "690e24d8-16a6-4518-bf37-09a8f0120dfb",
   "userTreatments": [
       {
           "treatmentId": "6",
           "treatmentTrackingId": "6_690e24d8-16a6-4518-bf37-09a8f0120dfb",
           "rank": "1",
           "treatmentContent": "{ \"title\": \"You have a new message!\", \"description\": \"Learn how our product helps you\", \"cta_name\": \"Learn more\", \"cta_link\": \"/tabs/home/feed\"}",
           "treatmentType": "IN_APP_CONTENT_CARD",
           "surface": "HOME_SCREEN",
           "contentLanguageCode": "en",
       },
       {
           "treatmentId": "4",
           "treatmentTrackingId": "4_690e24d8-16a6-4518-bf37-09a8f0120dfb",
           "rank": "1",
           "treatmentContent": "{ \"title\": \"Check out your trends\", \"description\": \"87% of users found this feature useful\", \"cta_name\": \"View trends\", \"cta_link\": \"/actionscreen\"}",
           "treatmentType": "IN_APP_CONTENT_CARD",
           "surface": "CART_SCREEN",
           "contentLanguageCode": "en",
       },
       {
           "treatmentId": "3",
           "treatmentTrackingId": "3_690e24d8-16a6-4518-bf37-09a8f0120dfb",
           "rank": "2",
           "treatmentContent": "{ \"title\": \"Check leaderboard\", \"description\": \"See your global ranking\", \"cta_name\": \"View leaderboard\", \"cta_link\": \"/leaderboardscreen\"}",
           "treatmentType": "IN_APP_CONTENT_CARD",
           "surface": "HOME_SCREEN",
           "contentLanguageCode": "en",
       }
   ]
}

Schema Reference

Request

Name	Data Type	Required?	Description
projectId	string	Required	For a given customer’s project, this should always be the same.
userId	string	Required	This is the Unique ID for every user.
contextualAttributes	json	Optional	The set of additional attributes from the app’s context. Example: Current screen, recent actions, or context selections of the user. Each contextual attribute is a key-value pair. What to include: Any user attributes that are potentially newer than what Auxia has last seen. This enables the latest signals to be included in the rule processing and ML models for the treatment selection. Other signals identifying the user’s current context in the app. For example, this could be `last_button_clicked` or `current_screen_id`. Duplicate attributes with the same key will throw an exception. Examples: { “key”: “profile_id”, “stringValue”: “pr1234” } { “key”: “profile_id”, “integerValue”: 10 }
surfaces	json	Required	At least one surface should be provided in the request. Each surface contains: `surface` is a client-configured parameter to request treatments for a particular UI component, screen (home screen), or use case (coupon). A typical example of surface is `HOME_SCREEN` or `PURCHASE_SCREEN`. `maximumTreatmentCount` (Optional) is the maximum number of treatments that should be returned to the client for the given surface. If no value is set, defaults to 1. `minimumTreatmentCount` (Optional) is the minimum number of treatments that should be returned to the client for a given surface. If this field is set, the response is guaranteed to have either 0 or greater than or equal to the value of `minimumTreatmentCount`. If no value is set, it defaults to 0. Example: { “surface”: “CAROUSEL”, “maximumTreatmentCount”: 10, “minimumTreatmentCount”: 1 }
languageCode	string	Optional	The language code that is being requested for the content of the treatment. Format: IETF BCP 47. If this field is left unspecified, a default language (en) is used. Treatments that do not have translations for the requested language will not be returned.
maximumTreatmentCount	int64	Optional	The maximum amount of treatments that should be returned for the client. If no value is set, this defaults to 1.

Response

Name	Data Type	Description
responseId	string	Unique ID generated for each call to `getTreatments`. This ID is global to the response compared to `UserTreatment.treatmentTrackingId` that is specific to each treatment in this response. The treatment ID is required to ensure there is a sufficient feedback loop instead of this global response ID unless zero treatments were returned in the response.
userTreatments	json (see table below)	List of treatments that contain the information needed to render them in your UI or messaging system.

userTreatments

Name	Data Type	Description
treatmentId	string	A unique ID that identifies a specific treatment. It can also be found in the Auxia console in the “Overview” section under “Treatments”.
treatmentTrackingId	string	A unique ID that references not only the specific treatment, but also the specific RPC call in which the treatment was returned.
surface	string	The name of the surface, as defined above in the request, on which this treatment should be rendered or for which this treatment should be used.
rank	int64	The rank of the treatment in the response for the given surface. Auxia ranks and sorts the treatments for each user before they are provisioned in the response.
treatmentType	string	A client-configured parameter used to decide how to render the content. Example: “In App Content Card” for rendering a card with title, text, and image, or “Banner” for a different UI component.
treatmentContent	json	The content to be displayed (in app) or included (messages). Placeholders in the content can be replaced by personalization signals. Content format is owned by Auxia Customers via the Treatment Config UI. It can be plain text, JSON, HTML, JS snippet, or any format directly usable by the client UI. Example: `{ “content”: ”{ title: ‘Check out your trends’, description: ‘87% of users found this feature useful’, cta_name: ‘View trends’, cta_link: ‘/actionscreen’ }” }`
contentLanguageCode	string	Language code for the content of the treatment. Format: IETF BCP 47.

Appendix

Language and translations

Treatment content such as the in_app_content_card can be translated into different languages. To use translations, select a specific language code in the “language_code” JSON field when posting to your project’s Get Treatments endpoint (see API Definition above for the two possible endpoints).

Example

curl --location --request POST 'https://apis.auxia.io/v1/GetTreatments' \
--header 'Content-Type: application/json' \
--header 'x-api-key: *********************' \
--data-raw '{
    "projectId": "1250",
    "userId": "gGTE8CWUIgpzPivCejVk7JN284V",
    "contextualAttributes": [
        {
            "key": "profile_id",
            "stringValue": "pr1234"
        },
        {
            "key": "last_action",
            "stringValue": "button_x_clicked"
        }
    ],
    "surfaces": [
        {
            "surface": "HOME_SCREEN", 
            "maximumTreatmentCount": 1        
        }        
    ],
    "languageCode": "vi"
}'

Response

{
    "responseId": "18c7c4b3-2093-494a-9996-94989abac914",
    "userTreatments": [
        {
            "treatmentId": "4",
            "treatmentTrackingId": "4_18c7c4b3-2093-494a-9996-94989abac914",
            "rank": "1",
            "treatmentContent": "... translated content ...",
            "treatmentType": "IN_APP_CONTENT_CARD",
            "surface": "HOME_SCREEN",
            "contentLanguageCode": "vi",            
        }
    ]
}

Non-translated

If a treatment is not translated into the language requested, then the treatment will not be returned.

Example

curl --location --request POST 'https://apis.auxia.io/v1/GetTreatments \
--header 'Content-Type: application/json' \
--header 'x-api-key: *********************' \
--data-raw '{
    "projectId": "1250",
    "userId": "gGTE8CWUIgpzPivCejVk7JN284V",
    "contextualAttributes": [
        {
            "key": "profile_id",
            "stringValue": "pr1234"
        },
        {
            "key": "last_action",
            "stringValue": "button_x_clicked"
        }
    ],
    "surfaces": [
        {
            "surface": "HOME_SCREEN",   
            "maximumTreatmentCount": 1                 
        }        
    ],
    "languageCode": "eo"
}' # The language code `eo` is not supported.

Response

{
    "responseId": "e9861c48-f8bf-42dd-a189-a471c35002ad"
}

​API Definition

​Path Parameters

​Headers

​Status Codes

​Raw request body

​Example curl

​Response

​Schema Reference

​Request

​Response

​userTreatments

​Appendix

​Language and translations

​Example

​Response

​Non-translated

​Example

​Response

API Definition

Path Parameters

Headers

Status Codes

Raw request body

Example curl

Response

Schema Reference

Request

Response

userTreatments

Appendix

Language and translations

Example

Response

Non-translated

Example

Response