API & MCP docs

HandlemyAP is accounts payable as a service. Send it an invoice and it reads the document with AI, normalises it and lines it up in the owner’s queue — ready to be paid with PayPal in a tap. Nothing is paid automatically. Two ways to integrate:

REST API

Classic HTTP + JSON. Best for backends and webhooks — e.g. a platform paying its contractors.

MCP server

Model Context Protocol. Point an AI agent (Claude, etc.) at it and it can submit and track payables as tools.

Both surfaces call the exact same engine, so behaviour is identical. Base URL: https://handlemyap.com

Authentication

Create an API token in Settings → API tokens and send it as a bearer header. Every request is scoped to that token’s account.

Authorization: Bearer <your-token>

REST API /api/v1

Method	Path	What it does
POST	/api/v1/invoices	Submit a payable (JSON fields or a multipart file). Runs AI extraction.
GET	/api/v1/invoices	List your invoices, newest first.
GET	/api/v1/invoices/{id}	Fetch one invoice with its vendor and payments.
POST	/api/v1/invoices/{id}/extract	Run (or re-run) the AI read on an uploaded invoice.
POST	/api/v1/invoices/{id}/hold	Park an invoice.
POST	/api/v1/invoices/{id}/reject	Decline an invoice.
GET	/api/v1/vendors	List vendors.
POST	/api/v1/vendors	Create or update a vendor.
GET	/api/v1/payouts	List PayPal payments and their status.

Submit an invoice

# AI reads it; then pay it with PayPal from the dashboard
curl -X POST https://handlemyap.com/api/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -d vendor_name="Jane Q Notary" \
  -d vendor_email=jane@example.com \
  -d amount=125.00 -d currency=USD \
  -d external_ref=order:12345:notary-payment

The response includes the invoice status. A new payable lands in needs_review, waiting in the queue to be paid with PayPal; it becomes paid once a payment is captured.

MCP server

HandlemyAP speaks the Model Context Protocol over streamable HTTP (JSON-RPC 2.0). Connect an AI agent and it gets four tools to submit and track payables — so an agent can file a bill into the queue, but a human still pays it with PayPal. The agent never moves the money.

Endpoint

https://handlemyap.com/mcp      # POST, JSON-RPC 2.0, Bearer auth

Connect a client

Add it to any MCP client that supports HTTP transport, e.g.:

{
  "mcpServers": {
    "handlemyap": {
      "type": "http",
      "url": "https://handlemyap.com/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Tools

submit_invoice

Add a payable. AI reads and normalises it, then it waits in the queue to be paid with PayPal.

list_invoices

See the queue, optionally filtered by status.

get_invoice

Inspect one invoice and its payment history.

list_payouts

See PayPal payments and their status.

Call a tool directly

curl -X POST https://handlemyap.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "submit_invoice",
      "arguments": {
        "vendor_name": "Jane Q Notary",
        "vendor_email": "jane@example.com",
        "amount": 125.00,
        "external_ref": "order:12345:notary-payment"
      }
    }
  }'

Invoice lifecycle

Every invoice moves through the same states, whichever surface created it:

received extracting needs_review paid held rejected

AI only reads the document — genuinely semantic work. Every invoice then waits in needs_review until a human pays it with PayPal (paid), holds it, or rejects it. Money only moves on a real PayPal approval.

Idempotency

Pass external_ref on submit — your own stable key (e.g. order:12345:payment). Resubmitting the same reference returns the existing invoice instead of creating a duplicate, so retries and at-least-once webhooks are safe.

HandlemyAP — AI accounts payable · Home · GitHub