Developers · API v1

The EZPZ API

Read and write your agency’s book with the same permissions your team has.

  • Make a key in Studio › API & webhooks.
  • A key acts as the roles you give it. It never reaches more than the person who made it.
  • A key can be limited to chosen fields. Every read and webhook it makes then carries only those fields, plus id.
  • Included in the Agency plan.
  • Spec file (OpenAPI 3.1) for code generators and API tools.
Start

Authentication

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.

Pagination

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
}

Errors

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

{ "error": "<code>" }
CodeStatusWhat it means
unauthenticated401No key, a malformed key, or a revoked one.
forbidden403The key is real but its roles do not allow this, or the record is outside its reach.
plan_required403The agency is not on a plan that includes the API.
not_found404No such record, or one the key cannot see.
validation422 · 400The body or query did not pass. 400 when an id is malformed.
unknown_param400A custom endpoint got a query parameter it does not take. The endpoint is the query.
rate_limited429Too many requests. Wait the seconds in the Retry-After header.
db_error500Our fault. Retry with backoff.
not_ready503This part of the API is still being switched on. Retry in a few minutes.

Rate limits

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.

Resources · ezpz_v1

Ids carry a prefix (ld_…, ag_…). Money is integer cents. Times are ISO 8601 in UTC; dates are YYYY-MM-DD. A key sees only the records its roles reach.

lead

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

  • GET /api/v1/leads?phone=&email=List leads, newest first. phone finds a lead by its number in any common US spelling; email by its address as typed or in lower case.
  • GET /api/v1/leads/{id}Get one lead.
  • POST /api/v1/leadsCreate a lead. Once your agency signs the key's consent promise in Studio, a lead the key posts with a phone can get texts. sms_consent: {text, at} is optional: the person's own consent words and when, kept as the proof. Before the promise is signed, a lead needs them to get texts.
  • PATCH /api/v1/leads/{id}Change its name, phone, email, state or product (first_name, last_name, phone, email, state, product_type), its agency fields (custom), its agency stage (stage_id) or its built-in stage (disposition: new_lead, called, contacted, follow_up, not_interested, booked, missed_appointment, wrong_number). A lead that is closed or presented keeps it. A note is its own call (below). address and source are refused.
  • POST /api/v1/leads/{id}/notesAdd a note. It shows in the lead's notes.
  • POST /api/v1/leads/{id}/tagsAdd or remove tags: {add?, remove?}, lists of tag names.
  • 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.

FieldTypeNotes
idstringThe lead id.
owner_idagent idThe agent who owns the record (an agent id).
first_namestring or nullFirst name.
last_namestring or nullLast name.
emailstring or nullEmail address.
phonestring or nullPhone number, E.164 where known.
statestring or nullTwo-letter US state.
zipstring or nullZIP code.
ageinteger or nullAge in years, as given.
dispositionstringThe fixed disposition, such as new_lead or booked (a sale is closed). Canonical; stage is the agency's word for it. PATCH can set it; closed, presented and chargeback stay with a person.
stageobject or nullThe agency stage it shows: {id, key, label}, or null for the fixed label.
sourcestringWhere the lead came from (facebook, transferred, mail_in, manual, …). A lead created through this API reads manual.
product_typestringThe product line the lead asked about (mp, iul, fex, annu or life). A lead filed on a lead type holds the type's base product.
lead_typeobject or nullThe lead type it is filed on: {key, label} — the agent's or the agency's own type, which works like its product_type. Null for a plain product.
tagsarrayTags, as strings.
notesstring or nullThe agent's notes on the lead.
scoreinteger or nullLead score, 0–100.
score_warmth_labelstring or nullThe warmth word beside the score.
call_countintegerThe current call streak.
dial_attemptsintegerEvery dial ever placed to the lead.
voicemails_leftintegerVoicemails left.
callback_attimestamp or nullA scheduled callback.
closed_attimestamp or nullWhen the lead was closed.
last_touched_attimestampThe last time anyone acted on the lead.
last_dialed_attimestamp or nullThe last dial.
last_inbound_attimestamp or nullThe last inbound text or call.
cost_centsinteger (cents)What the lead cost (cents).
campaign_idstring or nullThe ad campaign it came from (an EZPZ campaign id).
origin_channelstring or nullThe channel it first arrived through.
referred_by_lead_idlead id or nullThe lead who referred this one.
customobjectAgency field values, keyed by field key. Health-shaped fields are never included.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed.
Request
curl https://www.buildezpz.com/api/v1/leads/ld_2b3c4d5e-0000-4000-8000-00000001ead1 \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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",
  "lead_type": {
    "key": "veterans",
    "label": "Veterans"
  },
  "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 — custody_*, copied_from_lead_id, listing_id, purchased_from_listing_id, pool_listed_at, resale_owner_id, purge_hold_at, scrub_*, last_inbound_preview.

