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. Only title is required: type defaults to hidden when omitted, and ordernum is ignored on create because the new field is placed last. Without options or relations in the request, the response echoes the properties that were sent plus id, perstag, ordernum, cdate, udate, created_by and updated_by; with them, the complete field is read back with its options and relations and the fieldOptions and fieldRels side-loaded. The field is also added to the account's default field group unless group is sent.
- 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
}
}options or relations are malformed: more than 25 entries, an option without a value or with a duplicate value, a relation id that is not a whole number, or options sent for a type that cannot have them (type missing, or not dropdown, listbox, radio or checkbox).