Custom fields and their groups

In this section we will describe all available methods for Custom fields and their groups.

Table of Contents

Common information

  • Custom fields can be added to leads, contacts, companies, lists, segments, and customers
  • Method URL depends on the entity

Custom fields list

Method

GET /api/v4/leads/custom_fields

GET /api/v4/contacts/custom_fields

GET /api/v4/companies/custom_fields

GET /api/v4/customers/custom_fields

GET /api/v4/customers/segments/custom_fields

GET /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to get a list of custom fields in the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
422 Request can not be processed. Details are available in the request response
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of custom field models. The properties of the custom field model are listed below. Model properties differ depending on the entity.

Parameter Data type Description
id int Field ID
name string Field name
code string Field code that can be used to update the value of the field without passing the field ID in the request
sort int Field sorting
type int Field type. The list of the available types
entity_type string Entity type (leads, contacts, companies, segments, customers, catalogs)
is_predefined bool Defines whether the field is predefined. This parameter is returned only when getting a contact or company fields list
is_deletable bool Defines whether the field is deletable. This parameter is returned only when getting a contact or company fields list
is_visible bool Defines whether the field is displayed in the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_deletable bool Defines whether the field is deletable from the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_required bool Defines whether the field is mandatory when creating a list element. This parameter is returned only when getting a list of lists (catalogs) fields
settings array|null Field settings. This parameter is returned only when getting a list of lists (catalog) fields.
remind string|null Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event). This value is available only for the birthday type field. This parameter is returned only when getting a list of lead, contact, or company fields, сделок и компаний
enums array|null Available field values array. Only available for the fields with enum values
enums[0] object Available field value model
enums[0][id] int Value ID
enums[0][value] string Value
enums[0][sort] int Value sorting
nested array|null Nested values array. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0] object Nested value model. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][id] int Nested value ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][parent_id] int Nested value parent ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][value] string The value of the nested value. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][sort] int Nested value sorting. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
is_api_only bool Defines whether the field is editable via API only. This parameter is returned only when getting a lead, contact, or company fields list
group_id string|null Fields group ID for the current field. This parameter is returned only when getting a lead, contact, company, or customer fields list
required_statuses array|null Array of the fields required to change a lead status. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0] object Required field model. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0][status_id] int ID of the stage which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company fields list
required_statuses[0][pipeline_id] int ID of the pipeline which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company fields list

Response example

        
{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 10,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/custom_fields?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.com/api/v4/leads/custom_fields?limit=2&page=2"
        },
        "last": {
            "href": "https://example.amocrm.com/api/v4/leads/custom_fields?limit=2&page=10"
        }
    },
    "_embedded": {
        "custom_fields": [
            {
                "id": 4439091,
                "name": "Text field example",
                "sort": 504,
                "type": "text",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": [
                    {
                        "status_id": 41221,
                        "pipeline_id": 3142
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/custom_fields/4439091/"
                    }
                }
            },
            {
                "id": 4440043,
                "name": "Example 'date' type field",
                "sort": 505,
                "type": "date",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": null,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/custom_fields/4440043/"
                    }
                }
            }
        ]
    }
}
        
    

Getting an entity field by its ID

Method

GET /api/v4/leads/custom_fields/{id}

GET /api/v4/contacts/custom_fields/{id}

GET /api/v4/companies/custom_fields/{id}

GET /api/v4/customers/custom_fields/{id}

GET /api/v4/customers/segments/custom_fields/{id}

GET /api/v4/catalogs/{catalog_id}/custom_fields/{id}

Description

This method allows to get a particular custom field data by its ID.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
422 Request can not be processed. Details are available in the request response
401 User is not authorized

Response parameters

Method returns a custom field model. The properties of the custom field model are listed below. Model properties differ depending on the entity.