policy

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.
  • POST /api/v1/policiesRecord a sale on a lead your key's creator owns: {lead_id, ap_cents, commission_pct, close_date, …}. The lead closes, as on the screen.
  • PATCH /api/v1/policies/{id}Change a sale your key's creator owns.

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

FieldTypeNotes
idstringThe policy id.
lead_idlead idThe lead it was sold to.
owner_idagent idThe agent who owns the record (an agent id).
ap_centsinteger (cents)Annual premium (cents).
advanced_pay_centsinteger (cents)Advance paid (cents).
commission_centsinteger (cents)Commission (cents).
commission_pctnumber or nullCommission percent (two decimals).
face_amount_centsinteger (cents) or nullFace amount (cents).
carrier_namestring or nullCarrier.
carrier_productstring or nullCarrier product.
policy_numberstring or nullPolicy number.
policy_stagestringWhere the policy stands (submitted, issued, paid, lapsed, …).
policy_stage_attimestampWhen it reached that stage.
close_datedateThe sale date.
effective_datedate or nullThe policy effective date.
sold_reasonstring or nullWhy it sold, as noted.
policy_notestring or nullThe agent's note on the policy.
client_first_namestring or nullThe insured's first name, when not the lead.
client_last_namestring or nullThe insured's last name, when not the lead.
call_idcall id or nullThe call it closed on.
customobjectAgency policy field values, keyed by field key. Health-shaped fields are never included.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed.
Request
curl https://www.buildezpz.com/api/v1/policies/pl_3c4d5e6f-0000-4000-8000-0000000b0011 \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

appointment

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

  • GET /api/v1/appointmentsList appointments.
  • GET /api/v1/appointments/{id}Get one appointment.
FieldTypeNotes
idstringThe appointment id.
lead_idlead idThe lead it is with.
owner_idagent idThe agent who owns the record (an agent id).
starts_attimestampStart.
ends_attimestampEnd.
timezonestring or nullThe IANA time zone it was booked in.
statusscheduled | cancelled | completed | no_showIts state.
outcomestring or nullWhat happened at the meeting.
titlestring or nullTitle.
notesstring or nullNotes.
sourcestring or nullHow it was booked.
created_byagent id or nullWho booked it (an agent id).
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed.
Request
curl https://www.buildezpz.com/api/v1/appointments/ap_4d5e6f70-0000-4000-8000-0000000a1101 \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

call

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

  • GET /api/v1/callsList calls.
  • GET /api/v1/calls/{id}Get one call.
