Skip to main content
Custom fields let each workspace capture information specific to its sales process that is not part of the Vendaze standard schema: tax IDs, lead sources, market segments, internal scores, or any other relevant data. Each field belongs to the workspace, has a fixed type, and can be displayed on people, companies, and/or deals based on its visibility configuration.

​
Correct usage flow

Using custom fields safely follows a specific order that prevents type mismatches and data inconsistencies. 1. Create the field in the workspace Before associating values with any record, the field must exist with the correct type configured. Use POST /v1/custom-fields for this. 2. Associate values on records Once the field exists, pass custom_fields in the body of POST or PATCH requests on people, companies, or deals, referencing the field by its key.

​
Why you should create the field first

When you send an unknown field_key through the people, companies, or deals routes, the API automatically creates the field with type: text. This may seem convenient, but it creates a real problem: if the field was meant to be select, date, number, or any other type, it will have been created with the wrong type. Fixing it later requires a separate update call and can produce inconsistencies in values already stored. Always create the field with the correct type before writing values.

​
Create a custom field

POST /v1/custom-fields
Required fields: label, key, and type. 
{
  "label": "Lead Source",
  "key": "lead_source",
  "type": "select",
  "value": {
    "select_list": [
      { "key": "sl_referral", "option": "Referral" },
      { "key": "sl_inbound", "option": "Inbound" },
      { "key": "sl_event", "option": "Event" }
    ]
  },
  "show_people": true,
  "show_companies": false,
  "show_deals": true
}
Creation rules:
  • key is immutable after creation. Use stable, descriptive identifiers such as lead_source or company_tax_id.
  • type is also immutable. Choose the correct type before creating the field.
  • For select and multi_select, the value.select_list field is required and defines the available options.
  • The show_people, show_companies, and show_deals flags control which entities display the field. The default is true for people and companies, false for deals.

​
Available types

TypeDescription
textSingle line of text
long_textMulti-line text
numberInteger or decimal numeric value
dateDate in YYYY-MM-DD format
selectOne option from a predefined list
multi_selectMultiple options from a predefined list
cpfBrazilian individual tax ID
cnpjBrazilian company tax ID
linkFull URL
addressPhysical address structured into subfields

​
Associate values with records

With the field created, include custom_fields in the request body when creating or updating a record. Each item requires field_key and value. 
POST /v1/people

{
  "full_name": "Ana Costa",
  "emails": [{ "email": "ana@acme.com", "type": "work" }],
  "custom_fields": [
    { "field_key": "lead_source", "value": "sl_referral" },
    { "field_key": "score", "value": 85 }
  ]
}
The API resolves field_key to the field’s internal ID. If no field with that key exists in the workspace, it is created automatically with type: text. See the section above on why this should be avoided.

​
Association mode

The association_mode parameter controls the behavior when updating a record via PATCH:
  • append (default): sets or replaces the value for each field_key sent, without affecting other fields already associated with the record.
  • replace: removes all custom field values from the record and inserts only the ones sent in this request.

​
Value format reference by type

​
text

Plain string, single line. 
{ "field_key": "internal_role", "value": "Sales Manager" }

​
long_text

String with line breaks represented as \n. 
{ "field_key": "notes", "value": "Preferred customer.\nContact by email only." }

​
number

JSON number without quotes. Accepts integers or decimals. 
{ "field_key": "employee_count", "value": 120 }

{ "field_key": "internal_score", "value": 7.5 }

​
date

String in YYYY-MM-DD format, without time. 
{ "field_key": "contract_date", "value": "2026-08-15" }

​
select

Key of a single option from the field’s predefined list. To retrieve available keys, use GET /v1/custom-fields/:id and inspect value.select_list. 
{ "field_key": "segment", "value": "sl_technology" }
Sending a key that does not exist in the list returns a validation error.

​
multi_select

JSON array of selected option keys. 
{ "field_key": "products_of_interest", "value": ["sl_basic_plan", "sl_advanced_plan"] }
To select a single option, pass an array with one element. To clear all selections, pass an empty array. 
{ "field_key": "products_of_interest", "value": [] }

​
cpf

String with or without punctuation. 
{ "field_key": "responsible_cpf", "value": "123.456.789-09" }

​
cnpj

String with or without punctuation. 
{ "field_key": "company_cnpj", "value": "12.345.678/0001-90" }
Full URL with protocol. 
{ "field_key": "linkedin", "value": "https://linkedin.com/in/ana-costa" }

​
address

JSON object with the subfields below. All are optional: send only the ones available. Subfields not sent are stored as an empty string.
SubfieldDescription
address_line_1Street address and number
address_line_2Complement (suite, floor, unit)
cityCity
regionState or region
postal_codeZIP or postal code
countryCountry
{
  "field_key": "headquarters_address",
  "value": {
    "address_line_1": "1000 Market Street",
    "address_line_2": "Suite 42",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94103",
    "country": "United States"
  }
}

​
Read values on a record

When retrieving a record by ID, associated values are returned in the custom_fields array with the field object embedded: 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Ana Costa",
    "custom_fields": [
      {
        "id": "cf-assoc-uuid",
        "value": "sl_referral",
        "field": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "label": "Lead Source",
          "key": "lead_source",
          "type": "select"
        }
      }
    ]
  }
}

​
Full example

The example below creates a person with fields of every type, assuming each field was already created via POST /v1/custom-fields. 
POST /v1/people

{
  "full_name": "Ana Costa",
  "emails": [{ "email": "ana@acme.com", "type": "work" }],
  "custom_fields": [
    { "field_key": "responsible_cpf",      "value": "123.456.789-09" },
    { "field_key": "company_cnpj",         "value": "12.345.678/0001-90" },
    { "field_key": "segment",              "value": "sl_technology" },
    { "field_key": "products_of_interest", "value": ["sl_basic_plan", "sl_advanced_plan"] },
    { "field_key": "employee_count",       "value": 120 },
    { "field_key": "contract_date",        "value": "2026-08-15" },
    { "field_key": "linkedin",             "value": "https://linkedin.com/in/ana-costa" },
    { "field_key": "notes",                "value": "Referred by Acme partner." },
    {
      "field_key": "headquarters_address",
      "value": {
        "address_line_1": "1000 Market Street",
        "address_line_2": "Suite 42",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94103",
        "country": "United States"
      }
    }
  ]
}