# Cipher & Row Integration Guide

> Phase 1 covers carrier and broker verification, continuous compliance monitoring, and driver Trust Links. Three doors into the same backend — pick the one that fits how you build.

## 1. Dashboard

The web dashboard at https://www.cipherandrow.com is the human interface. Role-based pages for dispatchers, brokers, carriers, and admins. Run lookups, save companies to your watched list, send Trust Links to drivers, and manage billing.

## 2. REST API

Programmatic access for custom integrations. Authenticate with an API key from `Settings → API`.

**Phase 1 endpoints:**

- `POST /carrier-lookup` — look up a US carrier by MC or DOT (FMCSA QCMobile + L&I + SAFER)
- `POST /carrier-lookup-ca` — look up a Canadian carrier by CVOR (ON), CTQ/NEQ (QC), NSC, or cross-border DOT
- `POST /verify-carrier` — full verification (authority + insurance + fraud signals) in one call
- `POST /broker-lookup` — verify a US broker's FMCSA authority and BMC-84 bond
- `POST /ca-broker-verify` — verify a Canadian broker against CBSA and provincial registries
- `POST /carrier-monitor` — subscribe to a carrier; get a webhook when authority, insurance, or safety rating changes
- `POST /insurance-monitor` — watch a carrier's insurance certificate; alert on lapse or impending expiry
- `POST /compliance-scan` — on-demand fresh snapshot across all upstream registries
- `POST /trust-link-create` — mint a one-time tokenized URL for a driver (SMS or email)
- `POST /trust-link-verify` — driver-side endpoint that binds the link to a name + truck

Full reference: https://www.cipherandrow.com/docs

**Rate limits:** Free 10 req/min · Starter 120 · Pro 1,000 · Enterprise custom. Daily quotas: 100 / 5,000 / 50,000 / unlimited. Returned in `X-RateLimit-*` headers.

**Auth:** `x-api-key: cr_live_...`. Keys are shown only at creation; store in a secret manager and rotate from `Settings → API`.

Deal flow, agent-to-agent messaging, AI gateway, and document extraction endpoints arrive in Phase 2.

## 3. MCP Server

For AI agents (Claude, ChatGPT, custom). Phase 1 tools cover lookup, verification, monitoring, and Trust Links.

**Connection:**

```json
{
  "mcpServers": {
    "cipher-and-row": {
      "command": "npx",
      "args": ["-y", "@cipherrow/mcp-server"],
      "env": {
        "CR_API_KEY": "your_key_here"
      }
    }
  }
}
```

**Phase 1 tool examples:**

- `cr_carrier_lookup` — verify a US carrier by MC / DOT
- `cr_carrier_lookup_ca` — verify a Canadian carrier by CVOR / CTQ / NSC
- `cr_verify_carrier` — full verification (authority + insurance + fraud) in one call
- `cr_broker_lookup` — verify a US broker's authority and BMC-84 bond
- `cr_broker_verify_ca` — verify a Canadian broker
- `cr_monitor_carrier` — subscribe a carrier for compliance change alerts
- `cr_compliance_scan` — on-demand fresh snapshot of a carrier's compliance state
- `cr_trust_link_create` — mint a driver-facing Trust Link

Full tool list: https://www.cipherandrow.com/docs

## Webhooks

Subscribe a webhook URL when you create a monitoring subscription. Phase 1 event catalog:

- `authority_change` — operating authority moved between active / inactive / revoked
- `insurance_lapse` — insurance cancelled, reduced, or expiring within 14 days
- `insurance_renewed` — new or renewed coverage observed
- `safety_rating_change` — FMCSA / CVOR rating updated
- `out_of_service_added` / `out_of_service_lifted`
- `broker_bond_change` — BMC-84 bond status changed
- `broker_authority_change` — broker authority moved between active / inactive / revoked
- `trust_link_opened` / `trust_link_completed`

Webhooks are signed with HMAC-SHA256. Verify the `X-CR-Signature` header against your webhook secret before trusting the payload. Deliveries older than 5 minutes should be rejected as replays. Non-2xx responses are retried with exponential backoff for up to 24 hours.

## Quick start

1. Sign up at https://www.cipherandrow.com/signup
2. From `Settings → API`, generate a key
3. Run your first verification:
   ```
   curl -X POST https://amjwnrglafnzwfrctqoh.supabase.co/functions/v1/carrier-lookup \
     -H "x-api-key: $CR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"mc_number": "MC-391204"}'
   ```
4. Subscribe the carrier to monitoring and wire a webhook to receive `authority_change` and `insurance_lapse` events.

## Need help

Email integrations@cipherandrow.com or book a 30-minute integration call: https://www.cipherandrow.com/book-demo