Home/Insert DataField

Insert DataField

This document provides a guide and overview for the InsertDataField RPC, which allows you to register a DataField directly via API. Once registered, the DataField name can be used immediately as a contextual attribute key when calling GetTreatments, with no further setup.

API Definition

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

note

InsertDataField requires a Treatment Management API key, passed in the x-api-key header. A key without Treatment Management permissions is rejected with 403 PERMISSION_DENIED.

Entities

UserPropertyParams

message UserPropertyParams {
  // Required.
  // The data type of the user property.
  // Only BOOLEAN, STRING and INTEGER are supported. Any other value returns INVALID_ARGUMENT.
  DataFieldType data_type = 1;
}

enum DataFieldType {
  UNSPECIFIED_DATA_FIELD_TYPE = 0;
  INTEGER = 1;
  DOUBLE = 2;
  STRING = 3;
  BOOLEAN = 4;
  TIMESTAMP_SECONDS = 5;
  INTEGER_LIST = 6;
  DOUBLE_LIST = 7;
  STRING_LIST = 8;
}

DataFieldPb

message DataFieldPb {
  // Auxia-assigned identifier for the DataField. Stable across calls.
  string data_field_id = 1;

  // The project this DataField belongs to.
  string project_id = 2;

  // The DataField name.
  string name = 3;

  oneof source {
    UserPropertyParams user_property = 4;
  }
}

InsertDataField

API to register a DataField

message InsertDataFieldRequest {
  // Required.
  // Numeric project id.
  string project_id = 1;

  // Required.
  // Must be snake_case, matching ^[a-z](?:[a-z0-9_]*[a-z0-9])?$, with a maximum length of 256 characters.
  // This name is the key used as a contextual attribute in GetTreatments.
  string name = 2;

  // Required.
  // Exactly one source must be set.
  oneof source {
    UserPropertyParams user_property = 3;
  }
}

message InsertDataFieldResponse {
  // The registered DataField (or the pre-existing one, if it already existed).
  DataFieldPb data_field = 1;
}

tip

InsertDataField is idempotent on (project_id, name). Calling it again with the same project and name returns the existing data_field_id without creating a duplicate or returning an error.

Sample cURL Request

curl --location --request POST 'https://apis.auxia.io/v1/InsertDataField' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
  "projectId": "PROJECT_ID",
  "name": "loyalty_tier",
  "userProperty": {
    "dataType": "STRING"
  }
}'

Sample Response

{
  "dataField": {
    "dataFieldId": "8821",
    "projectId": "PROJECT_ID",
    "name": "loyalty_tier",
    "userProperty": {
      "dataType": "STRING"
    }
  }
}