FieldTypeNotes
idstringThe call id.
lead_idlead id or nullThe lead on the call, when known.
owner_idagent idThe agent who owns the record (an agent id).
directionstringinbound or outbound.
statusstringThe call state (ringing, in_progress, completed, no_answer, …).
started_attimestamp or nullWhen it started.
answered_attimestamp or nullWhen it was answered.
ended_attimestamp or nullWhen it ended.
duration_secinteger or nullTalk time in seconds.
voicemailbooleanA voicemail was left or taken.
from_numberstringFrom.
to_numberstringTo.
caller_namestring or nullCaller name, when known.
placed_by_actor_idagent id or nullWho placed it, when not the owner (an agent id).
answered_bystring or nullWho picked up (human or machine), when detected.
recording_duration_secinteger or nullRecording length in seconds.
has_recordingbooleanA recording exists and has not been purged.
transcriptionstring or nullThe call transcript, when one was made.
recording_linkstring or nullA stable link to the audio while it exists: GET it with a key holding calls.listen for the call's owner and it answers 302 to a fresh short-lived file link (404 once the audio is gone). Null without calls.listen, or when there is no recording.
created_attimestampWhen the record was created.
Request
curl https://www.buildezpz.com/api/v1/calls/cl_5e6f7081-0000-4000-8000-0000000ca111 \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

message

A text message to or from a lead.

  • GET /api/v1/messagesList text messages.
FieldTypeNotes
idstringThe message id.
lead_idlead id or nullThe lead, when known.
owner_idagent idThe agent who owns the record (an agent id).
directionstringinbound or outbound.
bodystringThe text.
statusstringDelivery state.
from_numberstringFrom.
to_numberstringTo.
num_mediainteger or nullAttached media count.
send_originstring or nullWhat sent it (manual, automation, …).
sent_by_kindstring or nullowner, delegate or echo.
sent_by_actor_idagent id or nullWho sent it, when not the owner (an agent id).
read_attimestamp or nullWhen the agent read it.
created_attimestampWhen the record was created.
Request
curl "https://www.buildezpz.com/api/v1/messages?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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, send_subkind, workflow_id; billing — num_segments.

agent

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.

FieldTypeNotes
idstringThe agent id.
full_namestring or nullFull name.
display_namestring or nullThe name they go by.
business_namestring or nullTheir business name.
emailstringEmail.
phonestring or nullPhone.
agency_idagency id or nullTheir agency.
roleagency_owner | agency_admin | agency_assistant | member or nullTheir seat in the agency; null when they hold none.
manager_idagent id or nullTheir upline manager.
npnstring or nullNational Producer Number.
timezonestring or nullIANA time zone.
work_statestring or nullHome work state.
avatar_urlstring or nullAvatar image URL.
statusstringAccount status.
customobjectAgency agent field values, keyed by field key. Health-shaped fields are never included.
created_attimestampWhen the record was created.
Request
curl https://www.buildezpz.com/api/v1/agents/ag_1a2b3c4d-0000-4000-8000-0000000a6e01 \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

role

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

  • GET /api/v1/rolesList your agency's custom roles.
FieldTypeNotes
idstringThe role id.
agency_idagency idThe defining agency.
namestringName.
descriptionstringDescription.
switchesobjectSwitch key → the reaches it grants (a data switch) or true (an agency-wide switch).
push_modeoffered | suggested | extendable | locked or nullPushed to the agencies below: offered, suggested, extendable or locked; null = not pushed.
statusdraft | live | retireddraft, live or retired.
created_attimestampWhen the record was created.
Request
curl "https://www.buildezpz.com/api/v1/roles?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.kit": true
      },
      "push_mode": null,
      "status": "live",
      "created_at": "2026-09-01T15:00:00Z"
    }
  ],
  "next_cursor": null
}

Never exposed: internal — grants, created_by.

field

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

  • GET /api/v1/fieldsList your agency's custom fields.
FieldTypeNotes
idstringThe field id.
agency_idagency idThe defining agency.
objectlead | policy | agentWhat it is on.
keystringThe key its values appear under in custom.
labelstringLabel.
typestringField type (text, number, date, select, multi_select, checkbox, …).
optionsarrayChoices {value, label} for a pick field.
requiredbooleanRequired.
helpstringHelp text.
positionintegerDisplay order.
push_modeoffered | suggested | extendable | locked or nullPushed to the agencies below; null = not pushed.
statusdraft | live | retireddraft, live or retired.
created_attimestampWhen the record was created.
Request
curl "https://www.buildezpz.com/api/v1/fields?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

