The EZPZ API

Send your key as a bearer token on every request.

Authorization: Bearer ezpz_live_…

We show the secret once, when you make the key. We keep only a hash of it, so copy it then. Revoke a key in Studio at any time; it stops working at once.

List endpoints take limit (default 50, max 100) and cursor. Pass the next_cursor you got back to read the next page. It is null on the last page.

{
  "object": "list",
  "data": [ … ],
  "next_cursor": "…" | null
}

A failed request answers with a status code and one stable code you can branch on.

{ "error": "<code>" }

Each key gets 600 requests a minute and 50,000 a day. Past either, you get 429 rate_limited with a Retry-After header in seconds.

A person an agent is working: contact facts, where they came from, and where they stand.

• GET /api/v1/leadsList leads, newest first.
• GET /api/v1/leads/{id}Get one lead.
• POST /api/v1/leadsCreate a lead.
• PATCH /api/v1/leads/{id}Change its agency fields (custom), its stage (stage_id) or its notes.
• POST /api/v1/leads/{id}/notesAdd a note.
• POST /api/v1/leads/{id}/appointmentsBook an appointment.

custom holds your agency's own fields on this object, keyed by field key. A field that looks like health data is never sent.

curl https://www.buildezpz.com/api/v1/leads/ld_2b3c4d5e-0000-4000-8000-00000001ead1 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "lead",
  "id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
  "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "first_name": "Dana",
  "last_name": "Ruiz",
  "email": "dana.ruiz@example.com",
  "phone": "+15555550142",
  "state": "TX",
  "zip": "78701",
  "age": 54,
  "disposition": "booked",
  "stage": {
    "id": "st_92a3b4c5-0000-4000-8000-0000000057a6",
    "key": "appointment_set",
    "label": "Appointment set"
  },
  "source": "facebook",
  "product_type": "final_expense",
  "tags": [
    "evenings"
  ],
  "notes": "Prefers a call after 6 pm.",
  "score": 82,
  "score_warmth_label": "Warm",
  "call_count": 2,
  "dial_attempts": 5,
  "voicemails_left": 1,
  "callback_at": null,
  "closed_at": null,
  "last_touched_at": "2026-09-30T18:04:11Z",
  "last_dialed_at": "2026-09-30T17:58:40Z",
  "last_inbound_at": "2026-09-30T18:02:09Z",
  "cost_cents": 2400,
  "campaign_id": "c5d6e7f8-0000-4000-8000-0000000ca3e1",
  "origin_channel": "facebook",
  "referred_by_lead_id": null,
  "custom": {
    "coverage_goal": "burial"
  },
  "created_at": "2026-09-28T15:20:00Z",
  "updated_at": "2026-09-30T18:04:11Z"
}

Never exposed: sensitive — date_of_birth, raw_payload; vendor ids — meta_*, gclid, base44_id; internal — lead_session_id, custody_*, copied_from_lead_id, listing_id, purchased_from_listing_id, pool_listed_at, resale_owner_id, purge_hold_at, scrub_*, last_inbound_preview.

A sale (or a policy in motion) on a lead: carrier, product, premium and where it stands.

• GET /api/v1/policiesList policies.
• GET /api/v1/policies/{id}Get one policy.

custom holds your agency's own fields on this object, keyed by field key. A field that looks like health data is never sent.

curl https://www.buildezpz.com/api/v1/policies/pl_3c4d5e6f-0000-4000-8000-0000000b0011 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "policy",
  "id": "pl_3c4d5e6f-0000-4000-8000-0000000b0011",
  "lead_id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
  "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "ap_cents": 102000,
  "advanced_pay_cents": 76500,
  "commission_cents": 102000,
  "commission_pct": 100,
  "face_amount_cents": 1500000,
  "carrier_name": "Example Mutual",
  "carrier_product": "Level Benefit Whole Life",
  "policy_number": "EX-0001245",
  "policy_stage": "issued",
  "policy_stage_at": "2026-10-01T14:00:00Z",
  "close_date": "2026-09-30",
  "effective_date": "2026-10-15",
  "sold_reason": "Wanted burial covered for her kids.",
  "policy_note": null,
  "client_first_name": null,
  "client_last_name": null,
  "call_id": "cl_5e6f7081-0000-4000-8000-0000000ca111",
  "custom": {},
  "created_at": "2026-09-30T19:10:00Z",
  "updated_at": "2026-10-01T14:00:00Z"
}

