Skip to main content

Custom Fields

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

The Custom Field object

id string

Field ID

name string

Display name

key string

Machine-readable key

type string

Field type "text" | "number" | "select" | "multiselect" | "date" | "boolean"

entityType string

Which entity this field belongs to "tickets" | "customers"

required boolean

Whether the field is required

options string[]

Options for select/multiselect fields

position integer

Display order

Endpoints

GET List Custom FieldsPOST Create Custom Field
GET /api/v1/teams/{teamId}/custom-fields

List Custom Fields

List all custom field definitions.

Query Parameters

entityType string

Filter by entity type

Code Examples

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

Responses

200 Custom fields
{
  "success": true,
  "data": [
    {
      "id": "cf_abc",
      "name": "Priority Level",
      "key": "priority_level",
      "type": "select",
      "entityType": "tickets",
      "options": [
        "P0",
        "P1",
        "P2"
      ]
    }
  ]
}
401 Authentication failed — missing or invalid API key
{
  "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
{
  "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
{
  "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.

Request Body

name string required

Display name

key string required

Machine-readable key

type string required

Field type

entityType string required

Entity type

options string[]

Options for select types

Code Examples

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 '{"name":"Region","key":"region","type":"select","entityType":"tickets","options":["US","EU","APAC"]}'

Responses

201 Field created
{
  "success": true,
  "data": {
    "id": "cf_abc",
    "name": "Region",
    "key": "region",
    "type": "select"
  }
}
401 Authentication failed — missing or invalid API key
{
  "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
{
  "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
{
  "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"
  }
}