ReCall Partner API — Onboarding Guide

Your ReCall admin has issued you one API key that looks like this:

recall_partner_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Treat this key like a database password:

• Store it in your backend secrets manager (AWS Secrets Manager, GCP Secret Manager, 1Password, Doppler, etc.)
• Never commit it to source control, log it, or expose it to browser code.
• If lost or leaked, contact your ReCall admin — we'll revoke and reissue it.

You should also have received:

Every request must include your API key as a Bearer token:

Authorization: Bearer recall_partner_live_XXXXXXXXXX...

Bad or missing keys → HTTP 401. Keys used against endpoints outside /api/v1/partner/* → HTTP 401.

3.1 Provision a new tenant

POST https://recall.business/api/v1/partner/tenants

Body:

{
  "business_name": "Bob's HVAC",
  "full_name": "Bob Smith",
  "email": "bob@bobshvac.com",
  "timezone": "America/New_York",
  "external_id": "your-user-id-12345"
}

Field notes:

• business_name — displayed in ReCall's app + booking-page name
• full_name — owner user we create for this tenant
• email — must be unique across all of ReCall (HTTP 400 if already registered)
• timezone — optional, IANA format (default America/New_York)
• external_id — optional, stored on the tenant for cross-referencing

Response (HTTP 200):

{
  "ok": true,
  "tenant_id": "8f2c1e...",
  "user_id": "d4a91b...",
  "booking_slug": "bobs-hvac",
  "login_token": "eyJhbGci...",
  "login_url": "https://recall.business/auth/partner-login?token=eyJ..."
}

Billing note: the tenant is now active and counts toward your next invoice. No Stripe checkout happens for the end-user — you (the partner) are billed.

3.2 List all your tenants

GET https://recall.business/api/v1/partner/tenants

Response includes total and an array of tenants with id, business_name, booking_slug, partner_external_id, created_at, and deleted_at. Filter by deleted_at !== null to show only active tenants.

3.3 Get current usage + projected invoice

GET https://recall.business/api/v1/partner/usage

{
  "partner_id": "e97867...",
  "partner_name": "Jobber Integration",
  "active_tenants": 42,
  "rate_per_tenant_cents": 1900,
  "rate_per_tenant_usd": 19.0,
  "projected_month_end_invoice_cents": 79800,
  "projected_month_end_invoice_usd": 798.0,
  "note": null
}

If note mentions placeholder pricing, your rate isn't finalized yet — your ReCall admin will update it once the contract is signed. Existing tenants continue to work fine.

3.4 Offboard a tenant (soft-delete)

DELETE https://recall.business/api/v1/partner/tenants/{tenant_id}

• Tenant is soft-deleted immediately — the owner user can no longer sign in.
• Your Stripe subscription quantity is re-reported to Stripe within seconds so this tenant drops off your bill this period.
• Idempotent — a second DELETE returns {"ok": true, "already_offboarded": true}
• Tenants that don't belong to you return HTTP 404 (never 403 — we don't leak the existence of other partners' tenants).

Every provisioning response includes a login_url — a one-shot signed JWT that logs the end-user directly into their workspace.

Recommended flow:

1. Your customer clicks "Open ReCall Dashboard" (or similar) in your app.
2. Your backend calls POST /api/v1/partner/tenants for first-timers, or retrieves the saved login_token if you cached it.
3. Redirect the customer's browser to login_url — ReCall consumes the token, sets an auth cookie, and lands them on /app.

Token TTL: 30 days. To generate a fresh token for an existing user, contact us — self-service re-mint is on the roadmap.

• Global: 300 requests / minute per API key
• Provisioning: 60 tenant creations / minute per API key

Exceeding these returns HTTP 429 with a Retry-After header (seconds).

All error responses include a detail field with a human-readable message.

There is currently no separate test environment — the partner API runs against the live database, and all Stripe charges hit your live subscription.

Recommended:

1. Create 1–2 tenants with obviously fake email addresses (test-1@yourcompany.dev).
2. Verify they show up in GET /api/v1/partner/tenants.
3. Offboard them via DELETE — they drop off the count within seconds.
4. Verify GET /api/v1/partner/usage reflects the correct running total.

Because offboarding fires an immediate Stripe re-report, test tenants won't appear on your invoice as long as you delete them before the 1st of the following month.

You have web access to the same data at:

https://recall.business/partner

Paste your API key on that page and you'll see live tenant count, rate per tenant, projected month-end invoice, and a full tenant list with per-row Offboard button. The key is stored in browser localStorage only — nothing is transmitted to any third party. Sign out clears it.

• Cadence: Stripe generates one invoice per calendar month on the 1st. Payment is drawn from your card on file (or emailed if you're on NET-30).
• What we count: tenants where partner_id = you AND deleted_at IS NULL at the moment the monthly cron runs (00:15 UTC on the 1st).
• Prorations: none. A tenant that exists for one hour is billed the same as one that exists for the full month.
• Invoice email: sent to the contact_email your admin provided at partner creation. To change it, ask your ReCall admin.
• Failed payment: Stripe smart-retry logic (3 attempts over 21 days). Final failure → account flips to past_due — contact us.

• Technical questions: engineering@recall.business
• Contract / rate questions: your assigned account manager
• Emergencies: call the on-call number provided at contract signing

Response time: <4 business hours during 9-5 ET.

By using this API, you agree that:

• You will not resell or transfer the API key.
• You will comply with the messaging opt-in laws that apply in your customers' jurisdictions (TCPA, A2P 10DLC, GDPR, etc.). ReCall provides the plumbing; lawful use is your responsibility.
• Your customers' phone-number and lead data is processed under ReCall's standard privacy terms at recall.business/legal/privacy.
• ReCall may audit provisioned tenants for compliance with the agreed use case.