Create a custom field: Migration guide

This guide details how the Create a custom field endpoint has changed (previously known as createCustomField in v1).

💡

Key changes

• Terminology: The API v2 uses a different term for the custom field's target resource. Where you previously used collection, you'll now use targetType.
• Support for path sessions: The v2 endpoint introduces the ability to create custom fields for path sessions (pathSessions), in addition to users.
• Removal of restricted fields: The ability to create custom fields with a fixed list of authorized values (using isRestricted and authorizedValues in v1) is no longer supported.

Documentation links

Here are the links to the API reference for:

• API v1
• API v2

Endpoint mapping

Here's the direct correlation between the v1 and v2 endpoint URLs:

• API v1: /api/v1/customfields
• API v2: /api/v2/custom-fields

Behavior changes

The v2 endpoint no longer supports the creation of custom fields with a predefined list of authorized values. In v1, this was handled by the isRestricted and authorizedValues parameters. This functionality has been removed in v2.

Input changes

This section details the specific alterations to the input requirements between API versions.

API v1 input example

curl --location -g 'https://{{host}}/api/v1/customfields?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Country",
    "collection": "users",
    "isRestricted": true,
    "authorizedValues": ["Mayotte", "Finlandia", "Bulgaria"]
}'

API v2 input example

curl --request POST \
     --url https://app.360learning.com/api/v2/custom-fields \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer access_token' \
     --header 'content-type: application/json' \
     --data '
{
  "targetType": "users",
  "type": "string",
  "name": "Department"
}
'

Main input differences

Output changes

This section details the specific alterations to the successful output returned between API versions.

API v1 output example

{
    "_id": "68518fee0e2b8b742b072029",
    "status": "customField_created"
}

API v2 output example

{
  "_id": "68518fee0e2b8b742b072029",
  "name": "Department",
  "targetType": "users",
  "type": "string"
}

Main output differences

API v2 provides a more detailed success response and structured, specific error codes. On success, it returns the complete created custom field object instead of a simple status message.