Never exposed: sensitive — client_dob; internal — closed_by, stage_nudge_*, contact_idx.

A booked meeting with a lead and what came of it.

• GET /api/v1/appointmentsList appointments.
• GET /api/v1/appointments/{id}Get one appointment.

curl https://www.buildezpz.com/api/v1/appointments/ap_4d5e6f70-0000-4000-8000-0000000a1101 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "appointment",
  "id": "ap_4d5e6f70-0000-4000-8000-0000000a1101",
  "lead_id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
  "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "starts_at": "2026-10-01T23:00:00Z",
  "ends_at": "2026-10-01T23:30:00Z",
  "timezone": "America/Chicago",
  "status": "scheduled",
  "outcome": null,
  "title": "Dana Ruiz — coverage review",
  "notes": null,
  "source": "echo",
  "created_by": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "created_at": "2026-09-30T18:03:00Z",
  "updated_at": "2026-09-30T18:03:00Z"
}

Never exposed: vendor ids — google_*, html_link, meet_link.

A phone call, inbound or outbound, and how it went.

• GET /api/v1/callsList calls.
• GET /api/v1/calls/{id}Get one call.

curl https://www.buildezpz.com/api/v1/calls/cl_5e6f7081-0000-4000-8000-0000000ca111 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "call",
  "id": "cl_5e6f7081-0000-4000-8000-0000000ca111",
  "lead_id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
  "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "direction": "outbound",
  "status": "completed",
  "started_at": "2026-09-30T17:58:40Z",
  "answered_at": "2026-09-30T17:58:52Z",
  "ended_at": "2026-09-30T18:05:44Z",
  "duration_sec": 412,
  "voicemail": false,
  "from_number": "+15555550100",
  "to_number": "+15555550142",
  "caller_name": null,
  "placed_by_actor_id": null,
  "answered_by": "human",
  "recording_duration_sec": 405,
  "has_recording": true,
  "transcription": null,
  "recording_link": null,
  "created_at": "2026-09-30T17:58:40Z"
}

Never exposed: vendor ids — provider*, twilio_*, *_sid, agent_leg_call_control_id, stir_*, caller_line_type, hangup_cause, recording_url; internal — quality_flags, error_*, *_alerted_at, *_started_at.

A text message to or from a lead.

• GET /api/v1/messagesList text messages.

curl "https://www.buildezpz.com/api/v1/messages?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": "ms_6f708192-0000-4000-8000-0000000e5501",
      "lead_id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
      "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
      "direction": "inbound",
      "body": "Tuesday at 6 works for me.",
      "status": "received",
      "from_number": "+15555550142",
      "to_number": "+15555550100",
      "num_media": 0,
      "send_origin": null,
      "sent_by_kind": null,
      "sent_by_actor_id": null,
      "read_at": "2026-09-30T18:02:30Z",
      "created_at": "2026-09-30T18:02:09Z"
    }
  ],
  "next_cursor": null
}

Never exposed: vendor ids — provider*, twilio_message_sid, subaccount_sid; internal — error_*, opt_out_*, send_class; billing — num_segments.

A person on the agency's team.

• GET /api/v1/agentsList the agents your key can see.
• GET /api/v1/agents/{id}Get one agent.

custom holds your agency's own fields on this object, keyed by field key. A field that looks like health data is never sent.

curl https://www.buildezpz.com/api/v1/agents/ag_1a2b3c4d-0000-4000-8000-0000000a6e01 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "agent",
  "id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "full_name": "Sam Okafor",
  "display_name": "Sam",
  "business_name": "Okafor Family Coverage",
  "email": "sam.okafor@example.com",
  "phone": "+15555550100",
  "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
  "role": "member",
  "manager_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e02",
  "npn": "99990001",
  "timezone": "America/Chicago",
  "work_state": "TX",
  "avatar_url": null,
  "status": "active",
  "custom": {
    "contract_level": 90
  },
  "created_at": "2026-01-12T16:00:00Z"
}

Never exposed: sign-in secrets — client_data_pin_hash, phone_e164_*; vendor ids — base44_id, telephony_provider; internal — referral_code*, pz_*, va_of_user_id, paused_*, scrub_*, *_override*, sms_*, email_*, setup_progress, discovery_questions, dismissed_announcements; billing — admin_*, access_granted_by_admin, comp_source, lead_ceiling.

