Creates a custom field definition for contacts. For dropdown, listbox, radio, and checkbox fields, create the options in the same request by adding an options array inside the field payload; list relationships can likewise be added as a relations array (relid 0 relates the field to every list). Each array is capped at 25 entries and the field plus its children are created in one transaction. Options can also be added later with POST /fieldOptions or POST /fieldOption/bulk. Fails with 400 when options are sideposted on a field type that cannot have options, and 422 when the title is already used by another field. The response side-loads the created options and relations.
- When the
field_typeisdropdown,radio,checkboxorlistbox, you need to add field options usingfieldOption/bulkendpoint. - A User can only see a custom field if the contact is part of a list that this custom field is related to. Use
fieldRelendpoint to specify which list gets to see the custom field. -
This endpoint creates a custom field, but does not populate it with options, if it requires them.
The dropdown, multiselect, radio, and checkbox custom fields need to be supplied with options. To learn more, see our Custom Objets Api Guide
Example POST Body
POST Body{
"field": {
"type": "textarea",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "Default Value",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "text",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "Default Value",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "date",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "2025-01-01",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "dropdown",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "listbox",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "radio",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "checkbox",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "hidden",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "Default Value",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "datetime",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "2025-05-19T02:45:00-05:00",
"visible": 1,
"ordernum": 1
}
}{
"field": {
"type": "number",
"title": "Field Title",
"descript": "Field description",
"perstag": "Personalized Tag",
"defval": "1234",
"visible": 1,
"ordernum": 1
}
}