Parameter Data type Description
id int Field ID
name string Field name
code string Field code that can be used to update the value of the field without passing the field ID in the request
sort int Field sorting
type int Field type. The list of the available types
entity_type string Entity type (leads, contacts, companies, segments, customers, catalogs)
is_predefined bool Defines whether the field is predefined. This parameter is returned only when getting a contact or company field
is_deletable bool Defines whether the field is deletable. This parameter is returned only when getting a contact or company field
is_visible bool Defines whether the field is displayed in the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_deletable bool Defines whether the field is deletable from the list interface. This parameter is returned only when getting a list of lists (catalogs) fields
is_required bool Defines whether the field is mandatory when creating a list element. This parameter is returned only when getting a list of lists (catalogs) fields
settings array|null Field settings. This parameter is returned only when getting a list (catalog) field.
remind string|int Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event). This value is available only for the birthday type field. This parameter is returned only when getting a lead, contact, or company field
enums array|null Available field values array. Only available for the fields with enum values
enums[0] object Available field value model
enums[0][id] int Value ID
enums[0][value] string Value
enums[0][sort] int Value sorting
is_api_only bool Defines whether the field is editable via API only. This parameter is returned only when getting a lead, contact, or company field
group_id string|null Fields group ID for the current field. This parameter is returned only when getting a lead, contact, company, or customer field
required_statuses array|null Array of the fields required to change a lead status. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0] object Required field model. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0][status_id] int ID of the stage which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company field
required_statuses[0][pipeline_id] int ID of the pipeline which requires the current field to have a value before the lead can be moved. This parameter is returned only when getting a lead, contact, or company field
nested array|null Nested values array. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0] object Nested value model. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][id] int Nested value ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][parent_id] int Nested value parent ID. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][value] string The value of the nested value. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field
nested[0][sort] int Nested value sorting. This parameter is returned only when getting the list of catalog fields. The value is avalable only for the category type field

Response example

        
{
    "id": 3,
    "name": "Phone",
    "type": "multitext",
    "account_id": 28805383,
    "code": "PHONE",
    "sort": 4,
    "is_api_only": false,
    "enums": [
        {
            "id": 1,
            "value": "WORK",
            "sort": 2
        },
        {
            "id": 3,
            "value": "WORKDD",
            "sort": 4
        },
        {
            "id": 5,
            "value": "MOB",
            "sort": 6
        },
        {
            "id": 7,
            "value": "FAX",
            "sort": 8
        },
        {
            "id": 9,
            "value": "HOME",
            "sort": 10
        },
        {
            "id": 11,
            "value": "OTHER",
            "sort": 12
        }
    ],
    "group_id": null,
    "required_statuses": [],
    "is_deletable": false,
    "is_predefined": true,
    "entity_type": "contacts",
    "remind": null,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/contacts/custom_fields/3"
        }
    }
}
        
    

Adding custom fields

Method

POST /api/v4/leads/custom_fields

POST /api/v4/contacts/custom_fields

POST /api/v4/companies/custom_fields

POST /api/v4/customers/custom_fields

POST /api/v4/customers/segments/custom_fields

POST /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to add singular or multiple custom fields to an entity.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To add a custom field, the field model should be passed.

Parameter Data type Description Is the field mandatory Supported field types
type string Field type. The list of the available types Available for all field types
name string Field name Available for all field types
code string Field code that can be used to update the value of the field without passing the field ID in the request Available for all field types
sort int Field sorting in the field group Available for all field types
group_id string Field group ID Available for all lead, contact, company, and customer fields
is_api_only bool Defines whether the field is editable via API only Available for all lead, contact, and company fields
required_statuses array|null Array of the fields required to change a lead status Available for all lead, contact, company, and customer fields
required_statuses[0] object Required field model Available for all lead, contact, company, and customer fields
required_statuses[0][status_id] int ID of the stage which requires the current field to have a value before the lead can be moved Available for all lead, contact, company, and customer fields
required_statuses[0][pipeline_id] int ID of the pipeline which requires the current field to have a value before the lead can be moved Available for all lead, contact, company, and customer fields
settings object Field settings Available for all lists (catalogs) fields
is_visible bool Defines whether the field is displayed in the list interface Available for all lists (catalogs) fields
is_required bool Defines whether the field is mandatory when creating a list element Available for all lists (catalogs) fields
remind string|null Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event) Available only for the birthday type fields
enums array Available field values array Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0] object Available field value model Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0][value] string Value Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0][sort] string Value sorting Available for the following field types:
  • multiselect
  • radiobutton
  • select