A custom role the agency defined in Studio, and the switches it grants.

• GET /api/v1/rolesList your agency's custom roles.

curl "https://www.buildezpz.com/api/v1/roles?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "list",
  "data": [
    {
      "object": "role",
      "id": "rl_708192a3-0000-4000-8000-0000000501e1",
      "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
      "name": "Closer",
      "description": "Works their own leads and sees the team board.",
      "switches": {
        "leads.view": [
          "own"
        ],
        "leads.edit": [
          "own"
        ],
        "calls.dial": [
          "own"
        ],
        "team.production": [
          "team"
        ],
        "build.reports": true
      },
      "push_mode": null,
      "status": "live",
      "created_at": "2026-09-01T15:00:00Z"
    }
  ],
  "next_cursor": null
}

Never exposed: internal — grants, created_by.

A custom field the agency defined on leads, policies or agents.

• GET /api/v1/fieldsList your agency's custom fields.

curl "https://www.buildezpz.com/api/v1/fields?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "fd_8192a3b4-0000-4000-8000-0000000f1e1d",
      "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
      "key": "coverage_goal",
      "label": "Coverage goal",
      "type": "select",
      "options": [
        {
          "value": "burial",
          "label": "Burial"
        },
        {
          "value": "income",
          "label": "Income"
        }
      ],
      "required": false,
      "help": "What the client wants the policy to do.",
      "position": 1,
      "push_mode": "extendable",
      "status": "live",
      "created_at": "2026-09-01T15:00:00Z"
    }
  ],
  "next_cursor": null
}

Never exposed: internal — created_by.

An agency stage: the agency's own word for one of the fixed dispositions.

• GET /api/v1/stagesList your agency's stages.

curl "https://www.buildezpz.com/api/v1/stages?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "list",
  "data": [
    {
      "object": "stage",
      "id": "st_92a3b4c5-0000-4000-8000-0000000057a6",
      "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
      "key": "appointment_set",
      "label": "Appointment set",
      "maps_to": "booked",
      "tone": "sea",
      "position": 3,
      "push_mode": null,
      "status": "live",
      "created_at": "2026-09-01T15:00:00Z"
    }
  ],
  "next_cursor": null
}

Never exposed: internal — created_by.

A custom table that applies in your agency: its own, or one pushed to it. Only live tables are listed.

• GET /api/v1/tablesList the custom tables live in your agency, each with its fields.
• GET /api/v1/tables/{id}Get one table.

curl https://www.buildezpz.com/api/v1/tables/tb_a3b4c5d6-0000-4000-8000-00000007ab1e \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "table",
  "id": "tb_a3b4c5d6-0000-4000-8000-00000007ab1e",
  "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
  "key": "referrals",
  "name": "Referrals",
  "record_noun": "referral",
  "icon": null,
  "shared": true,
  "on_lead": true,
  "status": "live",
  "fields": [
    {
      "key": "relationship",
      "label": "Relationship",
      "type": "text",
      "options": [],
      "required": true
    }
  ]
}

Never exposed: internal — created_by.

A record in a custom table. owner_id is null on an agency-shared table.

• GET /api/v1/records?table_id=&owner_id=&updated_since=List one table's records, newest first. table_id is required. A list past your agency's rows-per-filter limit (20,000 unless raised) answers 422 too_many_rows: narrow it by owner_id or updated_since.
• GET /api/v1/records/{id}Get one record.
• POST /api/v1/recordsCreate a record: {table_id, owner_id?, data}, data keyed by field key. Without owner_id it belongs to your key's default owner (a shared table's records have none). Link fields are read-only.
• PATCH /api/v1/records/{id}Change some of its values: {data}, keyed by field key; null clears one.

data holds the table's fields, keyed by field key (the table's fields list them). A field that looks like health data is never sent.

curl https://www.buildezpz.com/api/v1/records/rc_b4c5d6e7-0000-4000-8000-0000000ec0d1 \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "record",
  "id": "rc_b4c5d6e7-0000-4000-8000-0000000ec0d1",
  "table_id": "tb_a3b4c5d6-0000-4000-8000-00000007ab1e",
  "agency_id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
  "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
  "title": "Referral from Dana Ruiz",
  "data": {
    "relationship": "Neighbor"
  },
  "links": [
    {
      "kind": "lead",
      "id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1"
    }
  ],
  "created_at": "2026-09-30T19:20:00Z",
  "updated_at": "2026-09-30T19:20:00Z"
}

