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_fields
Authorization: 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/search
Authorization: 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"
      }
    }
  ]
}