Get DataFields - Auxia Docs

Returns the ID and type of each DataField that matches the parameters you send. Use the returned dataFieldId to reference a DataField, for example in a treatment’s eligibility rules.

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

Requires a Treatment Management API key in the x-api-key header. Read-only and safe to retry.

Request body

Field	Type	Description
`projectId`	string	Required. Your Auxia project ID.
`dataFieldParams`	array of DataFieldParams	Required. The DataFields to look up. Must contain at least one item.

DataFieldParams

Each item describes one DataField. Set exactly one of these fields:

Field	Type	Description
`userAttributeDataFieldParams`	object	A user attribute. See User attribute.
`treatmentDataFieldParams`	object	A count or timestamp of treatment interactions. See Treatment interaction.
`eventDataFieldParams`	object	A count or timestamp of events. See Event.

User attribute

Field	Type	Description
`propertyName`	string	Required. The name of the user attribute, for example `loyalty_tier`.

Treatment interaction

Field	Type	Description
`treatmentInteractionType`	enum	Required. One of `SENT`, `VIEWED`, `CLICKED`, `SNOOZED`, `DISMISSED`, `CTA_COMPLETED`, `SWIPE`.
`treatmentId`, `surfaceId`, `surfaceName`, `treatmentTypeId`	string	Optional. Set at most one to count interactions for that treatment, surface or treatment type only. If none is set, interactions with every treatment in the project are counted.
One aggregation	object	Required. Set exactly one.
`isDistinctInteraction`	boolean	Optional. If `true`, each user is counted once. Only valid with `dailyCountAggregation`. Defaults to `false`.

Event

Field	Type	Description
`eventSchemaName`	string	Required. The event name, for example `Stream Finished`.
`propertyValueByPropertyName`	map	Optional. Counts only events whose properties have these values. Each value sets one of `longValue`, `doubleValue`, `stringValue`, `booleanValue`, `timestampValue`.
One aggregation	object	Required. Set exactly one.

Aggregations

Field	Description
`dailyCountAggregation`	The number of occurrences in a rolling window. `windowName` is required: one of `LAST_1D`, `LAST_7D`, `LAST_14D`, `LAST_28D`, `LAST_56D`. An item without it matches no DataField.
`firstTimestampAggregation`	The time of the first occurrence. Send an empty object, `{}`.
`latestTimestampAggregation`	The time of the most recent occurrence. Send `{}`.
`daysSinceFirstTimestampAggregation`	The number of days since the first occurrence. Send `{}`.
`daysSinceLastTimestampAggregation`	The number of days since the most recent occurrence. Send `{}`.

Response

Field	Type	Description
`dataFields`	array of objects	One entry per item in `dataFieldParams`, in the same order.

Each entry in dataFields:

Field	Type	Description
`dataFieldId`	string	The DataField ID. A 64-bit integer, returned as a string.
`dataFieldType`	string	One of `INTEGER`, `DOUBLE`, `STRING`, `BOOLEAN`, `TIMESTAMP_SECONDS`, `INTEGER_LIST`, `DOUBLE_LIST`, `STRING_LIST`.
`dataFieldParams`	object	The item from your request that this entry matched, unchanged.

Example

Request

curl --request POST 'https://apis.auxia.io/v1/GetDataFields' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: API_KEY' \
  --data '{
    "projectId": "PROJECT_ID",
    "dataFieldParams": [
      {
        "userAttributeDataFieldParams": {
          "propertyName": "loyalty_tier"
        }
      },
      {
        "treatmentDataFieldParams": {
          "treatmentInteractionType": "VIEWED",
          "surfaceName": "HOME_SCREEN",
          "dailyCountAggregation": { "windowName": "LAST_7D" }
        }
      }
    ]
  }'

Response (200)

{
  "dataFields": [
    {
      "dataFieldId": "8821",
      "dataFieldParams": {
        "userAttributeDataFieldParams": { "propertyName": "loyalty_tier" }
      },
      "dataFieldType": "STRING"
    },
    {
      "dataFieldId": "8822",
      "dataFieldParams": {
        "treatmentDataFieldParams": {
          "treatmentInteractionType": "VIEWED",
          "surfaceName": "HOME_SCREEN",
          "dailyCountAggregation": { "windowName": "LAST_7D" }
        }
      },
      "dataFieldType": "INTEGER"
    }
  ]
}

Errors

Errors use the standard error response. Handle them by HTTP status, not by message.

Status	When
400	`projectId` is not a number, `dataFieldParams` is empty, an item sets none of the three parameter types, a required field is missing, or `isDistinctInteraction` is set without `dailyCountAggregation`.
403	The API key is missing or invalid, or is not a Treatment Management key for this project.
404	At least one item in `dataFieldParams` matches no DataField in the project, or matches more than one. For example, a user attribute that has not been registered yet, or a `surfaceName` that does not exist.

A 404 fails the whole request. No DataFields are returned, including the ones that exist, and message names only the first item that did not match. To get the DataFields that exist and a list of the items that do not, set allowMissing (below).

Partial results with `allowMissing`

Set allowMissing to true to get the DataFields that exist even when some items do not match, and a list of the items that did not.

Field	Type	Description
`allowMissing` (request)	boolean	Optional. Defaults to `false`. If `true`, items that match no DataField are returned in `missing` instead of failing the request with `404`.
`missing` (response)	array of DataFieldParams	The items from `dataFieldParams` that matched no DataField, as sent. Only returned when `allowMissing` is `true`.

With allowMissing set to true:

The response is 200, even when some or all items do not match.
dataFields contains only the items that matched. Match each entry to your request by its dataFieldParams, not by position.
An item that matches more than one DataField still fails the request with 404.
400 and 403 errors are unchanged.

Request body

{
  "projectId": "PROJECT_ID",
  "allowMissing": true,
  "dataFieldParams": [
    { "userAttributeDataFieldParams": { "propertyName": "loyalty_tier" } },
    { "userAttributeDataFieldParams": { "propertyName": "spring_campaign_list" } }
  ]
}

Response (200)

{
  "dataFields": [
    {
      "dataFieldId": "8821",
      "dataFieldParams": {
        "userAttributeDataFieldParams": { "propertyName": "loyalty_tier" }
      },
      "dataFieldType": "STRING"
    }
  ],
  "missing": [
    { "userAttributeDataFieldParams": { "propertyName": "spring_campaign_list" } }
  ]
}

​Request body

​DataFieldParams

​User attribute

​Treatment interaction

​Event

​Aggregations

​Response

​Example

​Errors

​Partial results with allowMissing

Request body

DataFieldParams

User attribute

Treatment interaction

Event

Aggregations

Response

Example

Errors

Partial results with `allowMissing`