Never exposed: nothing beyond the rule — a column that is not a field above is never sent.

The agency itself and where it sits in the tree.

• GET /api/v1/agencyGet your agency.

curl https://www.buildezpz.com/api/v1/agency \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "agency",
  "id": "ay_0c1d2e3f-0000-4000-8000-00000000a9e1",
  "name": "Example Agency Group",
  "parent_id": null,
  "tier": "portal",
  "created_at": "2025-11-03T15:00:00Z"
}

Never exposed: vendor ids — telnyx_*; internal — owner_email; billing — monthly_price, portal_comped_*, stripe_*; platform costs — *pricing*.

One agent's numbers for one day, computed from the ledgers. Id kd_<agent uuid>_<YYYY-MM-DD>. Totals: not subject to the consent rule, like Team production.

• GET /api/v1/kpi_days?from=&to=&agent_id=One row per agent per day between from and to (dates, at most 93 days). agent_id is optional.

curl "https://www.buildezpz.com/api/v1/kpi_days?from=2026-09-30&to=2026-09-30&agent_id=ag_1a2b3c4d-0000-4000-8000-0000000a6e01" \
  -H "Authorization: Bearer ezpz_live_…"

{
  "object": "list",
  "data": [
    {
      "object": "kpi_day",
      "id": "kd_1a2b3c4d-0000-4000-8000-0000000a6e01_2026-09-30",
      "agent_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
      "date": "2026-09-30",
      "dials": 118,
      "contacts": 31,
      "appointments_set": 6,
      "appointments_held": 4,
      "presentations": 4,
      "closes": 2,
      "texts_sent": 85,
      "talk_seconds": 9420,
      "leads_received": 14,
      "ap_cents": 204000,
      "spend_cents": 42000,
      "lead_cost_cents": 33600,
      "cost_per_lead_cents": 3000,
      "cost_per_close_cents": 21000
    }
  ],
  "next_cursor": null
}

Never exposed: nothing beyond the rule — a column that is not a field above is never sent.

Add an endpoint in Studio › API & webhooks and pick the events it gets. Each delivery is a POST with this JSON body.

data.object is the full resource, exactly as the API returns it. changed lists the fields that changed.

{
  "id": "evt_01J9EXAMPLE0000000000000001",
  "type": "lead.stage_changed",
  "created_at": "2026-09-30T18:04:12Z",
  "api_version": "v1",
  "data": {
    "object": {
      "object": "lead",
      "id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
      "owner_id": "ag_1a2b3c4d-0000-4000-8000-0000000a6e01",
      "first_name": "Dana",
      "last_name": "Ruiz",
      "email": "dana.ruiz@example.com",
      "phone": "+15555550142",
      "state": "TX",
      "zip": "78701",
      "age": 54,
      "disposition": "booked",
      "stage": {
        "id": "st_92a3b4c5-0000-4000-8000-0000000057a6",
        "key": "appointment_set",
        "label": "Appointment set"
      },
      "source": "facebook",
      "product_type": "final_expense",
      "tags": [
        "evenings"
      ],
      "notes": "Prefers a call after 6 pm.",
      "score": 82,
      "score_warmth_label": "Warm",
      "call_count": 2,
      "dial_attempts": 5,
      "voicemails_left": 1,
      "callback_at": null,
      "closed_at": null,
      "last_touched_at": "2026-09-30T18:04:11Z",
      "last_dialed_at": "2026-09-30T17:58:40Z",
      "last_inbound_at": "2026-09-30T18:02:09Z",
      "cost_cents": 2400,
      "campaign_id": "c5d6e7f8-0000-4000-8000-0000000ca3e1",
      "origin_channel": "facebook",
      "referred_by_lead_id": null,
      "custom": {
        "coverage_goal": "burial"
      },
      "created_at": "2026-09-28T15:20:00Z",
      "updated_at": "2026-09-30T18:04:11Z"
    },
    "changed": [
      "stage",
      "disposition"
    ]
  }
}

A delete carries only the id.