stage

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

  • GET /api/v1/stagesList your agency's stages.
FieldTypeNotes
idstringThe stage id.
agency_idagency idThe defining agency.
keystringKey.
labelstringLabel.
maps_tostringThe fixed disposition it counts as.
tonestring or nullDot colour.
positionintegerDisplay order.
push_modeoffered | suggested | extendable | locked or nullPushed to the agencies below; null = not pushed.
statusdraft | live | retireddraft, live or retired.
created_attimestampWhen the record was created.
Request
curl "https://www.buildezpz.com/api/v1/stages?limit=1" \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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.

agency

The agency itself and where it sits in the tree.

  • GET /api/v1/agencyGet your agency.
FieldTypeNotes
idstringThe agency id.
namestringName.
parent_idagency id or nullThe agency above it, if any.
tierstringAgency kind (portal, enterprise, external, spinoff).
created_attimestampWhen the record was created.
Request
curl https://www.buildezpz.com/api/v1/agency \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "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*.

kpi_day

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.
FieldTypeNotes
idstringThe day id: kd_<agent uuid>_<date>.
agent_idagent idThe agent.
datedateThe day, in the agent's time zone.
dialsintegerDials.
contactsintegerContacts.
appointments_setintegerAppointments booked.
appointments_heldintegerAppointments held.
presentationsintegerPresentations.
closesintegerCloses.
texts_sentintegerTexts sent.
talk_secondsintegerTalk time (seconds).
leads_receivedintegerNew leads received.
ap_centsinteger (cents)Annual premium closed (cents).
spend_centsinteger (cents)Ad and lead spend (cents).
lead_cost_centsinteger (cents)The summed cost of the leads received (cents).
cost_per_lead_centsinteger (cents) or nullDERIVED: spend_cents ÷ leads_received, rounded; null when no leads.
cost_per_close_centsinteger (cents) or nullDERIVED: spend_cents ÷ closes, rounded; null when no closes.
Request
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_…"
Response
{
  "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.

sale

A sale posted to the agency's book of business, with the agent who posted it. Read-only, oldest change first: poll GET /api/v1/sales with the next_cursor you got last time to get every new, changed or deleted sale once, and upsert each by id. Changes appear after about 10 seconds. A deleted sale comes back with deleted: true. An API key sees the sales posted after it was created.

  • GET /api/v1/salesEvery sale on your agency's book, oldest change first. Unlike other lists, next_cursor is never null after your first sale: store it and pass it back as cursor to get only what is new, changed or deleted since. Fewer rows than limit means you are caught up. Changes appear after about 10 seconds. A key sees sales posted after it was created. Needs Team production at Agency reach.
FieldTypeNotes
idstringThe sale id.
agent_emailstringThe agent's sign-in email, lower-cased.
agent_contact_emailstring or nullThe agent's contact email, when they set one apart from the sign-in email.
agent_first_namestring or nullThe first word of the agent's full name. EZPZ stores one full name; this is a split of it. Null when the name is blank.
agent_last_namestring or nullThe rest of the agent's full name after the first word. Null when the name is one word or blank.
annual_premium_centsinteger (cents)Annual premium (cents): the monthly premium × 12.
carrierstring or nullThe carrier.
productstring or nullThe product within the carrier.
sale_datedateThe sale date the agent entered; when none, the day it was posted (Mountain time).
statusstringWhere it stands, as entered: Submitted, Submitted - Pending Requirements, Packet Received, Issue Paid, Canceled, Declined, Lapsed or Chargeback. Empty when none is set yet.
countedbooleanIt counts toward premium totals: a status is set and it is not Canceled, Declined, Lapsed or Chargeback. Always false when deleted.
created_attimestampWhen the record was created.
updated_attimestampWhen the sale last changed; on a deleted sale, when it was deleted.
deletedbooleanThe sale was deleted. Its other fields are the last values it had.
Request
curl https://www.buildezpz.com/api/v1/sales \
  -H "Authorization: Bearer ezpz_live_…"
Response
{
  "object": "list",
  "data": [
    {
      "object": "sale",
      "id": "sl_d6e7f809-0000-4000-8000-00000005a1e1",
      "agent_email": "sam.okafor@example.com",
      "agent_contact_email": null,
      "agent_first_name": "Sam",
      "agent_last_name": "Okafor",
      "annual_premium_cents": 102000,
      "carrier": "Mutual of Omaha",
      "product": "Living Promise",
      "sale_date": "2026-09-30",
      "status": "Submitted",
      "counted": true,
      "created_at": "2026-09-30T18:04:11.204518+00:00",
      "updated_at": "2026-09-30T18:04:11.204518+00:00",
      "deleted": false
    }
  ],
  "next_cursor": "WyIyMDI2LTA5LTMwVDE4OjA0OjExLjIwNDUxOCswMDowMCIsImQ2ZTdmODA5LTAwMDAtNDAwMC04MDAwLTAwMDAwMDA1YTFlMSJd"
}

Never exposed: sensitive — client_name, state; internal — lead_type, external_id, month_label, month_order, row_order, discord_posted_at, effective_date*, fi_date, landed_at, submitted_date, canceled_at; billing — commission_percent.

onboarding_call

An onboarding call someone booked on one of the agency's onboarding pages (Desk ▸ Booking). Sent as the onboarding_call.booked webhook; there is no /api/v1 route for it yet. A key gets it when it holds team.production at a reach covering the whole agency (the sales feed's rule).

