Custom Fields & Forms

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

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

Custom fields are scoped to an entity type — one of conversation, contact, or company. There is no ticket entity type; ticket-style data lives on the conversation entity.

List Custom Fields

cURL

curl "https://apps.aurionai.net/api/v2/custom-fields?entity_type=conversation" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query parameters: entity_type (optional — one of conversation, contact, company), field_category (optional), include_archived (default false), limit (optional, 1–500), offset (default 0).

Response — a top-level JSON array of field definitions (no pagination envelope):

[
  {
    "id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "entity_type": "conversation",
    "field_key": "department",
    "label": "Department",
    "field_type": "select",
    "field_category": "custom",
    "required": true,
    "choices": ["Engineering", "Sales", "Marketing", "HR", "Finance"],
    "options": null,
    "default_value": null,
    "placeholder": null,
    "help_text": null,
    "validation": {},
    "visible_in": ["inbox", "form", "widget"],
    "sort_order": 0,
    "status": "active",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-01T10:00:00Z"
  }
]

Get a Custom Field

curl "https://apps.aurionai.net/api/v2/custom-fields/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns the single field definition shown above, or 404 {"detail": "Custom field not found"}.

Create Custom Field

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

entity_type, field_key, label, and field_type are required. Creating a field with field_category: "system" returns 403 {"detail": "Cannot create system fields via API"}. A duplicate field_key for the same entity returns 409.

Field Types (field_type):

Type	Description
`text`	Single-line text input
`paragraph`	Multi-line text input
`number`	Integer value
`decimal`	Decimal value
`boolean`	Boolean true/false
`date`	Date picker
`select`	Single select from choices
`multiselect`	Multiple select from choices
`url`	URL input
`lookup`	Reference to another record
`content`	Static content block (no input)
`cascading_dropdown`	Multi-level hierarchical dropdown
`file_upload`	File attachment

A POST/PATCH with any other value returns 422 {"detail": "Invalid field_type '...'. Allowed: [...]"}.

Update Custom Field

curl -X PATCH "https://apps.aurionai.net/api/v2/custom-fields/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "choices": ["Engineering", "Sales", "Marketing", "HR", "Finance", "Legal"]
  }'

System fields cannot change field_key, field_type, entity_type, or field_category — attempting to do so returns 403. An unknown id returns 404.

Delete Custom Field

curl -X DELETE "https://apps.aurionai.net/api/v2/custom-fields/8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content on success. Deleting a system field returns 403; an unknown id returns 404 {"detail": "Custom field not found"}.

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: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "conversation",
    "custom_attrs": {
      "department": "Engineering",
      "office_location": "Brussels"
    },
    "form_id": "f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f"
  }'

entity_type must be one of conversation, contact, or company (anything else returns 422). Optional fields: context and prior_custom_attrs (pass the record's prior custom_attrs when validating an edit so previously-absent required fields are grandfathered).

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 a cascading_dropdown field. The choice tree is a nested dict keyed by label (max depth 3), not an array of objects:

Get choice tree

curl "https://apps.aurionai.net/api/v2/custom-fields/c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071/choices/tree" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "field_id": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071",
  "choices": {
    "Belgium": { "Brussels": {}, "Antwerp": {} },
    "France": { "Paris": {}, "Lyon": {} }
  }
}

The PUT body is the nested-dict tree sent directly (no tree wrapper key):

Update choice tree

curl -X PUT "https://apps.aurionai.net/api/v2/custom-fields/c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071/choices/tree" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Belgium": { "Brussels": {}, "Antwerp": {} },
    "France": { "Paris": {}, "Lyon": {} }
  }'

Returns the updated {field_id, choices}. A tree exceeding depth 3 returns 422; a field that does not exist or is not a cascading type returns 404.

System Fields

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

curl "https://apps.aurionai.net/api/v2/custom-fields/system?entity_type=conversation" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a top-level JSON array of field definitions (same shape as List Custom Fields) with field_category: "system".

Forms

Forms group custom fields into structured layouts. Each form belongs to an entity type and can have multiple sections. Like fields, forms are scoped to conversation, contact, or company.

List Forms

curl "https://apps.aurionai.net/api/v2/custom-fields/forms?entity_type=conversation" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a top-level JSON array of forms (no pagination envelope).

Get a Form

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns the single form, or 404 {"detail": "Custom form not found"}.

