Integration guide

Get your platform sending leads into Switchly in under fifteen minutes.

1. Get credentials

A Switchly admin registers your platform and returns two values you'll never see again:

• api_key — your bearer token. Send as Authorization: Bearer <api_key> on every request.
• signing_secret — a 48-character HMAC secret. Switchly signs outbound webhooks to your platform with this so you can authenticate them.

Capture both into your secrets store (1Password, Vault, AWS Secrets Manager, whatever) the moment the registration response comes back.

2. Send your first lead

The smallest viable request hits POST /v1/leads/ingest with a Universal Lead Schema payload. The minimum required blocks are lead_metadata, consumer, and compliance.tcpa_consent.

curl -X POST https://api.switchly.example/api/v1/leads/ingest \
  -H "Authorization: Bearer $SWITCHLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "lead_metadata": {
      "lead_id": "019e4ddd-aaaa-7000-8000-000000000001",
      "timestamp": "2026-05-22T15:00:00Z",
      "product_line": "medicare"
    },
    "consumer": {
      "first_name": "Jordan",
      "phone": "+1-555-0100",
      "address": {"state": "IN", "zip": "46202"}
    },
    "compliance": {
      "tcpa_consent": true
    }
  }'

A successful response is 201 Created:

{
  "lead_id": "019e4d80-bbbb-7000-8000-222222222222",
  "status": "accepted",
  "errors": []
}

The lead_id Switchly returns is the canonical UUID you'll use for every follow-up call.

Using the PHP SDK? composer require switchly/php-sdk and use the UlsLeadBuilder to compose payloads without hand-writing JSON.

3. Subscribe to lifecycle events

Lead routing is asynchronous — Switchly accepts your lead in milliseconds and then queues it for matching. To learn what happens next, register a webhook subscription:

curl -X POST https://api.switchly.example/api/v1/webhooks \
  -H "Authorization: Bearer $SWITCHLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-platform.example/webhooks/switchly",
    "events": [
      "lead.routed",
      "lead.delivered",
      "lead.failed",
      "lead.status_changed"
    ],
    "description": "Production CRM bridge"
  }'

The response includes a one-time signing_secret for this webhook. Switchly maintains a separate secret per webhook so you can rotate one endpoint's credentials without touching the rest. See the webhook guide for the full event catalog and how to verify the X-Switchly-Signature header.

4. Pull status when you need it

Webhooks are push; if you need a synchronous snapshot, call:

GET /api/v1/leads/{lead_id}/status

Returns the lifecycle (ingestion → routing → delivery), the lead's current scoring values, fraud flags, and the per-attempt audit trail.

5. Sync your agents (optional)

If Switchly should be able to route leads to specific named agents on your platform, post your roster up via POST /v1/agents/sync. The endpoint upserts on (site_id, email) and replaces each agent's licenses. Pass a removed_emails array to suspend agents who've left.

{
  "agents": [
    {
      "name": "Jane Smith",
      "email": "jane@example.test",
      "phone": "+1-555-0100",
      "status": "active",
      "licenses": [
        {"state": "IN", "license_number": "X-1", "status": "active"},
        {"state": "OH"}
      ]
    }
  ],
  "removed_emails": ["former@example.test"]
}

See /docs for the full Swagger reference and the ULS guide for what each ULS block actually means.