Webhook only: subscribe an endpoint to `onboarding_call.booked`. No /api/v1 route yet.

FieldTypeNotes
idstringThe onboarding call id.
full_namestringThe name the person typed when they booked.
emailstringThe email they typed, lower-cased.
phonestringThe phone they typed, as typed.
member_emailstring or nullSet when the email is an agency member's: the member it matched. Null for someone who has not joined.
host_emailstringThe sign-in email of the staff member whose page it was booked on, lower-cased. They host the call.
starts_attimestampWhen the call starts.
ends_attimestampWhen the call ends.
timezonestringThe page's time zone (an IANA name, e.g. America/Chicago).
meet_linkstring or nullThe Google Meet link, when the calendar made one.
statusbooked | done | no_show | cancelledWhere it stands: booked, then done, no_show or cancelled.
created_attimestampWhen the record was created.
updated_attimestampWhen the record last changed.
Shape
{
  "object": "onboarding_call",
  "id": "oc_e7f8091a-0000-4000-8000-0000000ca11b",
  "full_name": "Jordan Lee",
  "email": "jordan.lee@example.com",
  "phone": "(555) 010-4477",
  "member_email": "jordan.lee@example.com",
  "host_email": "sam.okafor@example.com",
  "starts_at": "2026-10-01T16:00:00+00:00",
  "ends_at": "2026-10-01T16:30:00+00:00",
  "timezone": "America/Chicago",
  "meet_link": "https://meet.google.com/abc-defg-hij",
  "status": "booked",
  "created_at": "2026-09-30T18:04:11.204518+00:00",
  "updated_at": "2026-09-30T18:04:11.204518+00:00"
}

Never exposed: vendor ids — google_event_id; internal — agency_id, host_user_id, recruit_id, status_changed_at, status_changed_by.

Custom endpoints

Custom endpoints

An agency can save its own read in Studio › API & webhooks: one kind of data, up to five filters, the fields to send and a name. It answers at its own URL.

