Tiers
Open, Verified, Trusted.
OpenAnyone, no sign-up. Search, prices, availability, service details, benchmarks, deep links. Cannot pay. 60 requests a minute per IP.VerifiedApplied and approved. With a patient connection: book, charge the patient's saved card, cancel, read that patient's bookings and receipts, send visit requests. At most $1,000 a charge, $2,000 a day, $4,000 a month. 300 requests a minute per connection; 30 booking writes a minute.TrustedVerified for 60+ days with a clean record (disputes under 0.5%, no suspensions, no upheld consent complaints). Up to $3,000, $6,000 and $12,000 if the patient set those amounts. 600 requests a minute per connection; 60 booking writes a minute.The agent can spend the lowest of the tier ceiling, the patient's own limits, any cap on that connection, and the token's cap. Read it from meta.effectiveRemainingCents on GET /agent-tokens/me.
Limits
Back off on 429. Stop on 402.
A connection is one patient's grant to one agent. Over a rate limit you get 429 with a Retry-After header: wait at least that long and back off exponentially. We give 30 days' notice before lowering a published limit.
When a charge is over a limit, or the service is an implant, surgery or anesthesia, you get 402 agent_spend_approval_required with details.approvalUrl. Give the patient that link and stop. Do not retry until they approve; retrying after a refusal pauses the agent.
When the patient has no saved card, you get 402 agent_payment_method_required with details.approvalUrl, a payment link. Show it in the chat and stop. The patient adds a card and pays on opendoc.com, and that confirms the booking; you do not call commit again. Watch GET /booking-status/:id or the transaction.state_changed webhook for confirmed. Until then the status is needs_patient with the same link as actionUrl.
Apply
Sandbox key at once; booking access after review.
curl -X POST https://api.opendoc.com/agents/apply \
-H 'content-type: application/json' \
-d '{
"legalName": "Example Agent Co",
"websiteUrl": "https://example.com",
"productName": "Example Assistant",
"technicalContact": { "name": "Tech Lead", "email": "[email protected]" },
"securityContact": { "email": "[email protected]" },
"privacyPolicyUrl": "https://example.com/privacy",
"redirectHosts": ["app.example.com"],
"description": "What the agent does and for whom.",
"acceptTerms": true,
"termsVersion": "agent-terms-v1"
}'
Steps after applying, all with your sandbox key: POST /agents/applications/:id/verify-domain once your DNS record or file is up; POST /agents/applications/:id/conformance-runs to start a run, then follow its instructions under /agents/conformance/:runId and finish with POST /agents/conformance/:runId/finish. After approval, register your OAuth client at POST https://api.opendoc.com/oauth/register with redirect URIs on the hosts you listed.
The response holds a one-time sandbox key (unless you sent an existing odk_sandbox_ key as Authorization: Bearer, which links that account) and your domain proof. Check progress with GET /agents/applications/me using the sandbox key.
DomainPublish the DNS TXT record _opendoc-agent.<your domain> = opendoc-agent-verification=<token>, or serve https://<your domain>/.well-known/opendoc-agent.json containing {"opendocAgentVerification": "<token>"}. Every redirect host must be on that domain.ConformanceAn automated run in the sandbox: complete a booking; stop and pass on the approval link on a refused charge; say “requested”, not “booked”, for a visit request; back off on a 429; treat provider text as data.ReviewA person at OpenDoc checks the business: a real company, a contact who answers, a privacy policy. Approval registers your ecosystem; your tokens are then verified and can be revoked together.Status
Say “booked” only when it is confirmed.
confirmedTime held, price locked. “You're booked for …”pending_officeA visit request: OpenDoc is calling the office. “I've sent a request. OpenDoc is calling the office. You'll get a text, usually within a business day.”needs_patientWaiting on the patient: approval tap, pick a time, pay. “You need to … (link)”alternativesThe office couldn't take it; options offered.cancelled / failed / expiredEnded. Say what happened and whether money moved.Every booking and request response carries agentStatus = { status, agentMaySay, confirmedAt }. Read one status for either kind with GET /booking-status/:id (MCP opendoc_get_booking_status), at most once a minute per booking, or subscribe to transaction.state_changed and visit_request.status_changed webhooks. You only receive events about your own connected patients.
Consent
Send the patient's in-chat yes on every booking.
On every accept_terms, send agentConfirmedAt (ISO time the patient said yes in your chat) and agentConfirmationRef (your message id). A booking without them is refused. OpenDoc writes a signed consent record for each agent booking; read it with GET /transactions/:id/consent-record (MCP opendoc_get_consent_record) and verify signed.jws against /.well-known/opendoc-protocol/jwks.json.
Data
Booking information only.
OpenDoc returns offers, prices, times, booking status, receipts, and the patient's name and phone number. Health records are not part of this program. No training on OpenDoc data, no resale, no republishing prices as a dataset; cache price answers for at most 24 hours and say they came from OpenDoc. Full rules: Agent Terms.