Agent API: Create and Send Invoices with an API Key

Get an API key

Step 01: Open your account page

Step 02: Name the key and pick permissions

Use a name you will recognize later, such as the agent's name. Only tick the permissions it needs.

Step 03: Copy the key

The key starts with iw_live_ and is shown once. Store it in your agent's secret settings.

Keep keys private

A key can do everything its permissions allow on your account. Do not paste it into public chats or code. If a key leaks, revoke it on your account page and create a new one.

Make your first request

Send the key in the Authorization header. All endpoints live under https://invoicewebsite.com/api/v1.

Create a draft invoice. Totals, due date (from net30), and the invoice number are filled in for you:

curl -X POST https://invoicewebsite.com/api/v1/invoices \
  -H "Authorization: Bearer iw_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Source: my-assistant" \
  -d '{
    "client": { "name": "Acme Co", "email": "billing@acme.example" },
    "items": [
      { "description": "Website design", "quantity": 1, "rate": 1200 },
      { "description": "Hosting (months)", "quantity": 12, "rate": 15 }
    ],
    "currency": "USD",
    "terms": "net30",
    "taxLines": [{ "name": "Sales tax", "percentage": 8 }]
  }'

Email the client a link to the invoice and mark it as sent:

curl -X POST https://invoicewebsite.com/api/v1/invoices/INVOICE_ID/send \
  -H "Authorization: Bearer iw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Thanks for your business!" }'

The optional X-Agent-Source header names your agent so you can tell integrations apart. A full, machine-readable description is at openapi.json.

Endpoints

Agent API endpoints and the permission each needs
Method	Path	What it does	Permission
GET	/me	Current user, plan, key scopes, and remaining usage	Any key
GET	/invoices	List invoices, newest first	invoices:read
POST	/invoices	Create a draft invoice	invoices:write
GET	/invoices/{id}	Get an invoice	invoices:read
PATCH	/invoices/{id}	Update an invoice	invoices:write
POST	/invoices/{id}/send	Email the client a link to the invoice	send
POST	/invoices/{id}/share-link	Create a public share link for an invoice	send
GET	/estimates	List estimates, newest first	estimates:read
POST	/estimates	Create a draft estimate	estimates:write
GET	/estimates/{id}	Get an estimate	estimates:read
PATCH	/estimates/{id}	Update an estimate	estimates:write
POST	/estimates/{id}/share-link	Create a public share link for an estimate	send
POST	/estimates/{id}/convert	Convert an estimate into a new invoice	invoices:write
GET	/clients	List saved clients	clients:read
POST	/clients	Save a client	clients:write
GET	/businesses	List the businesses that can issue documents	clients:read
POST	/editor-link	Build a prefilled editor link for the user to review and save	Any key

Permissions (scopes)

API key permissions
Scope	Allows
invoices:read	Read invoices
invoices:write	Create and update invoices
estimates:read	Read estimates
estimates:write	Create and update estimates
clients:read	Read clients and businesses
clients:write	Create and update clients
send	Email documents and create share links

Limits and errors

The API needs a Basic or Premium plan. Each key can make 60 requests per minute, and your plan's document and email limits apply as they do on the website.

Errors use one JSON shape with a stable code and a message you can show the user:

{
  "error": {
    "code": "payment_required",
    "message": "You have used all documents included in your plan this month. Upgrade at https://invoicewebsite.com/pricing."
  }
}

Agent API error status codes
Status	Code	Meaning
400	invalid_request	The body or parameters failed validation. The message lists each problem.
401	unauthorized	The key is missing, wrong, or revoked.
402	payment_required	The account is on the Free plan, or a plan limit was reached.
403	forbidden	The key does not have the permission this endpoint needs.
404	not_found	The document does not exist or belongs to someone else.
429	rate_limited	More than 60 requests in a minute with one key. Wait and retry.

Prefer a review step?

POST /editor-link returns a prefilled editor URL instead of saving anything. The user opens it, checks the invoice, and saves it themselves. It does not count toward limits.

Agent API FAQ

Which plans include the Agent API?

Basic and Premium. Free accounts cannot create API keys, and if you downgrade to Free, existing keys get status 402 until you upgrade again. Prefill links and browser tools work on every plan.

Does creating an invoice through the API count toward my plan?

Yes. API requests use the same limits as the website, including documents per month and emails per day. When you reach a limit, the API answers with status 402 and an upgrade link.

Does the send endpoint attach a PDF?

No. It emails your client a secure link to view the invoice online, where they can also download it. Emails count toward your daily email limit.

Can I limit what an agent is allowed to do?

Yes. Pick only the permissions the agent needs when you create its key, for example read-only access to invoices. You can revoke a key at any time from your account page.

Is there an MCP server for Claude or ChatGPT?

A hosted MCP server is planned. Today, most agent frameworks can import the OpenAPI description at /openapi.json and call the REST API as tools.

Agent API