Custom formats

A custom format is an incoming URL for a system that cannot send the Standard body. It takes the JSON that system already sends, for example a CRM, helpdesk, or survey webhook. It maps the payload's fields onto the Standard body and stores the response.

Each custom format has its own URL, field mapping, and Store payloads setting. A form can have up to 20 custom formats.

After mapping, the request goes through the same checks, idempotency, and error codes as Standard. A few extra codes cover mapping problems.

Create a format

The format card shows its URL, how many fields are mapped, and its Store payloads setting. From the card menu you can Edit details, Duplicate, Copy URL, or Delete the format. Use the pencil icon to edit the mapping.

Field mapping

Each mapping row fills one field of the Standard body. Add field lists every field you can fill:

A format has 1 to 100 rows, and each target can be mapped only once. Payload fields that are not mapped are ignored. status is completed unless you map it.

Row settings

Open a row's settings (the sliders icon) to choose where its value comes from and how it is converted.

When a path matches several values, they are collected into an array for multiple choice answers and lists. For any other field, several matches return path_matched_many.

Conversions

A value that cannot be converted returns conversion_failed.

Check a mapping

The editor has three panes under the sample. None of them stores a response.

• Preview: Preview with the sample runs the draft mapping in the API and shows whether the result is valid, or lists each problem with its code.
• Test: paste a body of your own and check it against the mapping in the editor, saved or not, with the same engine the API uses.
• Requests: ready-to-run curl commands for this format's submit and validate URLs, with the sample as the body. They use the saved mapping, not unsaved edits.

Endpoints

Both take any JSON body up to 100 KB, and both authenticate with an admin API key:

• Send the key in the X-Api-Key header when the sender lets you add headers.
• Otherwise, append ?X-Api-Key=YOUR_ADMIN_API_KEY to the URL. See Authentication for the trade-offs.
• Send an Idempotency-Key header, or map externalId from the payload's event id, so retries from the sender are de-duplicated.

The submit URL answers the same way as Submit Response, with 202 and a responseId. The validate URL answers the same way as Validate Response.

Example: a CRM NPS webhook

Say a CRM posts this payload after each NPS survey, and you cannot change it:

curl -X POST 'https://api.encatch.com/engage-product/encatch/api/v2/admin/forms/3f8a2c1e-7b4d-4e9a-9c61-2d5f8e0b7a14/formats/crm-nps-webhook/responses' \
  -H 'X-Api-Key: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "event_id": "evt_1001",
    "occurred_at": 1792393591,
    "contact": { "email": "jane.doe@example.com" },
    "survey": {
      "score": "9",
      "liked": "Delivery;Checkout",
      "comment": "Tracking updates could be more frequent."
    }
  }'

Create a format with the slug crm-nps-webhook and these rows:

The API turns the payload into this Standard body, then validates and stores it:

{
  "status": "completed",
  "externalId": "evt_1001",
  "submittedAt": "2026-10-19T07:06:31Z",
  "user": { "userName": "jane.doe@example.com" },
  "answers": {
    "how-likely-are-you-to-recommend-us": 9,
    "what-did-you-like-most": ["fast-delivery", "easy-checkout"],
    "anything-we-could-improve": "Tracking updates could be more frequent."
  }
}

Because externalId comes from event_id, a webhook retried within 1 hour with the same payload returns the same responseId instead of storing a second response. user.userName must belong to a user created with Identify User. Otherwise, leave that row out to store anonymous responses.

Errors

Custom formats return the same codes as Standard, plus these:

In invalidParams, name points at the rule's target field. The most common cause of question_not_in_form is publishing a new form version that removed or replaced a question. Re-open the format after publishing, and remap or remove the affected rows.

Related

• Response Submit API overview
• Submit Response
• Answer formats
• Error codes