How clients text receipts to their bookkeeper over iMessage

Who uses iMessage for receipt collection?

iMessage receipt collection fits bookkeepers, fractional CFOs, small CPA firms and enrolled agents whose small-business and freelance clients live on their iPhone but rarely open the client portal. ZeroSettle is an iMessage API: a real phone number on real iMessage, running on Apple hardware we operate for you, that your code texts customers from and hears back on through a bearer token and signed webhooks.

The problem is timing. A receipt is easy to photograph at the register and hard to find three weeks later, when month-end close turns into chasing shoeboxes and tax season adds daily "is my return done?" calls. Receipt capture is one of the operations workflows in 50 ways businesses use iMessage.

How iMessage receipt collection works, step by step

Clients text receipts, your webhook files each photo and answers with a 👍, and at month end the bookkeeper texts only the charges still missing a receipt.

1. The client opts in and saves the number. The engagement letter names the firm's number and asks for consent to texts about the books. ZeroSettle shares the firm's name and photo with the first message the firm sends. Leave the portal link out of that welcome: a link in a first message to someone who has never texted the number shows as plain text until the client replies.
2. The client texts each receipt as it happens, one photo per text, with an optional caption ("lunch with the Acme client"). Each reaches your webhook as a signed message.received event with kind: "image" and the caption as text; HEIC arrives as JPEG.
3. Your webhook fetches the image from GET /api/imessage/messages/{id}/image with the same bearer token, runs OCR or passes it to your expense tool, and files merchant, date and amount under the client.
4. Your server confirms with a 👍 through POST /api/imessage/reactions with "reaction": "like". To the client, a receipt without one hasn't been logged.
5. As charges post, your ledger matches them to filed receipts, and at month end the bookkeeper texts only the charges still missing one, from code (POST /api/imessage/send) or the ZeroSettle console. The 👍 means "filed", not "matched": a receipt texted at the register usually arrives before its charge reaches the bank feed.
6. In tax season, the same thread carries the milestones (ready to sign, e-filed, accepted), with no daily cap on an ongoing conversation; on every plan, a third unanswered update waits for a reply. Sensitive documents go through your portal, whose link is tappable now that the client has texted.

A client with no paper receipt (a parking meter, a cash tip) can send a voice note; it arrives as an .m4a file for a transcription step like the one that turns technicians' voice notes into job reports. Insurance claim photos use the same inbound-photo pattern.

Example conversation: receipt collection

This thread shows a receipt filed mid-month, then the September close, as the firm sees them in the ZeroSettle console.

Setup: a receipt-capture webhook

A receipt-capture webhook is one route that checks ZeroSettle's signature, answers 2xx at once, then fetches each inbound photo, files it and reacts with like. The verifier is the one in the ZeroSettle webhook docs; how webhook events, signing and retries work covers the rest.

# receipts.py: run with  uvicorn receipts:app --port 8100
import asyncio, hashlib, hmac, json, os, time
import httpx
from fastapi import BackgroundTasks, FastAPI, Request, Response

BASE = "https://portal.zerosettle.io"
TOKEN, SECRET = os.environ["ZEROSETTLE_TOKEN"], os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
app = FastAPI()
seen: set[tuple[int, str]] = set()            # use your database in production

def file_receipt(handle: str, img: bytes, caption: str) -> bool:
    return False   # your OCR or expense tool: True once it's filed

