Custom Fields Mapping

Custom Fields Mapping describes how custom fields seen by user (e.g. contact custom field "Role in organisation") are mapped to custom field objects in Search API backend (e.g. "contact:12345").

Custom Fields Mapping API returns list of all custom fields defined on account for given entity (lead/contact/deal), alongside with additional meta-information (custom field type, id to use within search API, user-provided name).

Endpoints

There is one mapping API endpoint for each entity type:

Endpoint Action Response payload Description
/v3/deals/custom_fields GET JSON Deal custom fields mapping
/v3/leads/custom_fields GET JSON Lead custom fields mapping
/v3/contacts/custom_fields GET JSON Contact custom fields mapping

Schema

Custom fields

CustomField type consists of following attributes:

Attribute Type Description
id string ID of this custom field in Sell backend systems
name string User-defined custom field name, e.g. "Role in organisation"
type string Type of this custom field, see custom field type in firehose section
resource_type string Type of entity this custom field is defined for, possible values are lead, deal and contact, prospect_and_customer
search_api_id string Search API attribute id to use with Search API to e.g. sort on this custom field
GET /v3/deals/custom_fieldsAuthorization: Bearer $TOKEN
{    "items": [        {            "data": {                "id": "12345",                "name": "Required delivery date",                "type": "date",                "resource_type": "deal",                "search_api_id": "custom_fields.12345"            },            "meta": {                "type": "custom_field"            }        },        {            "data": {                "id": "56789",                "name": "Internal department ID",                "type": "string",                "resource_type": "deal",                "search_api_id": "custom_fields.56789"            },            "meta": {                "type": "custom_field"            }        }    ],    "meta": {        "type": "collection",        "count": 2    }}

Use with Search API

Custom field IDs obtained through Mapping API may be used to query Search API

POST /v3/deals/searchAuthorization: Bearer $TOKEN
{  "items": [    {      "data": {        "per_page": 2,        "query": {          "projection": [            {              "name": "id"            },            {              "name": "custom_fields.56789"            }          ],          "sort": [            {              "attribute": {                "name": "custom_fields.155488"              },              "order": "ascending"            }          ]        }      }    }  ]}
{  "items": [    {      "successful": true,      "items": [        {          "data": {            "custom_fields": {              "56789": "marketing"            },            "id": 11111,            "version": 21          },          "meta": {            "type": "deal"          }        },        {          "data": {            "custom_fields": {              "56789": "public relations"            },            "id": 33333,            "version": 8          },          "meta": {            "type": "deal"          }        }      ],      "meta": {        "count": 2,        "http_status": "200 OK",        "links": {          "next_page": "neXTpAgeT0k3n=="        },        "total_count": 321,        "type": "collection"      }    }  ]}