GET /api/v1/views/<slug>
Authorization: Bearer ezpz_live_…
  • It runs as your key. You get only the records your key's roles reach, and only the fields your key may see.
  • The endpoint is the query. Send only cursor, limit and the time floor of its data: updated_since for leads, since for every other kind but sales. Anything else answers 400 unknown_param.
  • Some filters run after a page is read, so a page can hold fewer items than limit, even none. Keep paging until next_cursor is null.
  • An endpoint on sales pages like GET /api/v1/sales: store next_cursor and poll with it.
  • A slug your agency has not saved, or a key the endpoint does not let in, answers 404 not_found.
Inbound URLs

Inbound URLs

An agency can make a private URL in Studio › API & webhooks for an outside system — a lead vendor, a form tool, Zapier — to post leads to. It needs no key: the URL is the secret. Keep it private.

POST https://www.buildezpz.com/api/in/<token>
Content-Type: application/json

{ "first_name": "Ann", "phone": "512-555-0100", "email": "ann@example.com" }
  • Send one lead per request: one JSON object, up to 64 KB. The agency maps your fields onto its leads in Studio, so send your own shape.
  • Each post needs a phone or an email. A lead the agency already has (same phone, then same email) is matched, not made twice.
  • Until the agency signs its consent statement for the URL, every lead is held: it lands, and nothing texts it. Once it is signed, every lead with a phone can get texts. You may also send the consumer's own consent words and the time they gave it; they are kept as proof.
  • Answers: 201 created · 200 matched · 202 held for consent, each with lead_id and result. 400 not JSON or unreadable · 413 over 64 KB · 422 needs_phone_or_email · 429 too many (wait the seconds in Retry-After) · 404 an unknown, paused or replaced URL.
  • Limits: 120 posts a minute and 10,000 a day per URL.
Webhooks

Events

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

EventWhen
lead.createdA lead was added.
lead.updatedA lead's fields or agency field values changed.
lead.stage_changedThe disposition or the agency stage moved.
lead.movedThe lead moved to another agent.
lead.deletedA lead was deleted.
policy.createdA policy was recorded.
policy.updatedA policy changed.
policy.soldA policy was sold (inserted, or its stage or close date set).
policy.deletedA policy was deleted.
appointment.bookedAn appointment was booked.
appointment.rescheduledIts time moved.
appointment.outcomeIts outcome or status was set.
appointment.deletedAn appointment was deleted.
call.startedA call began.
call.endedA call ended.
message.sentAn outbound text was sent (direction outbound).
message.receivedAn inbound text arrived (direction inbound).
onboarding_call.bookedSomeone booked an onboarding call on one of the agency's onboarding pages.
kpi_day.updatedAn agent's day changed; keyed by (agent, date).

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

Payload
{
  "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",
      "lead_type": {
        "key": "veterans",
        "label": "Veterans"
      },
      "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.

Delete payload
{
  "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.

Verify a signature

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.

Node
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);
}

Retries

  • 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.
AI agents · MCP

Connect an AI agent

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.

Server URL
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. A small change runs when you say yes in the chat (confirm_action) or press Approve in EZPZ. A big change, such as a sale or a lead with text consent, runs only when you press Approve in EZPZ: the agent's own confirm is refused with approve_in_ezpz. A key used as the bearer has no person to ask, so its big changes are refused (needs_person). Each change runs once and is logged.
  • Autopilot. Off by default. Turn it on for a key in Studio, or for your own connection in Settings › Apps, and small proposals run at once. A big change never runs on autopilot. 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.

Tools

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

