Replace a user custom fields values: Migration guide

We've combined the addCustomFieldValueand removeCustomFieldValue endpoints from API v1 into a single, more efficient endpoint in API v2: Replace a user custom fields.

This guide outlines the key differences you'll encounter when moving to API v2:

• From addCustomFieldValue
• From removeCustomFieldValue

💡

Key changes

• Replace all behavior: The v2 endpoint works on a Replace All behavior, meaning every custom values for the target user will be replaced. Thus if you intend to update only one customer field value, you should:
  1. Retrieve the full list of this user's custom fields values by calling List all custom field values for a user
  2. Perform the change in custom fields values within the response (add or delete custom field value)
  3. Upload the full list of custom fields values again using this method.
• HTTP method: The v2 endpoint uses the PUT method, while v1 used the DELETE method for the removeCustomFieldValue method

addCustomFieldValue migration

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/:collection/:targetId/customfields
• API v2: /api/v2/users/{​userId​}/custom-fields/values

Behavior changes

Replace all behavior: The v2 endpoint works on a Replace All behavior, meaning every custom values for the target user will be replaced. Thus, if you intend to update only one customer field value, you should:

1. Retrieve the full list of this user's custom fields values by calling List all custom field values for a user
2. Perform the change in custom fields values within the response by adding the new custom field value in the array
3. Upload the full list of custom fields values again using this method.

Input changes

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

API v1 input example

curl --location -g --request PUT 'https/{{host}}/api/v1/users/5be2b954b44a1b6e3526e091/customfields?company={{company}}&apiKey={{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{
    "values": [
        {
            "customFieldId": "5be2b954b44a1b6e3526e091",
            "value": "custom_value_0"
        },
        {
            "customFieldId": "5be2b954b44a1b6e3526e092",
            "value": "custom_value_1"
        }
    ]
}'

API v2 input example

curl --request PUT \
     --url https://app.360learning.com/api/v2/users/userId/custom-fields/values \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customValues": [
    {
      "customFieldId": "507f1f77bcf86cd799439011",
      "type": "string",
      "value": "US"
    }
  ]
}
'

Main input differences

Output changes

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

API v1 output example

{
  "status": "custom_field_values_added"
}

API v2 output example

[
  {
    "customFieldId": "507f1f77bcf86cd799439011",
    "type": "string",
    "value": "US"
  }
]

Main output differences

removeCustomFieldValue migration

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/:customFieldId/:collectionName/:targetId
• API v2: /api/v2/users/{userId}/custom-fields/values

Behavior changes

Replace all behavior: The v2 endpoint works on a Replace All behavior, meaning every custom values for the target user will be replaced. Thus, if you intend to update only one customer field value, you should:

1. Retrieve the full list of this user's custom fields values by calling List all custom field values for a user
2. Perform the change in custom fields values within the response by removing the custom field value from the array
3. Upload the full list of custom fields values again using this method.

Input changes

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

API v1 input example

curl --location -g --request DELETE 'https://{{host}}/api/v1/customfields/5be2b954b44a1b6e3526e091/users/5be2b954b44a1b6e3526e091?company={{company}}&apiKey={{apiKey}}%0A' \
--header 'Content-Type: application/json'

API v2 input example

curl --request PUT \
     --url https://app.360learning.com/api/v2/users/userId/custom-fields/values \
     --header '360-api-version: v2.0' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customValues": [
    {
      "customFieldId": "507f1f77bcf86cd799439011",
      "type": "string",
      "value": "US"
    }
  ]
}
'

Main input differences

Output changes

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

API v1 output example

// No response body

API v2 output example

[
  {
    "customFieldId": "507f1f77bcf86cd799439011",
    "type": "string",
    "value": "US"
  }
]

Main output differences