nested array Nested values array Available for the following field types:
  • category
nested[0] object Nested value model Available for the following field types:
  • category
nested[0][id] int Nested value ID Available for the following field types:
  • category
nested[0][parent_id] int Nested value parent ID Available for the following field types:
  • category
nested[0][value] string The value of the nested value Available for the following field types:
  • category
nested[0][sort] int Nested value sorting Available for the following field types:
  • category
nested[0][request_id] string Temporary identifier of a nested value. Identifier should be unique for the request, isn’t saved anywhere, and is used to create more than one nesting level within one request Available for the following field types:
  • category
nested[0][parent_request_id] string Temporary identifier of a nested value parent. Identifier is used only at the time of the request, isn’t saved anywhere, and defines the nesting level of the added element if the parent element hasn’t been created yet Available for the following field types:
  • category

An example of the request

        
[
    {
        "name": "multi select",
        "type": "multiselect",
        "sort": 510,
        "required_statuses": [
            {
                "pipeline_id": 16056,
                "status_id": 20540473
            }
        ],
        "enums": [
            {
                "value": "Value 1",
                "sort": 1
            },
            {
                "value": "Value 2",
                "sort": 2
            }
        ]
    }
]
        
    

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
201 Request successful
422 Request can not be processed. Details are available in the request response
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created fields’ models. The parameters are similar to the custom fields list request parameters

Response example

        
{
    "_total_items": 1,
    "_embedded": {
        "custom_fields": [
            {
                "name": "multi select",
                "type": "multiselect",
                "sort": 510,
                "settings": null,
                "is_predefined": false,
                "id": 4457223,
                "remind": null,
                "is_api_only": false,
                "enums": [
                    {
                        "value": "Value 1",
                        "sort": 1,
                        "id": 3778801
                    },
                    {
                        "value": "Value 2",
                        "sort": 2,
                        "id": 3778803
                    }
                ],
                "group_id": null,
                "required_statuses": [
                    {
                        "status_id": 20540473,
                        "pipeline_id": 16056
                    },
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/custom_fields/4457223/"
                    }
                }
            }
        ]
    }
}
        
    

Updating custom fields

Method

PATCH /api/v4/leads/custom_fields

PATCH /api/v4/contacts/custom_fields

PATCH /api/v4/companies/custom_fields

PATCH /api/v4/customers/custom_fields

PATCH /api/v4/customers/segments/custom_fields

PATCH /api/v4/catalogs/{catalog_id}/custom_fields

Description

This method allows to update singular or multiple custom fields of an entity.
To update a singular custom field, you can add the field ID into the method URL (/api/v4/leads/custom_fields/{id}).
When updating multiple custom fields, an array of field objects is passed. In the case with a singular custom field, the field model is passed.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To update a custom field, the field model should be passed.

Parameter Data type Description Is the field mandatory Supported field types
name string Field name Available for all field types
code string Field code that can be used to update the value of the field without passing the field ID in the request Available for all field types
sort int Field sorting in the field group Available for all field types
group_id string Field group ID Available for all lead, contact, company, and customer fields
is_api_only bool Defines whether the field is editable via API only Available for all lead, contact, and company fields
required_statuses array|null Array of the fields required to change a lead status Available for all lead, contact, company, and customer fields
required_statuses[0] object Required field model Available for all lead, contact, company, and customer fields
required_statuses[0][status_id] int ID of the stage which requires the current field to have a value before the lead can be moved Available for all lead, contact, company, and customer fields
required_statuses[0][pipeline_id] int ID of the pipeline which requires the current field to have a value before the lead can be moved Available for all lead, contact, company, and customer fields
settings object Field settings Available for all lists (catalogs) fields
is_visible bool Defines whether the field is displayed in the list interface Available for all lists (catalogs) fields
is_required bool Defines whether the field is mandatory when creating a list element Available for all lists (catalogs) fields
remind string|null Birthday reminders setting (never, day – day before the event, week – week before the event, month – month before the event) Available only for the birthday type fields
enums array Available field values array Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0] object Available field value model Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0][value] string Value Available for the following field types:
  • multiselect
  • radiobutton
  • select
