Set custom field values

Request to set or clear the values of the custom fields of a call:

PUT /api/v2/calls/<call-id>.json

Custom field values are the only attributes of a call that can be changed through the REST API.

Prerequisites

1. The role of the API user has the Edit action of the Call custom fields permission (call_custom_fields resource).
2. The custom field is configured as Editable by the administrator. See Custom fields.
3. The custom field is enabled for the tenant of the call.

Update a custom field by ID

The request body lists the custom fields to update, identified by field_id:

{
    "call": {
        "custom_fields": [
            {
                "field_id": "138fb20c-4c3b-11ee-8cbb-0015172d2a7d",
                "value": "Unknown"
            },
            {
                "field_id": "9079d60a-5192-11ee-aa89-0015172d2a7d",
                "value": "Sales call"
            }
        ]
    }
}

Update a custom field by name

Alternatively, identify the custom field by its name:

{
    "call": {
        "custom_fields": [
            {
                "name": "Payment status",
                "value": "Unknown"
            },
            {
                "name": "Call type",
                "value": "Sales call"
            }
        ]
    }
}

If both field_id and name are supplied, name is ignored.

Clear a custom field value

Only the custom fields listed in the request are updated. Custom fields of the call that are not listed keep their values. To remove a value, set it to null or an empty string:

{
    "call": {
        "custom_fields": [
            {
                "field_id": "138fb20c-4c3b-11ee-8cbb-0015172d2a7d",
                "value": null
            }
        ]
    }
}

Value format

Values are submitted as strings, whatever the type of the field. The value is validated against the field type:

• Text: any text up to the field length.
• Number: an integer within the configured minimum and maximum.
• Date: a date in the format YYYY-MM-DD.
• Dropdown: one of the configured choices.

Response contains HTTP status code as shown in the following table.

Response	Description
200 OK	The call has been successfully updated. The response body contains the complete call object after the update, in the same format as View one call
400 Bad Request	The request cannot be completed because the supplied JSON object has invalid data: an unknown field, a value that does not match the field type, or a field that is disabled or read-only. The response contains a detailed description of the error, like: {"error": "InvalidRecord", "explanation": "Record Validation errors", "details": {"custom_fields.0.value": "Cannot modify a read-only field"}}
403 Forbidden	The request cannot be completed because API user has no permission to edit custom fields of calls
404 Not Found	Call with such ID does not exist, or it is outside the access scope of the API user