How to Connect n8n to BytePhase (Automation Setup Guide)

Send data from any n8n workflow into BytePhase and turn it into a Lead or a Self Check-in — no dedicated BytePhase node required. n8n talks to BytePhase through its built-in HTTP Request node, POSTing a small JSON envelope to a single BytePhase endpoint with an API key in the header. This guide covers generating that key, building the request body, and a worked example workflow you can copy: a Webhook trigger, a Set node to rename fields, and an HTTP Request node to send them on. It takes about 10 minutes if you already have a workflow that receives form or event data.

What You’ll Need

What the n8n Integration Does

BytePhase has no n8n-specific backend code — n8n is wired in the same way any custom REST caller is, by POSTing a canonical JSON envelope to BytePhase’s /integrations/submit endpoint. The envelope has three parts: a form_id you choose (any string, useful for filtering in the Activity log), a destination (lead or self_checkin), and a data object with the canonical field names from the mapping reference below. Pick lead for enquiries your team follows up, and self_checkin for device drop-offs a customer reports themselves — matched by mobile number, and converted into a repair job with one click once the device is actually in your hands. BytePhase never creates a job or ticket automatically from either destination.

How the n8n Integration Works

Step 1: Open the n8n Card in BytePhase

Log into BytePhase and go to Settings → Integrations. Under Website & Forms you’ll find an n8n card. Click Connect to start the setup wizard.

Step 2: Choose Where Submissions Land

The wizard opens on Destination, and it comes first because everything after it depends on the answer — the field map you review later belongs to the destination you pick here. Choose Self Check-in if the workflow should open a job for a device that is coming in, or Lead if it should raise an enquiry for your team to follow up. Your workflow then sends the matching value in the destination field of the JSON body. You are not choosing once and for all — see running both side by side below.

Step 3: Copy Your Endpoint URL and API Key

The wizard’s Connect step gives you two things: the submit endpoint —

https://<tenant>.api.bytephase.com/api/<tenant-slug>/integrations/submit

— and an API key, shown once, that you send as an X-API-Key header rather than in the URL. Copy both now; if you lose the key you’ll need to rotate it and update your workflow.

Step 4: Build the HTTP Request Node

In your n8n workflow, add an HTTP Request node (n8n’s own reference for this node: n8n HTTP Request node documentation) and configure it:

• Method: POST
• URL: the endpoint from Step 3
• Headers: X-API-Key: YOUR_KEY, Content-Type: application/json
• Body: JSON, matching the envelope shape below

Example request body, sending a repair enquiry as a Lead:

{
  "form_id": "n8n-website-contact-form",
  "destination": "lead",
  "data": {
    "name": "Jordan Lee",
    "email": "jordan@example.com",
    "mobile_number": "+14155550101",
    "device_type": "Laptop",
    "device_brand": "Dell",
    "comment": "Cracked screen, need a quote"
  }
}

Store the API key in n8n’s credentials manager rather than typing it directly into the node — that keeps it out of any exported workflow JSON.

Step 5: Send a Test Submission and Map Your Fields

Execute the workflow once (or trigger it manually with test data) so BytePhase receives a real request. Back in the wizard, click Check now — it also polls automatically every few seconds. Because you control the field names in the data object, the source keys BytePhase detects are whatever you sent; if you already used the canonical names from the mapping table, the wizard’s auto-match should line most of them up immediately. Confirm at least one of email or mobile is mapped, then continue. Anything you don’t map is preserved as a custom field rather than dropped.

Step 6: Set the Duplicate Policy and Activate

Choose how repeat submissions are handled. The defaults are sensible starting points — Lead defaults to skip a repeat submission (matched by email OR mobile + country code); Self Check-in defaults to create a new record even for a returning customer (matched by mobile against any check-in still open). Review the summary screen and click Activate integration. Nothing goes live until you do.

Run Self Check-in and Lead Side by Side

You do not have to pick one for the whole account. A single integration can serve several forms at once, and each one carries its own destination and its own field map. BytePhase keys every entry by form and destination together, and the destination pinned in the URL is absolute — a Self Check-in URL will never fall through to a Lead entry or borrow its field mapping.

So one workflow can open a Self Check-in while another raises a Lead, from the same n8n instance, running in parallel. Add the second form in the wizard, choose the other destination, and give it its own URL. The Activity log records which destination each submission was routed to, so the two never blur together.

A Worked Example Workflow

A simple, reliable pattern for pulling in submissions from any source:

1. Webhook node — receives the raw payload from your form, chatbot, spreadsheet automation, or whatever’s upstream
2. Set node — renames the incoming fields to BytePhase’s canonical names (e.g. rename full_name to name, phone to mobile_number) and assembles the form_id/destination/data shape
3. HTTP Request node — POSTs the assembled body to /integrations/submit with the X-API-Key header from Step 3

Retry safety: n8n’s built-in retry-on-fail can resend the same request if a node times out. Add an Idempotency-Key header to the HTTP Request node with a value unique to that submission (a form response ID works well) — BytePhase deduplicates on it, so a retried request never creates a second Lead or Self Check-in. Without it, BytePhase falls back to a payload-hash check for the same day, which is a reasonable safety net but a real idempotency key is more precise.

Field Mapping Reference

Testing & Monitoring Your Submissions

Every request — successful, duplicate, failed, or simply received — shows up on the integration’s Activity screen, with both the raw JSON your workflow sent and the mapped version BytePhase saved. Use Send test to fire a synthetic submission without running your live workflow, and the one-click Retry action to replay anything that failed once you’ve fixed the cause. Three failures in a row trigger a warning banner in the app; five in a row also email your tenant’s support address. Submission logs are kept for 90 days. Note that BytePhase processes each request synchronously and returns the result immediately — there’s no queue in between, so your HTTP Request node’s response reflects the real outcome right away.

Troubleshooting

Security

Your API key is sha256-hashed at rest — BytePhase can verify it but can’t display it again, so store it in n8n’s credentials manager as soon as you copy it. Rotate it any time from the integration card; the old one stops working immediately. Because n8n sends it as a header rather than embedding it in a URL, it’s less likely to end up in logs by accident — but it will still appear in an exported workflow JSON if you paste it directly into the node instead of using a credential. Submissions are isolated per tenant — this endpoint only ever writes into your own BytePhase account.

Start Automating Lead Capture With n8n and BytePhase

Once your workflow is live, anything it touches — a form, a spreadsheet row, a chatbot conversation — can become a Lead or Self Check-in in BytePhase without anyone re-typing it. From a Self Check-in, converting to a repair ticket is one click once the device is actually in front of you. If you’d rather connect a form directly without building a workflow, see the Typeform and Jotform setup guides, or the Zapier guide for a no-code automation route. See every connector BytePhase supports on the integrations page.

BytePhase includes the n8n integration on every plan, with a 15-day free trial and no credit card required. Start your free BytePhase trial →