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:

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

Change type	API v1	API v2
Removed Body parameter	`isRestricted` (Optional): Removed from endpoint v2 version, not replaced.	-
Removed Body parameter	`authorizedValues` (Optional): Removed from endpoint v2 version, not replaced.	-
Modified Path segment name	`customfields`	`custom-fields`
Modified Body parameter	`collection` (Required): Specifies the resource type. Only accepted value: `users`.	`targetType`(Required): Renamed from `collection`. Now accepts: `users` or `pathSessions` as values.
Modified Body parameter	`type` (Optional): The type of custom field. Accepted values: `string` and `date`.	`type`(Required): This parameter is now mandatory. Still accepts `string` and `date`.

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.

Change type	API v1	API v2
Removed Output property	`status`: A string indicating the result of the operation. Removed from endpoint v2 version, not replaced.	-
Modified Success output	`200 OK`: Returns a success message with an `_id` and a `status`.	`201 Created`: Returns a `201` status code and the full JSON object of the created custom field.
Added Output property	-	`name`: The name of the custom field.
Added Output property	-	`targetType`: The resource type to which the custom field is linked.
Added Output property	-	`type`: The type of the custom field.

💡Key changes