Concepts

Repair-shop vocabulary is not self-evident. Ten minutes here prevents integrations that break on the first workspace with custom statuses.

Workspace

A workspace is one BytePhase account — one shop or one company. It has its own subdomain (harbor-repair.bytephase.com), its own data, its own settings and its own API keys. Nothing crosses workspaces: a key from one workspace does not exist in another.

In the API the workspace is identified by the base URL — the subdomain (or white-label domain) you send the request to. It never appears in a request body. The connection test returns its display name as workspace.

Business

A workspace may contain more than one business — a location, branch or brand operating under the same account. There is no separate “branch” concept; business is the branch.

• Every workspace has a default business.
• Intake requests accept an optional integer business_id. Omit it and the record belongs to the default business.
• An unknown or disallowed business_id is rejected with 403 integration_not_permitted.

Most integrations never need to set it.

Customer

A customer is a person or company the shop has done business with. Customers are created inside the app, or by Zapier’s “create customer” action. The API’s read endpoints return recent customers with name, email, mobile, phone, tax number and source.

Lead

A lead is an enquiry that has not yet become a repair: a quote request, a contact-form message, a marketplace enquiry. It carries contact details, optional device details, a comment, a source, a status and an assignee.

Leads are the main thing the intake API creates. They are assigned automatically to the workspace’s default assignee and appear in the Leads list immediately.

Duplicate handling. By default, a new lead whose mobile number (with country code) or email matches an existing lead is not created again; the existing lead is returned with "status": "duplicate". The behaviour can be changed per form in the integration’s settings.

Self check-in

A self check-in is a customer-initiated repair booking: “here is my device, here is what is wrong, I will bring it in”. It carries contact details, device type, brand and model, serial numbers, accessories, an optional pickup request and an optional scheduled date. Staff turn it into a repair when the device arrives.

Self check-ins are the second thing the intake API creates. By default every submission creates a new self check-in (no duplicate merging), because two bookings from one customer are usually two devices. For what the customer and the shop each see, read How self check-in works in BytePhase.

Repair

A repair (called a repair ticket, job or job sheet in the app) is the core record: a device, a customer, a fault, work done, parts, and a bill. The API does not create repairs. Zapier-typed keys can read recent repairs — number, status, customer, device, amount, payment status, assignee, estimated delivery.

Statuses and stages

Repair and lead statuses are configured per workspace. One shop has “Received, Diagnosing, Waiting for Parts, Ready”; another has twelve statuses in another language. Do not hard-code status names.

Each status belongs to a stage, which is a small fixed set that stays the same across workspaces. Records returned by the API carry both:

"status": "Waiting for Parts",
"status_stage": "in_progress"

Branch on status_stage when you need logic; display status to people. The exact list of stage values is in the API reference.

Payment

A payment is money received against a repair or an invoice. Zapier-typed keys can read recent payments: amount, payment type, transaction reference, when it was received, and the customer. Payments cannot be created through the API.

Outsourced repair

Work the shop sends to an outside vendor. Readable by Zapier-typed keys: vendor, price, description, the repair it belongs to and the device.

Form and field map

An integration can have one or more forms, each identified by a form_id you choose (or that the provider supplies). A form has a destination — lead or self_checkin — and, where needed, a field map that translates the names your form uses into BytePhase’s names:

"Your Name"     → name
"Phone"         → mobile_number
"What's wrong?" → comment

Forms are configured in BytePhase under the integration. A submission that names a form_id uses that form’s destination and map. A submission with no form_id on an integration with exactly one form uses that form; otherwise it must say which destination it wants.

Your own code can skip the map entirely by sending BytePhase’s field names directly.

Submission log

Every request to an intake endpoint is recorded against the integration: when, from where, what was sent, what was created, and the request id. Failed and parked submissions can be retried from there once the cause is fixed. It is the first place to look when something is missing. See Submissions & Troubleshooting.

Custom fields

Workspaces can define their own fields for leads and self check-ins. Any field in a submission that BytePhase does not recognise is kept as a custom field on the record rather than discarded, so nothing a customer typed is lost. See Custom Integrations.