enums[0][sort] string Value sorting Available for the following field types:
  • multiselect
  • radiobutton
  • select
nested array Nested values array Available for the following field types:
  • category
nested[0] object Nested value model Available for the following field types:
  • category
nested[0][id] int Nested value ID. Shouldn’t be passed when creating a new value Available for the following field types:
  • category
nested[0][parent_id] int Nested value parent ID Available for the following field types:
  • category
nested[0][value] string The value of the nested value Available for the following field types:
  • category
nested[0][sort] int Nested value sorting Available for the following field types:
  • category
nested[0][request_id] string Temporary identifier of a nested value. Identifier should be unique for the request, isn’t saved anywhere, and is used to create more than one nesting level within one request Available for the following field types:
  • category
nested[0][parent_request_id] string Temporary identifier of a nested value parent. Identifier is used only at the time of the request, isn’t saved anywhere, and defines the nesting level of the added element if the parent element hasn’t been created yet Available for the following field types:
  • category

An example of the request

In the following example we’ll update 2 catalog fields using the method /api/v4/catalogs/{catalog_id}/custom_fields.

        
[
    {
        "id": 1278898087,
        "name": "New custom field name",
        "sort": 560,
        "is_visible": false,
        "is_required": true
    },
    {
        "id": 1278898091,
        "name": "New Category field name",
        "nested": [
            {
                "id": 197,
                "parent_id": null,
                "value": "category 1",
                "sort": 0
            },
            {
                "parent_id": null,
                "value": "new category 2",
                "sort": 1
            },
            {
                "parent_id": 197,
                "value": "new subcategory 1",
                "sort": 1
            }
        ]
    }
]
        
    

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
201 Request successful
422 Request can not be processed. Details are available in the request response
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of updated fields’ models. The parameters are similar to the custom fields list request parameters.

Response example

        
{
    "_total_items": 2,
    "_embedded": {
        "custom_fields": [
            {
                "id": 1278898087,
                "name": "New custom field name",
                "type": "textarea",
                "account_id": 17079858,
                "code": "DESCRIPTION",
                "sort": 560,
                "is_api_only": false,
                "enums": null,
                "request_id": "0",
                "catalog_id": 1095,
                "is_visible": false,
                "is_deletable": true,
                "is_required": false,
                "nested": null,
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/catalogs/1095/custom_fields/1278898087"
                    }
                }
            },
            {
                "id": 1278898091,
                "name": "New Category field name",
                "type": "category",
                "account_id": 17079858,
                "code": "GROUP",
                "sort": 500,
                "is_api_only": false,
                "enums": null,
                "request_id": "1",
                "catalog_id": 1095,
                "is_visible": true,
                "is_deletable": false,
                "is_required": false,
                "nested": [
                    {
                        "id": 197,
                        "parent_id": null,
                        "value": "category 1",
                        "sort": 0
                    },
                    {
                        "id": 215,
                        "parent_id": 197,
                        "value": "new subcategory 1",
                        "sort": 0
                    },
                    {
                        "id": 217,
                        "parent_id": 197,
                        "value": "new category 2",
                        "sort": 1
                    }
                ],
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/catalogs/1095/custom_fields/1278898091"
                    }
                }
            }
        ]
    }
}
        
    

Deleting a custom field

Method

DELETE /api/v4/leads/custom_fields/{id}

DELETE /api/v4/contacts/custom_fields/{id}

DELETE /api/v4/companies/custom_fields/{id}

DELETE /api/v4/customers/custom_fields/{id}

DELETE /api/v4/customers/segments/custom_fields/{id}

DELETE /api/v4/catalogs/{catalog_id}/custom_fields/{id}

Description

This method allows to delete a custom field of an entity on the account.

Limitations

  • Method is available for administrator users only.
  • Custom field values will be deleted.

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 The field has been successfully deleted
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body.

Custom field groups list

Method

GET /api/v4/leads/custom_fields/groups

GET /api/v4/contacts/custom_fields/groups

GET /api/v4/companies/custom_fields/groups

