Submissions & Troubleshooting

Every request to an intake endpoint produces a submission. The response tells you what happened to it, and BytePhase keeps a log of it against the integration so you can look later.

The response

{
  "status": "completed",
  "request_id": "01K4R4Z2N7Q9X0F3M6C8V1B5D2",
  "data": { "id": 10421, "object": "lead", "…": "…" }
}

HTTP	status	Meaning	data
201	completed	A new lead or self check-in was created	The record
200	duplicate	Nothing new was created: either this Idempotency-Key was already processed, or the workspace’s duplicate rule matched an existing record	The existing record
202	received	The submission was accepted and stored, but not yet turned into a record, because the form it came from is not set up yet	null

data.object is "lead" or "self_checkin". Full field lists are in the reference.

received — parked, not lost

A 202 received happens when BytePhase cannot yet tell what to do with the submission:

• The form_id does not match any form configured on the integration, and the integration has more than one form (or none) so there is no single default.
• The form exists but is still a draft — its field map has not been activated.
• The provider posts its own field names (Typeform, JotForm, Tally.so) and the form has not been mapped yet.

The raw payload is stored. Open the integration in BytePhase, map the form (the detected fields from real submissions are offered to you), activate it, and retry the parked submissions from the log. They are then created as if they had just arrived. Nothing a visitor submitted is discarded.

Design your integration so a 202 is treated as success from the visitor’s point of view — it is a setup step for the shop, not an error the visitor can fix.

The submission log

In BytePhase, open Settings → Integrations, choose the integration, and look at its submissions. Each entry shows:

• when it arrived, from which IP address and user agent
• the form_id and destination
• the status: received, completed, duplicate or failed
• the HTTP status returned, and the error message for failures
• the request id — the same value as the request_id in the response and the X-Request-Id header
• what was sent and what it was mapped to
• a link to the lead or self check-in that was created

This is the first place to look when a lead is “missing”. The usual findings:

Symptom	Likely cause
Nothing in the log at all	The request never reached the workspace. Wrong base URL (412), wrong host, or your side never sent it. Check your own logs and Environments.
failed with a 422	A required field was missing after mapping — usually name, or neither mobile_number nor email. Fix the form or the field map, then retry.
received	The form is not mapped or not activated yet. Map it, then retry.
duplicate	Working as designed — a matching record already existed. Change the form’s duplicate rule if you want every submission to create a new record.
401 in your logs, nothing in BytePhase	The key was rejected before anything was logged. Check the key and the base URL.

Retry

Submissions in failed or received can be retried from the log after you fix the cause. A retry runs the stored payload through the pipeline again — with the form’s current field map and duplicate rule — and updates the entry. Completed submissions cannot be retried; they already produced a record.

Failed submissions are also worth retrying after a 500, once the cause on our side is resolved.

Duplicate rules

Each form on an integration has a duplicate setting:

• Skip — if a record matching the submission already exists, return it as duplicate instead of creating another. This is the default for leads (matched on mobile number + country code, or email).
• Create — always create a new record. This is the default for self check-ins.

Change it per form in the integration’s settings when the default is wrong for your use — for example a lead form where every submission should create a fresh lead even from a repeat customer.

What to send support

When something is not behaving, contact support with:

1. The request id (X-Request-Id header or request_id in the body). It lets us find the exact request in seconds.
2. The workspace name and the integration’s name (never the key itself).
3. The HTTP status and the error.code you received.
4. What you expected instead.

Never send the API key. If you think a key has leaked, rotate it in BytePhase first.