> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auxia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert DataField

> API for registering a DataField via API.

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

```url theme={null}
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`.
</Note>

## 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.
</Tip>

### 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"
    }
  }
}
```