Skip to content
BytePhaseBytePhaseBytePhase Developers

Quick Start

Four steps: create a key, work out your base URL, ping, create a lead.

1. Create an API key

Section titled “1. Create an API key”

In BytePhase, open Settings → Integrations and choose a provider — this is the key’s provider type, and it matters; see the note below. The wizard’s Connect step shows the key with the notice “Copy this key now. You will not be able to see it again.” Copy it; it starts with bp_. Finish the wizard and press Activate — “Nothing goes live until you press Activate.”

2. Find your base URL

Section titled “2. Find your base URL”

Your workspace has its own base URL. The workspace name is the subdomain you sign in with — if you sign in at harbor-repair.bytephase.com, your workspace is harbor-repair.

Environment Base URL
Production https://{workspace}.api.bytephase.com/api
Staging (BytePhase’s own test environment — not a customer sandbox) https://{workspace}.api.bytephaserecovery.com/api
Local development (BytePhase engineers running the stack locally) http://{workspace}.localhost:81/api
White-label custom domain https://{custom_domain}/api

Worked example. Workspace harbor-repair, production:

https://harbor-repair.api.bytephase.com/api/integrations/ping

If your workspace runs on its own domain (white-label), use that domain instead of api.bytephase.com — for example https://repairs.example.com/api/integrations/ping. Production examples pasted verbatim will not work on a white-label domain.

Getting the base URL wrong is the single most common setup mistake, which is why the next step exists. More in Environments.

3. Test the connection

Section titled “3. Test the connection”
Terminal window
curl "https://harbor-repair.api.bytephase.com/api/integrations/ping" \
  -H "Authorization: Bearer bp_your_api_key" \
  -H "Accept: application/json"

A good key against the right URL returns:

{
  "status": "connected",
  "workspace": "Harbor Repair Co.",
  "provider": "REST API"
}
If you see… It means
401 with credential_missing The header did not arrive. Check the header name and the Bearer prefix.
401 with credential_invalid Wrong key, or the key was disabled, rotated or has expired. Copy it again from BytePhase.
412 The workspace could not be identified from the URL. Fix the subdomain or the domain.
Connection refused / DNS failure Wrong host. Compare with the table above.

4. Create a lead

Section titled “4. Create a lead”
Terminal window
curl -X POST "https://harbor-repair.api.bytephase.com/api/integrations/leads" \
  -H "Authorization: Bearer bp_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 8f4c1e2a-6b3d-4f5e-9a7c-2d1b0e9f8a7b" \
  -d '{
    "name": "Jordan Ellis",
    "mobile_number": "4155550142",
    "mobile_country_code": "+1",
    "email": "jordan.ellis@example.com",
    "device_type": "Laptop",
    "device_brand": "Dell",
    "device_model": "XPS 13",
    "comment": "Screen flickers after boot",
    "source": "Website"
  }'

A lead needs a name and at least one of mobile_number or email. Everything else is optional. The response is 201 Created:

{
  "status": "completed",
  "request_id": "01K4R4Z2N7Q9X0F3M6C8V1B5D2",
  "data": {
    "id": 10421,
    "object": "lead",
    "name": "Jordan Ellis",
    "email": "jordan.ellis@example.com",
    "mobile_number": "4155550142",
    "mobile_country_code": "+1",
    "phone_number": null,
    "contact_person_name": null,
    "status": "New",
    "status_stage": "open",
    "source": "Website",
    "assigned_to": "Alex Morgan",
    "next_follow_up": null,
    "comment": "Screen flickers after boot",
    "created_at": "2026-09-09T09:14:07.000000Z"
  }
}

Run the same request again with the same Idempotency-Key and you get 200 OK with "status": "duplicate" and the same lead — no second record. Send it with a different key and the same phone number, and the workspace’s duplicate rule decides: by default an existing lead with that mobile number or email is returned as duplicate rather than created twice.

What happened

Section titled “What happened”
  • The key identified your integration inside your workspace.
  • The request was logged. Open the integration’s Activity screen under Settings → Integrations to see it as Successful, with the request_id shown above.
  • The lead was assigned to the workspace’s default assignee and is visible in the Leads list.

Next

Section titled “Next”