GET /api/v4/customers/custom_fields/groups

Description

This method allows to get a list of custom field groups in the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of custom field group models. The properties of the custom field group model are listed below.

Parameter Data type Description
id string Field group ID
name string Field group name
sort int Field group sorting within the entity card
entity_type string Entity type (leads, contacts, companies, customers)
is_predefined bool Defines whether the field group is predefined. Such groups can’t be deleted
type string Field group type (linked_group – product groups, custom_field_group – field groups)

Response example

        
{
    "id": "leads_29741591099841",
    "name": "Field group",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 3,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/leads_29741591099841"
        }
    }
}
        
    

Getting the field group of an entity by the group ID

Method

GET /api/v4/leads/custom_fields/groups/{id}

GET /api/v4/contacts/custom_fields/groups/{id}

GET /api/v4/companies/custom_fields/groups/{id}

GET /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to get the field group of an entity on the account.

Limitations

Method is available for all account users.

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 Request successful
404 The field group wasn’t found
401 User is not authorized

Response parameters

Method returns a custom field group model. The properties of the custom field group model are listed below.

Parameter Data type Description
id string Field group ID
name string Field group name
sort int Field group sorting within the entity card
entity_type string Entity type (leads, contacts, companies, customers)
is_predefined bool Defines whether the field group is predefined. Such groups can’t be deleted
type string Field group type (linked_group – product groups, custom_field_group – field groups)

Response example

        
{
    "_total_items": 4,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "default",
                "name": "Default",
                "is_predefined": true,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/default"
                    }
                }
            },
            {
                "id": "4521",
                "name": "Products",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/4521"
                    }
                }
            },
            {
                "id": "statistic",
                "name": "Stats",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 2,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/statistic"
                    }
                }
            },
            {
                "id": "leads_29741591099841",
                "name": "Field group",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 3,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/leads_29741591099841"
                    }
                }
            }
        ]
    }
}
        
    

Adding field groups

Method

POST /api/v4/leads/custom_fields/groups

POST /api/v4/contacts/custom_fields/groups

POST /api/v4/companies/custom_fields/groups

POST /api/v4/customers/custom_fields/groups

Description

This method allows to add multiple or singular field groups into the account.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

Parameter Data type Description
name string Field group name. This parameter is mandatory
sort int Field group sorting. This parameter is mandatory
request_id string Field that will be returned unchanged in the response and will not be saved. This parameter is not mandatory

An example of the request

        
[
    {
        "name": "group 1",
        "sort": 4
    },
    {
        "name": "group 2",
        "sort": 5
    }
]
        
    

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
201 The field groups have been successfully added
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns a collection of created field group models. The parameters are similar to the custom field groups list request parameters.

Response example

        
{
    "_total_items": 2,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "leads_2745158",
                "name": "group 1",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 4,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/leads_2745158/"
                    }
                }
            },
            {
                "id": "leads_609315",
                "name": "group 2",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 5,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/leads_609315/"
                    }
                }
            }
        ]
    }
}
        
    

Editing custom field group

Method

PATCH /api/v4/leads/custom_fields/groups/{id}

PATCH /api/v4/contacts/custom_fields/groups/{id}

PATCH /api/v4/companies/custom_fields/groups/{id}

PATCH /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to edit a particular custom field group by the group ID.

Limitations

Method is available for administrator users only.

Request header

Content-Type: application/json

Request parameters

To edit a field group, at least one parameter should be passed

Parameter Data type Description
name string Group name
sort int Group sorting

An example of the request

        
{
    "sort": 6
}
        
    

Data type header when the request is successful

Content-Type: application/hal+json

Data type header in case of an error

Content-Type: application/problem+json

HTTP response codes.

Response code Case
200 The field group has been successfully edited
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method returns the edited field group model. The parameters are similar to the custom field groups list request parameters.

Response example

        
{
    "id": "leads_2745",
    "name": "group 1",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 6,
    "_links": {
        "self": {
            "href": "https://example.amocrm.com/api/v4/leads/custom_fields/groups/leads_2745/"
        }
    }
}
        
    

Deleting a custom field group

Method