Create Form

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

name and entity_type are required. Field membership and ordering are expressed via field_order (a list of field ids). Optional: schema, ui_schema, is_default, metadata, status.

Update Form

curl -X PATCH "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "field_order": ["cf_department", "cf_office_location"]
  }'

The purpose field (agent or portal) may only be set on forms with entity_type: "conversation" — otherwise 422. An unknown id returns 404.

Delete Form

curl -X DELETE "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f" \
  -H "X-API-Key: itsm_sk_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/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/publish" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns the new form version ({id, form_id, version, schema, ui_schema, field_order, conditional_rules, ...}). Publishing a form with dangling field references returns 422; an unknown id returns 404.

Form Versions

List versions

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/versions" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns a top-level JSON array of versions.

Roll back to a previous version

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/versions/2/rollback" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Form Sections

Organize a form's fields into sections.

List sections

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/sections" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Create section

curl -X POST "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/sections" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Device Information",
    "field_ids": ["cf_asset_tag", "cf_device_type"],
    "sort_order": 2
  }'

Sections use field_ids (list of field ids) and sort_order. Optional: description, trigger_field_id, trigger_values (for conditional sections), collapsed_by_default, status.

Update section

curl -X PATCH "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/sections/a3b4c5d6-7e8f-9012-3a4b-5c6d7e8f9012" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Device & Asset Details" }'

Delete section

curl -X DELETE "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/sections/a3b4c5d6-7e8f-9012-3a4b-5c6d7e8f9012" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content. An unknown section returns 404 {"detail": "Form section not found"}.

Reorder sections

curl -X PUT "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/sections/reorder" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "section_ids": [
      "a3b4c5d6-7e8f-9012-3a4b-5c6d7e8f9012",
      "b4c5d6e7-8f90-1234-5a6b-7c8d9e0f1234"
    ]
  }'

The body is {"section_ids": [...]} listing every section id in the desired order; the response is the reordered list of sections.

Form Rules

Fetch the enabled conditional (business) rules for a form, in the client-evaluator shape used by the New Conversation modal. Only available for entity_type: "conversation" forms:

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/rules" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{ "rules": [] }

A form that is not a conversation form returns 404 {"detail": "Form not found"}.

Get Form as JSON Schema

Export a form as a standard JSON Schema for use in external integrations or for rendering a specific context:

curl "https://apps.aurionai.net/api/v2/custom-fields/forms/f2c3d4e5-6a7b-8c9d-0e1f-2a3b4c5d6e7f/rendered-schema?context=customer&locale=fr" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Optional query parameters:

context — one of agent, customer, voice, closure. Tailors which fields, labels, and required flags appear. An invalid value returns 400.
locale — visitor locale (e.g. fr, fr-FR). Only applied for the customer and voice contexts; ignored for agent/closure.

The response is {schema, ui_schema, form_id, entity_type, version}.

Using Custom Fields in Conversations

Custom field values are carried on the helpdesk's conversation entity (via the validate / form-builder flow above), not on the public v1 ticket-create endpoint. The public POST /api/v1/tickets body accepts only subject, description, status, priority, requester_email, and metadata — there is no custom_fields field, and description is required:

curl -X POST "https://apps.aurionai.net/api/v1/tickets" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "New laptop request",
    "description": "Requesting a replacement laptop for the engineering team.",
    "priority": "medium",
    "metadata": {
      "department": "Engineering",
      "office_location": "Brussels"
    }
  }'

Unlike the rest of this page, POST /api/v1/tickets is reachable with an API key (it requires the tickets:write scope). Stash structured values in metadata; an unknown custom_fields key is silently dropped.

Tickets — Create tickets via the public v1 API
Conversations — The conversation entity custom fields attach to

Authentication & Roles

These v2 custom-field endpoints are not reachable with an API key (see the preview banner above) — they are authenticated by a dashboard session JWT and gated by tenant role:

Operation	Allowed roles
Read (list/get fields, forms, sections, versions, rules, validate, choices tree GET, rendered-schema, system)	`super_admin`, `tenant_owner`, `tenant_admin`, `agent`, `supervisor`, `tenant_user`, `tenant_readonly`
Write (create/update/delete fields & forms, create/update/delete/reorder sections, publish, rollback, choices tree PUT)	`super_admin`, `tenant_owner`, `tenant_admin`

Custom Fields & Forms

On this page