Skip to navigation

Create Contact Custom Field Definition

Creates a contact custom field definition. The caller must have permission to create custom fields.

Send Content-Type: application/json. Supply only label, field_type, and the fields required for that type. Do not supply IDs, URIs, timestamps, source, question_uuid, or custom_field. Option objects accept only label. Unknown fields are rejected.

Leading and trailing whitespace is removed from the field label. The result must contain 1 to 255 characters. Currency codes are not case-sensitive and are converted to uppercase. Options keep their request order. Duplicate nonblank option labels are allowed. The server assigns option UUIDs. Each response option includes color, which is null when no color is set.

Invalid fields return 400. A field label that already exists returns 409. Field-name checks ignore case. If City exists, creating city returns 409. The default rate limit applies.

Example validation error:

{"title":"Invalid Argument","message":"The supplied parameters are invalid.","details":[{"parameter":"options","message":"Supply 1 to 10 label-only options for a single_select field."}]}

Example duplicate-label error:

{"title":"Already Exists","message":"The resource already exists","details":[{"parameter":"label","message":"A custom field with this label already exists."}]}

Note: Requires CRM on your plan.

Required scopes

contacts:write

Authentication

AuthorizationBearer
OAuth 2.0
OR
AuthorizationBearer
Personal Access Token

Request

This endpoint expects an object.
labelstringRequiredformat: "^\s*\S(?:[\s\S]{0,253}\S)?\s*$"
Display name. Leading and trailing whitespace is removed. The result must contain 1 to 255 characters.
field_typeenumRequired

Field type. Supported values:

  • text: A text value.
  • number: A numeric value.
  • currency: A monetary amount in the specified currency. Send currency with this value.
  • tags: A list of text labels.
  • date: A calendar date.
  • single_select: One value from the field’s configured options. Send options with this value.

System-generated invitee_question fields cannot be created.

currencystringOptionalformat: "^([Uu][Ss][Dd]|[Ee][Uu][Rr]|[Gg][Bb][Pp]|[Jj][Pp][Yy]|[Cc][Hh][Ff]|[Cc][Aa][Dd]|[Aa][Uu][Dd]|[Cc][Nn][Yy]|[Ss][Gg][Dd]|[Ii][Nn][Rr]|[Kk][Rr][Ww])$"

Required only for currency fields. Supported codes are USD, EUR, GBP, JPY, CHF, CAD, AUD, CNY, SGD, INR, and KRW. Codes are not case-sensitive. The response uses uppercase. Other field types reject this field.

optionslist of objectsOptional

Required only for single_select fields. Supply 1 to 10 label-only objects in display order. Duplicate labels are allowed. The server assigns option UUIDs. Other field types reject this field.

Response headers

LocationstringOptionalformat: "uri"
Canonical URI of the created custom field definition.

Response

Created
resourceobject
A custom field definition describes the schema for a field that can be applied to Contacts.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error