DELETE /api/v4/leads/custom_fields/groups/{id}

DELETE /api/v4/contacts/custom_fields/groups/{id}

DELETE /api/v4/companies/custom_fields/groups/{id}

DELETE /api/v4/customers/custom_fields/groups/{id}

Description

This method allows to delete a custom field group of an entity on the account.

Limitations

  • Method is available for administrator users only.
  • Predefined groups can\’t be deleted.

Request header

Content-Type: application/json

HTTP response codes.

Response code Case
204 The field group has been successfully deleted
404 The field group wasn’t found
403 Insufficient rights to call this method
401 User is not authorized
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body.

Available field types

Available custom field types

Type Name
text Text
numeric Number
checkbox Checkbox
select List
multiselect Multiselect list
date Date
url URL
textarea Text area
radiobutton Switch
streetaddress Short address
smart_address Address
birthday Birthday
legal_entity Tax ID
date_time Date and time
price Price
category Category
items Products

Custom field types availability table for different entities

Field type Contact Lead Company Customer Catalog Segment
Text
Number
Checkbox
List
Multiselect list
Multitext
Date
URL
Date and time
Text area
Switch
Short address
Address
Birthday
Tax ID
Price
Category
Products

Examples of custom fields of different types fill-in via API

Below, we’ll review examples of adding values to custom fields of different types.

All values are passed within objects of the custom_fields_values array, regardless of the field type. To fill a custom field, the field ID or field code as well as values shoud be passed.

Parameter Data type Description
custom_fields_values array An array that contains information about custom field values we want to set for an entity
custom_fields_values[0] object An object that contains information about the custom field value we want to set for an entity
custom_fields_values[0][field_id] int The ID of the field we want to fill in
custom_fields_values[0][field_code] string The code of the field we want to fill in
custom_fields_values[0][values] array An array of values we add
custom_fields_values[0][values][0] object Field value object. The object’s structure depends on the field type

Field types:

text, numeric, textarea, price, streetaddress

In the following example we’ll review the request to fill in text, numeric, textarea, price, and streetaddress type fields.

Parameter Data type Description
value string Field value
        
    ...
    "custom_fields_values": [
        {
            "field_id": 3,
            "values": [
                {
                    "value": "Field value"
                }
            ]
        },
        {
            "field_id": 103,
            "values": [
                {
                    "value": "1.5"
                }
            ]
        },
        {
            "field_id": 203,
            "values": [
                {
                    "value": "String1\nString2"
                }
            ]
        },
        {
            "field_id": 303,
            "values": [
                {
                    "value": "100"
                }
            ]
        },
        {
            "field_id": 403,
            "values": [
                {
                    "value": "222 Columbus Ave Ste 407, San Francisco, CA, 94133-5809"
                }
            ]
        }
    ],
    ...
        
    

checkbox

In the following example we’ll review the request to fill in a checkbox type field.

Parameter Data type Description
value bool Field value
        
    ...
    "custom_fields_values": [
        {
            "field_id": 5,
            "values": [
                {
                    "value": true
                }
            ]
        }
    ],
    ...
        
    

url

In the following example we’ll review the request to fill in a url type field.

Parameter Data type Description
value string Field value. Delegated URL
        
    ...
    "custom_fields_values": [
        {
            "field_id": 7,
            "values": [
                {
                    "value": "https://www.amocrm.com/"
                }
            ]
        }
    ],
    ...
        
    

date, date_time, birthday

In the following example we’ll review the request to fill in date, date_time, and birthday type fields.

Parameter Data type Description
value int Field value – Unix Timestamp
        
    ...
    "custom_fields_values": [
        {
            "field_id": 9,
            "values": [
                {
                    "value": 1577836800
                }
            ]
        },
        {
            "field_id": 109,
            "values": [
                {
                    "value": 1591965296
                }
            ]
        },
        {
            "field_id": 209,
            "values": [
                {
                    "value": 1586476800
                }
            ]
        }
    ],
    ...
        
    

select, multiselect, radiobutton, category

In the following example we’ll review the request to fill in select, multiselect, radiobutton, and category type fields. The value itself or value ID can be passed.