{
  "id": "evt_01J9EXAMPLE0000000000000002",
  "type": "lead.deleted",
  "created_at": "2026-09-30T18:10:00Z",
  "api_version": "v1",
  "data": {
    "object": {
      "object": "lead",
      "id": "ld_2b3c4d5e-0000-4000-8000-00000001ead1",
      "deleted": true
    }
  }
}

• Delivery is at least once, and events of different resources arrive in no set order. Dedupe on ezpz-id, and read the record when order matters.
• policy.sold can arrive more than once for the same policy — each time its stage or close date is set while it is live. Key on the policy id.
• When a lead moves to an agent outside your reach, your endpoint gets lead.moved with only { object, id, moved: true } — the agency it left hears that it went, not where.
• An endpoint hears only changes made after it was created, and nothing while it is paused.
• Send test in Studio sends a ping event, signed like any other.

Every delivery carries three headers:

• ezpz-id — the event id.
• ezpz-timestamp — when we signed it, in unix seconds.
• ezpz-signature — v1,<base64>.

The signed content is ${id}.${timestamp}.${rawBody}, signed with HMAC-SHA256. The key is your endpoint secret (whsec_…): base64 after the prefix. Reject a timestamp more than 5 minutes off, and compare in constant time.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the request body exactly as received (a string, before JSON.parse).
export function verifyEzpz(rawBody, headers, secret) {
  const id = headers['ezpz-id'];
  const timestamp = headers['ezpz-timestamp'];
  const signature = headers['ezpz-signature'] ?? '';
  if (!id || !timestamp || !signature.startsWith('v1,')) return false;

  // Reject anything more than 5 minutes off.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();
  const given = Buffer.from(signature.slice('v1,'.length), 'base64');

  return given.length === expected.length && timingSafeEqual(given, expected);
}

• Answer with a 2xx within 5 seconds. Anything else is a failure.
• We try 8 times over about 16 hours: 1 m → 5 m → 15 m → 1 h → 2 h → 4 h → 4 h → 4 h.
• We do not follow redirects. Give us the final URL.
• An endpoint pauses after 50 failures in a row. Turn it back on in Studio.
• Endpoints must be HTTPS to a public host.
• Delivery is at least once. You may get the same event twice — dedupe on ezpz-id.

EZPZ runs an MCP server, so an AI agent such as Claude can read your book and propose changes. It sees the same records the API does, through the same permissions.

https://www.buildezpz.com/api/mcp

• As yourself. Add the server URL as a connector in your AI app and sign in to EZPZ. On the consent screen you pick what it acts as: you, with all your powers or only some of your roles; or, if you manage API keys, one of your agency's keys.
• Headless. An agent with no sign-in screen sends an API key as the bearer: Authorization: Bearer ezpz_live_…. It acts as that key.
• Scopes. ezpz.read reads. ezpz.write adds the tools that propose changes. A key also needs the read_write scope to write.
• Propose, then confirm. A propose_… tool changes nothing. It checks the change, stores it for 15 minutes and answers an id and a summary. The agent shows you the summary and runs confirm_action only when you say yes. Each confirm runs once and is logged in Studio › Activity.
• Autopilot. Off by default. Turn it on for a key in Studio, or for your own connection in Settings › Connections, and proposals run at once. An agent can be steered by text it reads in a lead's messages, so turn it on only for agents you trust.
• Limits. Per connection: 60 requests a minute, 3,000 a day, and 30 writes a minute. Past one, you get 429 with a Retry-After header.

Each read answers exactly what its API endpoint answers. Write tools are listed only for a connection that may write.

Add your own web app in Studio › Apps & AI and it opens inside EZPZ, in the rail, for the people you pick. When someone opens it, EZPZ loads your start URL in a frame with a one-time token in the URL fragment. Your page trades that token for a one-hour session that acts as that person — it sees exactly what they see in EZPZ and can do only what they can.

• Your app must be served over HTTPS, and your server must allow EZPZ to frame it:

  Content-Security-Policy: frame-ancestors https://www.buildezpz.com https://buildezpz.com