def verify(header: str, raw: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, v1 = int(parts["t"]), parts["v1"]
    except Exception:
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(SECRET.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

async def call(zs: httpx.AsyncClient, path: str, body: dict) -> None:
    r = await zs.post(path, json=body)
    while r.status_code == 429 and r.json()["error"]["code"] == "line_busy":
        await asyncio.sleep(2)                # one send at a time per number
        r = await zs.post(path, json=body)

async def handle(m: dict) -> None:
    text = (m.get("text") or "").strip()
    async with httpx.AsyncClient(base_url=BASE, timeout=90,
                                 headers={"Authorization": f"Bearer {TOKEN}"}) as zs:
        if m.get("image"):                    # a receipt photo
            img = (await zs.get(m["image"]["url"])).content
            caption = "" if text == "📷 Photo" else text
            if await asyncio.to_thread(file_receipt, m["handle"], img, caption):
                await call(zs, "/api/imessage/reactions",
                           {"message_id": m["id"], "reaction": "like"})
        elif m.get("kind") == "image" or not text:   # no file: failed photo, lone PDF or video
            await call(zs, "/api/imessage/send", {"to": m["handle"], "text":
                "That one didn't come through. Could you send it as a photo or a screenshot?"})

@app.post("/webhook")
async def webhook(req: Request, tasks: BackgroundTasks):
    raw = await req.body()
    if not verify(req.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    ev = json.loads(raw)
    m = ev.get("message")
    if ev["event"] != "message.received" or m is None or (m["id"], ev["event"]) in seen:
        return {"ok": True}                   # echoes of your own sends, and retries
    seen.add((m["id"], ev["event"]))
    tasks.add_task(handle, m)                 # answer 2xx now; OCR runs after
    return {"ok": True}

Register the route with PUT /api/imessage/webhook and store the signing secret, which is shown once. ZeroSettle retries a failed delivery after 1, 5 and 20 seconds with the same message.id and event, hence the dedupe. The call helper covers a client who texts ten receipts at once: ZeroSettle sends one message at a time per number, a 👍 queued about 12 seconds returns 429 line_busy, and the docs say to retry after 2 seconds. A photo your OCR can't read gets no 👍 and waits in the console, like any plain question.

Also file each image in your own document system: ZeroSettle says only that messages are kept "indefinitely for now", and the IRS lists receipts among a business's supporting documents and says "all requirements that apply to hard copy books and records also apply to electronic records."

Three ways a receipt goes missing

• Several photos in one message: ZeroSettle delivers only the first, so clients send one receipt per text.
• A PDF or a video: no file arrives. Sent alone it comes through empty, and the handler asks for a photo or a screenshot; sent with words, it reads as a plain text and waits for the bookkeeper.
• A photo whose download never finished: image is null, and the same reply asks for it again.

Limits and consent for receipt collection

Receipt collection rarely meets ZeroSettle's limits: inbound messages are never limited, and only the firm's first message to a client who has never texted counts as a new contact.

Source: ZeroSettle iMessage API docs, "Errors, limits, and compliance". The day runs 3 AM to 3 AM Eastern.

The math: on Pro, a firm moving 60 clients onto the number can welcome 5 a day, so all 60 within 12 days. Clients who text first, from a link in the engagement letter, never count (see how to get customers to text you first), and the receipts, milestones and tapbacks that follow use none of the allowance. On every plan, a quiet client gets the missing-receipts text and one nudge, then nothing until they send something back (a tapback counts).

Keep the signed engagement letter as the consent record, and have the first text say who is writing. A pitch for a tax-planning package is likely promotional: treat it as needing marketing consent and, per ZeroSettle's docs, never send it before 8 am or after 9 pm in the client's time zone. This isn't legal advice.

A text with the word STOP in it, even "I'll stop by Friday with the folder", or a clear request like "take me off your list", opts the client out of every number on the firm's account. Their receipts still arrive, but each 👍 and text to them returns 403 recipient_opted_out until they text START as the whole message; flag that error for a phone call. See how STOP works on a ZeroSettle line.

When ZeroSettle is not a fit for receipt collection

ZeroSettle is the wrong tool for receipt collection when documents are sensitive, clients use Android, or paperwork arrives as files.

• Tax forms, SSNs or account numbers: use your secure portal; ZeroSettle's terms say message content may not be encrypted.
• Mostly Android clients: there is no SMS fallback, so keep email or portal upload for them. ZeroSettle checks whether a number is on iMessage before the first message and sends nothing if it isn't.
• Multi-page PDFs and statements: files don't arrive, only photos and voice notes.
• A native integration with your accounting software: ZeroSettle has none. Build it on the webhook, in code or with Zapier, n8n or Make.
• Proof a client read the missing-receipts text: the API reports message.sent (the message left the line), not delivered or read.

How much does iMessage receipt collection cost?

On ZeroSettle's side, receipt collection costs the plan price: there are no per-message fees and messages are unlimited on both plans, so tax season costs the same as August.

Pro has a 30-day money-back guarantee and can be cancelled anytime; AI credits apply only to the hosted AI agent, which this workflow doesn't use. See ZeroSettle plans and pricing, read the iMessage API docs, or get a number.