Parameter Data type Description
value string Field value
enum_id int Field value ID (enum).
        
    ...
    "custom_fields_values": [
        {
            "field_id": 11,
            "values": [
                {
                    "value": "Value 1"
                }
            ]
        },
        {
            "field_id": 111,
            "values": [
                {
                    "enum_id": 17
                },
                {
                    "enum_id": 19
                }
            ]
        },
        {
            "field_id": 211,
            "values": [
                {
                    "value": "Value 4"
                }
            ]
        }
    ],
    ...
        
    

smart_address

In the following example we’ll review the request to fill in a smart_address type field. This field takes multiple values. Parameters value and enum_id or enum_code should be passed.

Parameter Data type Description
value string Field value
enum_id int Field value ID. Available values: 1 – First address line, 2 – Second address line, 3 – City, 4 – State, 5 – Zip code, 6 – Country
enum_code string Field value code. Available values: address_line_1 – First address line, address_line_2 – Second address line, city – City, state – State, zip – Zip code, country – Country
        
    ...
    "custom_fields_values": [
        {
            "field_id": 13,
            "values": [
                {
                    "value": "222 Columbus Ave Ste 407",
                    "enum_id": 1
                },
                {
                    "value": "San Francisco",
                    "enum_code": "city"
                },
                {
                    "value": "CA",
                    "enum_code": "state"
                },
                {
                    "value": "94133-5809",
                    "enum_id": 5
                },
                {
                    "value": "USA",
                    "enum_code": "country"
                }
            ]
        }
    ],
    ...
        
    

multitext

In the following example we’ll review the request to fill in a multitext (Phone, Email) type field. This field takes multiple values. Parameters value and enum_id or enum_code should be passed.

Parameter Data type Description
value string Field value
enum_id int Field value ID
enum_code string Field value code
Available values for the Phone field: WORK – work phone number, WORKDD – direct work phone number, MOB – mobile, FAX – fax, HOME – home phone number, OTHER.
Available values for the Email fieeld: WORK – work email address, PRIV – private email address, OTHER.
        
    ...
    "custom_fields_values": [
        {
            "field_id": 31,
            "values": [
                {
                    "value": "+15551234567",
                    "enum_id": 48224
                },
                {
                    "value": "+14151234567",
                    "enum_code": "HOME"
                }
            ]
        }
    ],
    ...
        
    

legal_entity

In the following example we’ll review the request to fill in a legal_entity type field. Parameters name, vat_id, and kpp should be passed.

Parameter Data type Description
value object Field value
value[name] string Organization name
value[entity_type] int Legal entity type. 1 – Private, 2 – Legal.
value[vat_id] string Organization’s EIN
value[tax_registration_reason_code] string Primary State Registration Number
value[address] string Organization’s address
value[kpp] string Tax Registration Reason Code
value[external_uid] string External system identifier
        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "name": "Acme Co.",
                        "entity_type": 1,
                        "vat_id": "123123123",
                        "tax_registration_reason_code": 213,
                        "address": "San Francisco",
                        "kpp": "23123123",
                        "external_uid": "uuid"
                    }
                }
            ]
        }
    ],
    ...
        
    

items

In the following example we’ll review the request to fill in an items type field. Field is available in the invoice list.

Parameter Data type Description
value object Field value
value[sku] string Product SKU
value[description] string Product description
value[unit_price] int|float Product unit price
value[quantity] int|float Product quantity in the invoice
value[unit_type] string Product unit type
value[discount] object Product discount
value[discount][type] string Discount type (percentage, amount)
value[discount][value] int|float Discount value
value[vat_rate_id] int Tax rate ID (0 – without VAT, 1 – 10%, 2 – 10/110, 3 – 18%, 4 – 18/118, 5 – 0)
value[external_uid] string External system identifier
        
    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "sku": "34N4124",
                        "description": "Product description",
                        "unit_price": 10,
                        "quantity": 2,
                        "unit_type": "pc.",
                        "discount": {
                            "type": "amount",
                            "value": 25
                        },
                        "vat_rate_id": 18,
                        "external_uid": "uid"
                    }
                }
            ]
        }
    ],
    ...