• Read ezpz_token from location.hash, then remove it with history.replaceState.
• From the browser, POST /api/v1/auth/exchange with { "token": "…" }. The token works once, for 5 minutes, and only from your app's registered origin. Anything else answers 401 invalid_token.
• Use the access_token you get back (ezpz_sess_…) as Authorization: Bearer on /api/v1/*. It lasts an hour.
• On a 401, post { type: 'ezpz:token-expired' } to https://www.buildezpz.com and wait for { type: 'ezpz:token', token }, then exchange that token. Check event.origin on every message.
• To move EZPZ to one of its own pages, post { type: 'ezpz:navigate', path: '/leads' }.
• Never store either token — not in localStorage, a cookie or a log. Keep the session in memory and get a new one when it expires.

// 1. Read the one-time token from the fragment, then remove it from the URL.
const token = new URLSearchParams(location.hash.slice(1)).get('ezpz_token');
history.replaceState(null, '', location.pathname + location.search);

// 2. Exchange it from the browser (the Origin header must be your app's).
const PARENT = 'https://www.buildezpz.com';
async function exchange(t) {
  const res = await fetch(PARENT + '/api/v1/auth/exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: t }),
  });
  if (!res.ok) throw new Error('exchange failed');
  return (await res.json()).access_token; // ezpz_sess_… — keep it in memory only
}
let session = await exchange(token);

// 3. Call the API as the signed-in person.
async function api(path, init = {}) {
  const res = await fetch(PARENT + '/api/v1' + path, {
    ...init,
    headers: { ...init.headers, Authorization: 'Bearer ' + session },
  });
  if (res.status !== 401) return res;
  session = await renew(); // 4. On 401, ask EZPZ for a fresh token, then retry once.
  return fetch(PARENT + '/api/v1' + path, { ...init, headers: { ...init.headers, Authorization: 'Bearer ' + session } });
}

function renew() {
  return new Promise((resolve) => {
    window.addEventListener('message', async function onMessage(e) {
      if (e.origin !== PARENT || e.data?.type !== 'ezpz:token') return;
      window.removeEventListener('message', onMessage);
      resolve(await exchange(e.data.token));
    });
    parent.postMessage({ type: 'ezpz:token-expired' }, PARENT);
  });
}

// Move EZPZ itself to one of its pages:
// parent.postMessage({ type: 'ezpz:navigate', path: '/leads' }, PARENT);

EZPZ can keep a live copy of your agency’s data in a Postgres database you own. Changes in EZPZ reach your copy within seconds. The copy is one-way: nothing you write in your database comes back.

EZPZ stays the system of record. Make changes in EZPZ; read, join and report in your copy. The copy holds the same records and fields as API v1, under the schema ezpz_v1, ids included.

Connect it in Studio › Data copy. It is included in the Agency plan, and anyone whose role holds the Data copy switch can manage it.

• Postgres 14 or newer.
• SSL on. A connection string with sslmode=disable is refused.
• On Supabase, paste the pooler connection string (…pooler.supabase.com), not the direct db.<project>.supabase.co host. Use a paid project: a free project pauses when idle, and a paused project cannot be copied to.
• If your database has a firewall, allow the two addresses Studio › Data copy shows (one IPv4, one IPv6).

Paste a connection string for a user that can create a schema and a role. We use it once: we create the schema ezpz_v1 and a role ezpz_copier with its own password, keep that role’s connection sealed, and discard yours. ezpz_copier owns ezpz_v1 and can reach nothing else in your database.

Studio runs the checks and shows each one, with the fix beside any that fail. Then the first copy starts.

One table per resource, in ezpz_v1. id is the public id (ld_…, ag_…) and the primary key; references to other records are public ids too. Every public field is a column, typed:

• text — text, a fixed set of words.
• bigint — whole numbers, money in cents.
• numeric — decimals.
• boolean — true / false.
• timestamptz — times.
• date — dates.
• jsonb — objects, lists.

Custom values are in custom, keyed by each field’s key. Records of a custom table keep their values in records.data.

Every table also has:

• _xact — With _seq: the position in EZPZ’s change log this row was last written at.
• _seq — An older change never overwrites a newer one, and applying the same change twice writes nothing.
• _synced_at — When this row was last written in your copy.
• deleted_at — Set when the record was deleted in EZPZ. The row stays.

Tables of records an agent owns (leads, policies, appointments, calls, messages, agents, records, kpi_days) also have:

• departed_at — Set when the agent who owns it left your agency. The row stays and stops updating.
• moved_at — Set when the record moved to an agent outside your copy. The row stays and stops updating.
• reason — Why it stopped updating: departed, moved or consent_withdrawn.

We never delete a row in your database. What happened to a record is a column on its row:

• Deleted in EZPZ: deleted_at is set (a tombstone).
• Its agent left your agency: departed_at is set and reason is departed. The row stops updating.
• Moved to an agent outside your copy, or to one who has not accepted: moved_at is set and reason is moved. The row stops updating.
• If the record comes back to your copy, these clear and it updates again.

select *
from ezpz_v1.leads
where deleted_at is null
  and departed_at is null
  and moved_at is null;

Custom fields become columns in views we keep beside the tables: leads_typed, policies_typed, agents_typed, and one records_<table key> per custom table. Each field key is a column, cast by its type:

• number, currency → numeric
• date → date
• checkbox → boolean
• multi_select → text[]
• everything else → text

A field key that matches an existing column is named custom_<key>. The views are rebuilt when a field or table changes; the field and table definitions themselves are in fields and tables.

ezpz_v1.sync_meta has one row that tells you how current your copy is:

• model_version — The version of the table layout your copy has.
• last_synced_at — When the copy last caught up with every change.
• lag_ms — Milliseconds between a change in EZPZ and it landing here, for the latest batch.
• backlog — Changes waiting to copy.
• status — The copy’s state, as Studio shows it.
• backfill_done_at — When the first (or the latest full) copy finished.
• worker_version — The version of the program that wrote it.
• updated_at — When this row was last written.

select status, last_synced_at, lag_ms, backlog
from ezpz_v1.sync_meta;

Studio › Data copy shows the same. If the copy falls more than 15 minutes behind, or cannot reach your database again and again, the owner gets an email and a notice.

Choose in Studio › Data copy: Off, Links (the default) or Your bucket.

Links. recording_link on each row is a stable link, https://www.buildezpz.com/api/v1/calls/{id}/recording. Request it with an API key whose roles may listen to that agent’s recordings (calls.listen). It answers with a redirect to the audio, good for 10 minutes, or 404 when the audio is gone.

Your bucket. Each recording is also copied into your S3-compatible bucket (AWS S3, Cloudflare R2, Backblaze B2 and others) as ezpz-recordings/cl_….mp3 (or under the path prefix you set), and recording_object names it. recording_gone_at is set when the audio was gone before it could copy. We check the bucket the first time a recording copies; a failure shows in Studio and alerts the owner.

A bucket copy is kept by you, outside EZPZ’s deletion schedule. When a recording is removed in EZPZ we delete the object we copied into your bucket; copies you moved elsewhere are yours to delete.

Your agency and every agency under it are included. agents, roles, fields, stages, tables, agencies, kpi_days copy whether or not an agent accepted: your roster, its production totals and your definitions.

Record rows (leads, policies, appointments, calls, messages, records) copy only for agents who accepted the data copy notice. Each agent is asked the next time they sign in; Studio › Data copy shows how many of each agency have accepted.

Studio’s What copies switches turn whole groups off: leads with their deals and activity; conversations with their transcripts; agents with their roles, custom tables and records. Production totals, fields, stages and agencies always copy.

• Pause. Changes wait up to 7 days. Resume and what waited copies first.
• Can’t reach your database. We keep retrying, waiting longer each time. After 7 days the copy pauses and asks for a full re-copy, because changes older than 7 days are no longer kept.
• Re-copy all. Every record copies again from the start. Rows already in your database are updated in place, never deleted.
• Disconnect. Copying stops and we erase the connection. What is already in your database stays there.

Changes to ezpz_v1 are additive: a new table or a new column, applied to your copy automatically. Nothing is ever dropped or retyped. A breaking change ships ezpz_v2 beside ezpz_v1.

• Read your data. Outside setup (the server version, SSL, our role’s own rights) the one thing we read is ezpz_v1.sync_meta.
• Delete a row or drop a table in your database.
• Touch anything outside ezpz_v1.
• Show your connection string or bucket keys again. Both are stored sealed.

The version is in the path: /api/v1. Changes inside v1 are additive only — a new resource, a new field, a new event or a new enum value. Ignore fields you do not know.

A breaking change — a field removed or renamed, or its type or meaning changed — ships /api/v2 and ezpz_v2 beside v1, with a deprecation window.