PhonePick API & webhooks and PhonePick Connected today

Authentication

Make a key in PhonePick under Settings → API & MCP (an owner or admin, on Operations or Growth). Send it on every request:

Authorization: Bearer pp_live_…

A read-only key can call every GET; a read and write key can also create, change and pay. Keys are shown once, stored only as a hash, and stop working the moment they are revoked. The base address is https://www.phonepick.ai/api/v1. There is no browser access (no CORS): a key belongs on a server.

Conventions

• Money is whole cents, in fields ending _cents: "total_cents": 45000 is $450.00. A decimal such as "450.00" is refused rather than guessed at. The currency is the account's (USD or CAD) and is on every object.
• Dates are YYYY-MM-DD; times are ISO 8601 in UTC. "Overdue" is worked out on the business's own calendar date.
• Your ids: send external_id (your invoice or payment id). Sending the same one twice returns the record already there instead of making a duplicate, so a retry after a timeout is always safe.
• Idempotency-Key on any write: the same key and request within a day returns the first answer and acts once.
• Errors are {"error": {"type", "message", "errors"?}} with 401 (key), 403 (plan or read-only key), 404, 409 (e.g. voiding an invoice that has payments), 422 (invalid — errors names every problem) and 429 (over 300 requests a minute).
• Lists are {"object":"list","data":[…],"has_more","next_cursor"}; pass starting_after=<next_cursor> for the next page. limit is up to 100.

The invoice

{
  "object": "invoice", "id": "Xq3…", "number": "INV-1042", "external_id": "QB-1042",
  "status": "partially_paid",            // open | partially_paid | paid | void
  "overdue": true, "days_overdue": 13, "currency": "CAD",
  "total_cents": 45000, "paid_cents": 20000, "balance_cents": 25000,
  "customer": { "name": "Ana Ruiz", "phone": "+15195550101", "email": "ana@example.com" },
  "issue_date": "2026-09-15", "due_date": "2026-10-01",
  "items": [{ "description": "Furnace service", "quantity": 1, "unit_cents": 45000, "amount_cents": 45000 }],
  "notes": null, "pay_url": "https://www.phonepick.ai/i/…",
  "reminders_sent": 1, "last_reminded_at": "…", "source": "api",
  "created_at": "…", "updated_at": "…", "paid_at": null, "voided_at": null
}

pay_url is the invoice's own page: the customer sees it and, if Stripe is connected, pays what's left by card. It never expires. A mobile number is needed only for text reminders; an invoice without one is still tracked and payable.

The payment

{ "object": "payment", "id": "…", "invoice_id": "Xq3…", "kind": "payment",   // or "refund"
  "amount_cents": 20000, "currency": "CAD", "paid_on": "2026-10-10",
  "method": "etransfer",        // card | cash | cheque | etransfer | bank | other
  "reference": "CA-778", "note": null, "external_id": "PMT-88",
  "source": "api",              // manual | api | stripe
  "removed": false, "created_at": "…" }

A payment can't be more than the balance (a refund can't be more than what was paid). When the balance reaches zero the invoice is paid and reminders stop. Card payments made on the invoice's page arrive with source: "stripe", and a refund made in the business's Stripe dashboard arrives as a refund.

Endpoints

Keeping an ERP in step

Invoices in: send each one with PUT /invoices/external/{your id} whenever it is raised or changed. Payments out: either take webhooks (below) or poll GET /events?after=… and store next_cursor each time. The feed holds back the last five seconds, so a cursor never skips an event that was still being written.

curl -X PUT https://www.phonepick.ai/api/v1/invoices/external/INV-1042 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"number":"INV-1042","customer":{"name":"Ana Ruiz","phone":"+15195550101"},
       "total_cents":45000,"due_date":"2026-11-15"}'

Webhooks

Add an https address under Settings → API & MCP and pick the events (all, or any of invoice.created, invoice.updated, invoice.paid, invoice.voided, invoice.deleted, invoice.reminded, payment.created, payment.refunded, payment.deleted). Each event is POSTed as JSON — {"id","object":"event","type","created_at","data":{"object":…}}, with the invoice too on payment events — usually within a minute. Answer with any 2xx. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours; an address that has failed for three days is switched off, and the app says so.

Check every request. PhonePick-Signature: t=<unix time>,v1=<hex> is an HMAC-SHA256, with the address's signing secret, of t + "." + the raw body — the scheme Stripe uses:

// Node
const crypto = require("crypto");
function verified(header, rawBody, secret) {
  const p = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;          // replayed
  const want = crypto.createHmac("sha256", secret).update(`${p.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(want), b = Buffer.from(p.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

# Python
import hmac, hashlib, time
def verified(header, raw_body: bytes, secret: str) -> bool:
    p = dict(kv.split("=", 1) for kv in header.split(","))
    if abs(time.time() - int(p["t"])) > 300: return False
    want = hmac.new(secret.encode(), f'{p["t"]}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, p.get("v1", ""))

Use PhonePick-Event-Id to ignore a delivery you have already handled.

MCP: Claude, ChatGPT and other assistants

The MCP server is https://www.phonepick.ai/mcp (Streamable HTTP, the same key as a Bearer header). For a client that can only be given a link, https://www.phonepick.ai/mcp/<key> works too — treat that link as a password. Its tools: get_account, get_receivables_summary, list_invoices, get_invoice, list_changes, and with a write key create_invoice, update_invoice, record_payment, remove_payment, void_invoice and send_reminder. Tool inputs take dollars (450.00); results carry cents. Deleting an invoice is not offered to an assistant.

claude mcp add --transport http phonepick https://www.phonepick.ai/mcp \
  --header "Authorization: Bearer pp_live_…"