Agent Integration Guide

# How messaging works

Read this before you write your integration — it shapes your whole agent loop. Every webhook goes to your agent, and only your agent. RentAHuman never messages your end customer. RentAHuman receives requesterPhoneNumber only as server-side provenance and routing metadata. The ops team still communicates through you, the partner agent, rather than messaging the end customer directly.

• •Ops replies, status changes, payment links, and payment confirmations are all addressed to your agent — not your customer.
• •Your agent decides whether, when, and how to relay each update: verbatim, rephrased, summarized, batched, or withheld.
• •Nothing reaches your customer unless your agent sends it. A payment link in a webhook does nothing until you forward it.
• •Design your webhook handler as an agent turn — don't wire it straight through to your customer's channel.

#Fees & revenue share

An 18% platform fee is added on top of every payment link — your customer pays the task price × 1.18. Of that, 13% is RentAHuman's and 5% is revenue share credited to your account's wallet (the account that owns your API key) automatically when the customer pays. Your balance is visible at rentahuman.ai/account. In payloads, amountUsd is the total the customer pays and baseAmountUsd is the task price before the fee.

# Authentication

Send your partner API key on every request in the X-API-Key header. Keys start with rah_. Partner access is enterprise-gated: a valid key that is not enrolled in the partner program gets 403 — to become a partner, email [email protected] with the subject "Partner API". Keep the key server-side only. Errors return { "success": false, "error": "..." } with standard status codes. Writes (create + message) are limited to 30/minute and 300/hour; reads to 300/minute — on 429, back off for Retry-After seconds. High-throughput integrations can be moved to an automated tier with ~5x the standard per-key quotas, granted per key by RentAHuman admins (not self-serve) — email [email protected] to request it.

X-API-Key: rah_live_abc123

# Status lifecycle

received → needs_info → quoted → scheduled → in_progress → completed — with cancelled possible at any point.

# Example lifecycle

1. 1Customer texts your agent: "Can someone deep clean my apartment tomorrow evening? 2BR in the Mission."
2. 2Your agent calls POST /api/partner/v1/requests with task, the exact externalChatId, the customer's E.164 requesterPhoneNumber, location, dueBy, and a stable customerRef. It gets back a requestId with status received, and a partner.request.received webhook confirms it.
3. 3Ops finds a cleaner. A partner.message webhook arrives: "We can do 8pm tomorrow with a vetted cleaner for $120. Confirm?" — status is now quoted. Your agent relays this to the customer over iMessage.
4. 4Customer says "yes, book it." Your agent posts { "message": "Customer confirms 8pm tomorrow works." } to the request's messages endpoint.
5. 5A partner.payment_link webhook delivers a short checkout URL with amountUsd 141.60 (the $120 task price plus the 18% platform fee) and baseAmountUsd 120. Your agent decides to relay it and forwards the URL verbatim; the customer pays in the browser with no RentAHuman account, and your wallet is credited $6 rev share.
6. 6After checkout completes, a partner.payment_confirmed webhook arrives with the total paid and paidAt. Its request status remains quoted; payment confirmation does not advance the request lifecycle. Your agent promptly relays the confirmation to the customer.
7. 7partner.request.updated webhooks move the request through scheduled, in_progress, and finally completed. Your agent relays each update.

# Agent guidance

• •Always include dueBy when the customer gives any deadline, even a vague one ("tomorrow evening" becomes an ISO timestamp for tomorrow ~18:00 local).
• •Always send the exact externalChatId for the originating conversation; never collapse multiple customer chats into one source ID.
• •Send requesterPhoneNumber only in canonical E.164 form (for example +14155550100), and keep it out of logs, URLs, and public task text.
• •You decide whether to relay — RentAHuman never messages your customer. Every webhook is addressed to your agent; nothing reaches your customer unless you send it.
• •Relay payment links verbatim when you send them. paymentLinkUrl is already a short, trusted RentAHuman checkout link — never rewrite, shorten, or proxy it. Links expire in ~23 hours; if one goes stale, ask ops for a fresh one via the messages endpoint.
• •Relay payment confirmations promptly. Treat partner.payment_confirmed as the payment signal. Never infer payment from delivery of a payment link or from a customer's claim that they paid; wait for the event or verify the canonical payment-link status through the request endpoint.
• •One request per job. Use the messages endpoint for follow-ups on an existing job; don't create a duplicate request.
• •Use a stable customerRef per end customer or thread so ops and your agent can correlate follow-ups — it is echoed on every webhook.
• •Answer needs_info promptly — nothing moves until you reply.
• •Never invent status, pricing, or availability. Only relay what the API or a webhook actually said. If you don't know, say the ops team is on it.
• •Handle 429 by backing off for Retry-After seconds; requests are rate limited per partner account.