Custom Fields

Define custom data fields for tickets, customers and articles. Supports text, number, date, select and checkbox types.

The Custom Field object

id string

Field ID

contentType string

Record type this field belongs to "ticket" | "customer" | "article"

label string

Display name

fieldType string

Input type "text" | "number" | "date" | "select" | "checkbox"

defaultValue string

Pre-filled value, or null

options string[]

Choices for select fields, or null

minValue number

Lower bound for number fields, or null

maxValue number

Upper bound for number fields, or null

required boolean

Whether the field is required

sortOrder integer

Display order within its type

createdAt datetime

When the field was created

Endpoints

GET List Custom Fields POST Create Custom Field

GET /api/v1/teams/{teamId}/custom-fields

List Custom Fields

List custom field definitions in display order.

Query Parameters

entity string

Only fields for this record type

Code Examples

bash

curl -X GET "https://www.cstar.help/api/v1/teams/{teamId}/custom-fields?entity=ticket" \
  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Custom fields

json

{
  "success": true,
  "data": [
    {
      "id": "cf_abc",
      "object": "custom_field",
      "contentType": "ticket",
      "label": "Region",
      "fieldType": "select",
      "defaultValue": null,
      "options": [
        "US",
        "EU",
        "APAC"
      ],
      "minValue": null,
      "maxValue": null,
      "required": false,
      "sortOrder": 0,
      "createdAt": "2026-10-01T12:00:00Z"
    }
  ]
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

POST /api/v1/teams/{teamId}/custom-fields

Create Custom Field

Create a new custom field definition at the end of its type.

Request Body

contentType string required

Record type

label string required

Display name

fieldType string

Input type

Default: text

options string[]

Choices for select fields

defaultValue string

Pre-filled value

minValue number

Lower bound for number fields

maxValue number

Upper bound for number fields

required boolean

Whether the field is required

Code Examples

bash

curl -X POST "https://www.cstar.help/api/v1/teams/{teamId}/custom-fields" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"contentType":"ticket","label":"Region","fieldType":"select","options":["US","EU","APAC"]}'

Responses

201 Field created

json

{
  "success": true,
  "data": {
    "id": "cf_abc",
    "object": "custom_field",
    "contentType": "ticket",
    "label": "Region",
    "fieldType": "select",
    "options": [
      "US",
      "EU",
      "APAC"
    ],
    "required": false,
    "sortOrder": 0
  }
}

401 Authentication failed: missing or invalid API key

json

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

403 Insufficient permissions: wrong key type or team access

json

{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

429 Rate limit exceeded

json

{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}