Form Fields in /contacts/upsert

Learn how to correctly structure form fields (consents, level of support, presence status, custom fields, surveys, tasks) when syncing contacts.

Several fields in the contact object accept arrays of form objects. Each object requires the form id and a string value defined in your account settings.

The following field types follow this pattern:

Field	Description
consents	Forms related to consent and data collection
custom_fields	Custom fields associated with the contact
status	Level of support of the contact

1. Find your form IDs

   Each form type has its own endpoint. Call the relevant one to retrieve the IDs and accepted values for your account:

   Field	Endpoint
   consents	GET https://incoming.qomon.app/forms/consent
   custom_fields	GET https://incoming.qomon.app/forms/custom_fields
   status	GET https://incoming.qomon.app/forms/level_of_support

   For more information, look at the reference for /forms.

2. Correct payload structure

   Each form field follows the same shape: an array of objects with an id and a string value.

   If the form has a unique label, you can use the label instead of the id.

   {
     "kind": "contact",
     "data": {
       "firstname": "Jane",
       "surname": "Doe",
       "gender": "F",
       "mail": "[e-mail]",
       "address": {
         "postalcode": "12345"
       },
       "consents": [
         { "id": 1234, "value": "consent_email" },
         { "label": "General communication", "value": "consent_sms" }
       ],
       "custom_fields": [
         { "id": 4512, "value": "member" }
       ],
   	"status": [
   	  { "id": 9826, "value": "donator" }
   	]
     }
   }
   

Use the form id returned by the endpoint, not the form_ref_id.

The value field always expects a string — never a boolean or integer.

Every form field must be an array, even when setting a single value.