Custom Fields & Forms

The Custom Fields API (v2) lets you define custom data fields and organize them into forms. Custom fields extend the default ticket and conversation schema with your own attributes.

List Custom Fields

cURL

curl "https://apps.aurionai.net/api/v2/custom-fields" \
  -H "X-API-Key: ak_live_xxxx"

Response:

{
  "data": [
    {
      "id": "cf_abc123",
      "name": "department",
      "label": "Department",
      "type": "dropdown",
      "required": true,
      "choices": ["Engineering", "Sales", "Marketing", "HR", "Finance"],
      "default_value": null,
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "total": 8,
  "limit": 25,
  "offset": 0
}

Create Custom Field

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "office_location",
    "label": "Office Location",
    "type": "dropdown",
    "required": false,
    "choices": ["Brussels", "Paris", "Amsterdam", "Berlin"]
  }'

Field Types:

Type	Description
`text`	Single-line text input
`textarea`	Multi-line text input
`number`	Numeric value
`dropdown`	Single select from choices
`multi_select`	Multiple select from choices
`checkbox`	Boolean true/false
`date`	Date picker
`url`	URL input
`cascading_dropdown`	Multi-level hierarchical dropdown

Update Custom Field

curl -X PATCH "https://apps.aurionai.net/api/v2/custom-fields/cf_abc123" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "choices": ["Engineering", "Sales", "Marketing", "HR", "Finance", "Legal"]
  }'

Delete Custom Field

curl -X DELETE "https://apps.aurionai.net/api/v2/custom-fields/cf_abc123" \
  -H "X-API-Key: ak_live_xxxx"

Returns 204 No Content on success. System fields cannot be deleted.

Validate Custom Attributes

Validate a set of custom attribute values against field definitions before submitting:

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/validate" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "ticket",
    "custom_attrs": {
      "department": "Engineering",
      "office_location": "Brussels"
    },
    "form_id": "form_abc"
  }'

Response:

{
  "valid": true,
  "errors": []
}

If validation fails, valid is false and errors contains the list of issues.

Cascading Dropdowns

For hierarchical data (e.g., Country → City → Office), use cascading dropdowns:

Get choice tree

curl "https://apps.aurionai.net/api/v2/custom-fields/cf_location/choices/tree" \
  -H "X-API-Key: ak_live_xxxx"

Update choice tree

curl -X PUT "https://apps.aurionai.net/api/v2/custom-fields/cf_location/choices/tree" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tree": [
      {
        "label": "Belgium",
        "children": [
          {"label": "Brussels"},
          {"label": "Antwerp"}
        ]
      },
      {
        "label": "France",
        "children": [
          {"label": "Paris"},
          {"label": "Lyon"}
        ]
      }
    ]
  }'

System Fields

List the built-in system fields (read-only):

curl "https://apps.aurionai.net/api/v2/custom-fields/system" \
  -H "X-API-Key: ak_live_xxxx"

Forms

Forms group custom fields into structured layouts. Each form can have multiple sections.

List Forms

curl "https://apps.aurionai.net/api/v2/custom-fields/forms" \
  -H "X-API-Key: ak_live_xxxx"

Create Form

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IT Support Request",
    "description": "Form for general IT support tickets",
    "fields": ["cf_department", "cf_office_location", "cf_asset_tag"]
  }'

Delete Form

curl -X DELETE "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc" \
  -H "X-API-Key: ak_live_xxxx"

Returns 204 No Content on success.

Publish Form

Forms must be published before they appear in the UI. Publishing creates a versioned snapshot:

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc/publish" \
  -H "X-API-Key: ak_live_xxxx"

Form Versions

List versions

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc/versions" \
  -H "X-API-Key: ak_live_xxxx"

Restore previous version

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc/versions/2/restore" \
  -H "X-API-Key: ak_live_xxxx"

Form Sections

Organize form fields into sections:

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc/sections" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Device Information",
    "fields": ["cf_asset_tag", "cf_device_type"],
    "order": 2
  }'

Get Form as JSON Schema

Export a form as a standard JSON Schema for use in external integrations:

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/form_abc/rendered-schema" \
  -H "X-API-Key: ak_live_xxxx"

Using Custom Fields in Tickets

Include custom field values when creating or updating tickets:

curl -X POST "https://apps.aurionai.net/api/v1/tickets" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "New laptop request",
    "priority": "medium",
    "custom_fields": {
      "department": "Engineering",
      "office_location": "Brussels"
    }
  }'

Tickets — Use custom fields when creating tickets
Conversations — Custom fields on conversations

Required Scopes

Scope	Endpoints
`config:read`	`GET /v2/custom-fields`, `GET /v2/custom-fields/system`, `GET /v2/custom-fields/forms`, `GET /v2/custom-fields/:id/choices/tree`, `POST /v2/custom-fields/validate`
`config:write`	`POST /v2/custom-fields`, `PATCH /v2/custom-fields/:id`, `DELETE /v2/custom-fields/:id`, `POST /v2/custom-fields/forms`, `PATCH /v2/custom-fields/forms/:id`, `DELETE /v2/custom-fields/forms/:id`, `POST /v2/custom-fields/forms/:id/publish`, `PUT /v2/custom-fields/:id/choices/tree`

Custom Fields & Forms

On this page