ToolKindWhat it doesSame as
ezpz_list_leadsReadList leads, newest first.GET /api/v1/leads
ezpz_get_leadReadOne lead.GET /api/v1/leads/{id}
ezpz_list_policiesReadList policies, newest first.GET /api/v1/policies
ezpz_get_policyReadOne policy.GET /api/v1/policies/{id}
ezpz_list_appointmentsReadList appointments, newest first.GET /api/v1/appointments
ezpz_get_appointmentReadOne appointment.GET /api/v1/appointments/{id}
ezpz_list_callsReadList calls, newest first (a transcript only where the connection may listen).GET /api/v1/calls
ezpz_get_callReadOne call.GET /api/v1/calls/{id}
ezpz_list_messagesReadList text messages, newest first.GET /api/v1/messages
ezpz_list_agentsReadList the agents this connection reaches.GET /api/v1/agents
ezpz_get_agentReadOne agent.GET /api/v1/agents/{id}
ezpz_get_agencyReadThe agency this connection belongs to.GET /api/v1/agency
ezpz_list_rolesReadThe agency’s roles.GET /api/v1/roles
ezpz_list_salesReadThe agency’s sales as a feed, oldest change first.GET /api/v1/sales
ezpz_list_kpi_daysReadDaily activity totals per agent.GET /api/v1/kpi_days
ezpz_list_fieldsReadThe agency’s own fields on leads, policies and agents.GET /api/v1/fields
ezpz_list_stagesReadThe agency’s lead stages.GET /api/v1/stages
propose_create_leadProposes a changePropose adding a lead to the connection’s own book.POST /api/v1/leads
propose_update_leadProposes a changePropose changing a lead’s details, agency fields or stage.PATCH /api/v1/leads/{id}
propose_add_noteProposes a changePropose adding a dated note to a lead.POST /api/v1/leads/{id}/notes
propose_tag_leadProposes a changePropose adding or removing tags on a lead.POST /api/v1/leads/{id}/tags
propose_book_appointmentProposes a changePropose booking an appointment with a lead on its agent’s calendar.POST /api/v1/leads/{id}/appointments
propose_create_policyProposes a changePropose recording a sale (a policy) on one of the user’s own leads.POST /api/v1/policies
propose_update_policyProposes a changePropose changing one of the user’s own policies.PATCH /api/v1/policies/{id}
confirm_actionPending actionsRun a pending action the user approved.—
cancel_actionPending actionsDrop a pending action the user declined.—
list_pending_actionsPending actionsThis connection’s pending actions that have not expired.—

Set up your agency with your AI

An agency's owner or admin can let their own AI set up the agency. On the consent screen, tick Set up my agency. That adds the ezpz.setup scope and the tools below, for that agency only.

  • Small changes run at once. Each one shows in Studio › History, where the owner can Undo it.
  • Big changes ask first. A tool marked “Asks first” stores a pending action. You press Approve in EZPZ, in the assistant's panel. If your plan has no assistant, the AI asks you in its chat and runs confirm_action only when you say yes.
  • Disconnect any time in Studio › Apps & AI.
