Custom field definitions

Before you start

Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.

Path and query identifiers are UUID strings.

Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.

List custom field definitions

GET /api/v3/custom_field_definitions

Lists CRM custom field definitions. target_type must be one of Customer, Provider, Contact, Lead, Opportunity, or Assignment when present.

Parameter	Type	Description
target_type	string	Optional CRM target type filter.
active	boolean	Optional active filter.

Results are paginated. Pass page to move through pages of 50 records.

Response 200

[
  {
    "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
    "name": "Industry",
    "target_type": "Lead",
    "field_type": "string",
    "required": false,
    "active": true,
    "position": 1,
    "track_history": true,
    "options": [
      {
        "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
        "label": "SaaS",
        "active": true,
        "position": 1
      },
      {
        "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
        "label": "Retail",
        "active": true,
        "position": 2
      }
    ]
  }
]

Create a custom field definition

POST /api/v3/custom_field_definitions

On create, options is an array of option labels.

Request

{
  "name": "Industry",
  "target_type": "Lead",
  "field_type": "string",
  "required": false,
  "active": true,
  "position": 1,
  "track_history": true,
  "options": [
    "SaaS",
    "Retail"
  ]
}

Response 200

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Industry",
  "target_type": "Lead",
  "field_type": "string",
  "required": false,
  "active": true,
  "position": 1,
  "track_history": true,
  "options": [
    {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "label": "SaaS",
      "active": true,
      "position": 1
    },
    {
      "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
      "label": "Retail",
      "active": true,
      "position": 2
    }
  ]
}

Show a custom field definition

GET /api/v3/custom_field_definitions/{custom_field_definition_id}

Parameter	Type	Description
custom_field_definition_id	string (UUID)	Custom field definition id.

Response 200

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Industry",
  "target_type": "Lead",
  "field_type": "string",
  "required": false,
  "active": true,
  "position": 1,
  "track_history": true,
  "options": [
    {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "label": "SaaS",
      "active": true,
      "position": 1
    },
    {
      "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
      "label": "Retail",
      "active": true,
      "position": 2
    }
  ]
}

Update a custom field definition

PUT /api/v3/custom_field_definitions/{custom_field_definition_id}

target_type and field_type cannot be changed after create. On update, options is an array of objects with id, label, active, and position.

Request

{
  "name": "Industry updated",
  "required": true,
  "active": true,
  "position": 2,
  "track_history": false,
  "options": [
    {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "label": "SaaS",
      "active": true,
      "position": 1
    }
  ]
}

Response 200

{
  "id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Industry updated",
  "target_type": "Lead",
  "field_type": "string",
  "required": true,
  "active": true,
  "position": 2,
  "track_history": false,
  "options": [
    {
      "id": "2c2d2fd9-fe83-480a-adb8-351efc6a9808",
      "label": "SaaS",
      "active": true,
      "position": 1
    },
    {
      "id": "795c7a6e-cfb7-4883-bef8-2fb380de92c8",
      "label": "Retail",
      "active": true,
      "position": 2
    }
  ]
}

Delete a custom field definition

DELETE /api/v3/custom_field_definitions/{custom_field_definition_id}

Response 200

{}