ToolStepKindWhat it does
setup_statusThe pathReadWhere the agency is on its setup: first Get running (the cards before Go live), then Go live (go_live_done), then Make it yours — the queue, in four phases and by how many people each item reaches inside a phase, and the next item. Also each path step, done or not, skipped or not.
setup_briefThe pathReadThe Get running cards (the quick setup questions), the answers so far and the setup parts they draft.
setup_brief_submitThe pathChangeSave the owner’s Get running answers.
setup_list_changesThe pathReadThe agency’s setup changes, newest first, each with who made it and whether it can be undone.
setup_skip_stepThe pathChangeSkip a setup step for now, put it or a Make it yours item off until later, or bring it back.
setup_undoThe pathChange (asks first for a big one)Undo one setup change from setup_list_changes.
setup_get_brandBrand and web addressReadThe live brand, the draft waiting (if any) and the past versions.
setup_check_domainBrand and web addressReadThe agency’s web address: its status and the DNS records it still needs, as last checked.
setup_save_brand_draftBrand and web addressChangeSave brand changes as a DRAFT. Members see nothing until it is published.
setup_discard_brand_draftBrand and web addressChangeThrow away the brand draft. The live brand stays.
setup_publish_brandBrand and web addressAsks firstPublish the brand draft: every member sees it.
setup_revert_brandBrand and web addressAsks firstPut an earlier brand version back live.
setup_connect_domainBrand and web addressAsks firstConnect the agency’s own web address. The answer gives the DNS records to add.
setup_set_contactContact infoChangeSet the agency’s contact details and the welcome line new agents see. Only the keys given change.
setup_list_fieldsLead fields and stagesReadThe agency’s lead, policy and agent fields, and its lead stages.
setup_add_fieldsLead fields and stagesChangeAdd up to 20 fields at once. Each one shows on the leads, policies or agents it is for.
setup_update_fieldLead fields and stagesChangeChange one of the agency’s own fields: its label, hint, choices or whether it is required.
setup_set_stagesLead fields and stagesChangeSet the agency’s whole list of lead stages, in order. Every fixed stage needs at least one.
setup_list_rolesWho can do whatReadThe agency’s roles, what each one lets people do, who holds it, and the members. builtIns are Owner, Admin, Assistant and Member: each has its id (builtin:<tier>), what it grants here (grants), its defaults (defaultGrants), changed, and editable — true when this person may change it (only the agency owner; the Owner never).
setup_save_roleWho can do whatChange (asks first for a big one)Create a role, or change one, with the switches it turns on. A role grants nothing until someone holds it. To change what the built-in Member tier can do, pass role_id builtin:member and its full new switches. Admin and Assistant are the agency’s own starter roles: change them by their own role_id.
setup_reset_roleWho can do whatAsks firstPut the built-in Member tier back on today’s defaults.
setup_assign_roleWho can do whatAsks firstGive a member a role.
setup_get_comp_chartPay chartReadThe pay chart in force, the draft waiting and its open questions.
setup_save_comp_draftPay chartChangeChange the draft pay chart’s levels: rank names, codes, tracks and requirements, or how agents between levels are paid.
setup_publish_comp_chartPay chartAsks firstPublish the draft pay chart: new deals are paid from it.
setup_revert_comp_chartPay chartAsks firstPut an earlier pay chart version back.
setup_list_courseOnboarding courseReadThe agency’s onboarding course: its sections and their steps.
setup_add_course_itemsOnboarding courseChangeAdd up to 20 steps to the onboarding course, in a section that exists or a new one.
setup_install_starter_courseOnboarding courseChangeInstall the starter onboarding course. Only when the course is empty.
setup_add_trainingsWeekly trainingsChangeAdd up to 20 weekly trainings.
setup_update_trainingWeekly trainingsChangeChange one weekly training.
setup_get_kitStarter kitReadThe agency’s starter kit: each item, shared or not, and its draft.
setup_save_kit_itemStarter kitChangeCreate a kit item, or save a new draft of one. Nobody gets it until it is shared.
setup_share_kit_itemStarter kitChangeShare a kit item for the first time: every agent gets their copy.
setup_update_kit_itemStarter kitAsks firstPush the new draft of an already-shared kit item to every agent who has it.
setup_get_join_linkInvite your teamReadThe agency's two links. team_link is the one to send working agents: they sign up for EZ Leads and join the agency right away. recruit_link is the onboarding form for people being recruited and licensed. Share them exactly as returned.
setup_list_clone_targetsExtrasReadThe agencies below this one that its setup can be copied to.
setup_clone_setupExtrasAsks firstCopy this agency’s setup to an agency below it (or send it an offer to accept).
setup_post_announcementExtrasAsks firstPost an announcement to every member.
setup_distribute_leadsExtrasAsks firstHand out leads from the agency’s lead inventory: the newest count, round-robin or to one agent.
Apps

Embedded apps

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.
Browser
// 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);
Changes

Versioning

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.

What is EZPZ? EZPZ is a platform for licensed insurance agents and agencies, with two connected halves. EZ LEADS is a customer relationship management (CRM) platform where agents generate and manage their own exclusive leads, follow up by call, text, and email, book appointments, and automate their follow-up workflow. PZ PORTAL is the agency side — recruiting, onboarding, licensing, and production tracking in one place. Agents can connect their own Google account so booked appointments land on their Google Calendar and workflow emails send from their own Gmail — send-only access, with consent records and a one-click unsubscribe link on every email.