> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate with an AI assistant
> Copy a ready-made prompt that helps ChatGPT, Claude, Cursor or any AI assistant build your Pazy integration
If you build with an AI assistant, give it this page's prompt first. The prompt teaches the assistant how the Pazy API works, makes it ask you the right questions before it writes code, and points it at the documentation for every endpoint.
## How to use it
In the [Pazy app](https://app.pazy.io), go to **Settings → Developer → Create API Key**. Give the key only the permissions your integration needs.
Store the key in an environment variable such as `PAZY_API_KEY`.
Don't paste your API key into the chat with the assistant. The prompt tells it to read the key from an environment variable instead.
Use the copy button on the code block below.
Use any assistant that can write code, such as ChatGPT, Claude, Cursor or GitHub Copilot. For the best results, use one that can open web pages, so it can read the endpoint documentation.
The assistant will ask what you want to build, your language, which Pazy resources are involved, whether to use a sandbox, and how to handle failures. Then it will give you a plan to confirm before it writes code.
Read the code, and try read-only calls first. Be especially careful with calls that create or change data, and with marking invoices as paid.
A sandbox environment is created on request. Email [customer-support@pazy.io](mailto:customer-support@pazy.io) to ask for one, and test write operations there before you run them in production.
## The prompt
```text Pazy integration prompt theme={null}
You are helping me integrate my software with the Pazy API (accounts payable: vendors, purchase orders, invoices, payments, expenses, reimbursements, taxes). Follow these instructions exactly.
## How to work with me
1. Do NOT write code yet. First ask me the questions in "Questions to ask me" below. Ask them in one short batch, then wait for my answers. Ask follow-ups only where my answers are unclear.
2. Summarize your understanding and a short plan (endpoints you will call, in what order, how errors are handled). Wait for me to confirm.
3. Before writing code for any endpoint, open its documentation page (https://docs.pazy.io plus the path listed in the endpoint index) and use the exact parameter names, types, required fields and error codes from that page. Never guess fields. If you cannot open the page, tell me and ask me to paste its content.
4. Start with read-only calls. Add write calls (POST, PATCH) only after the read-only part works, and only after I confirm.
5. Keep the code small and runnable, with a short explanation of how to run it.
## Questions to ask me
1. What are you trying to build? (For example: sync vendors from our ERP, create purchase orders from our procurement tool, upload invoices, mark invoices as paid, export expenses.)
2. Which language and framework are you using, and where will this code run? (Script, backend service, scheduled job, serverless function.)
3. Which Pazy resources are involved? (Vendors, purchase orders, invoices, payments, expenses, reimbursements, users, tags, GRNs, SKUs, taxes, company settings.)
4. Do you only need to read data, or also create and update it?
5. Which environment? Production, or a sandbox? (A sandbox is created on request by emailing customer-support@pazy.io.) If I plan to write to production, ask me to confirm before any write call is run.
6. Do you already have a Pazy API key, and which permissions does it have? (Keys are created in the Pazy app under Settings > Developer > Create API Key.) Tell me never to paste the key into this chat.
7. How should the key be stored? (Environment variable, secret manager.)
8. How often will this run and how many records will it handle? (This decides pagination, batching and rate limit handling.)
9. How should it be triggered: on a schedule, on demand, or when something changes in Pazy? (For changes in Pazy, webhooks are better than polling: https://docs.pazy.io/webhooks/overview.)
10. How do you want to link records between systems? (Store the Pazy ids that come back from create calls: vendorId, poId, invoice id.)
11. What should happen on failure? (Retry, skip and log, stop and alert.)
12. What do you want delivered? (A script, a reusable client, a full service, tests.)
## Pazy API facts
Base URL: https://api.pazy.io/v1.0
Documentation: https://docs.pazy.io
Authentication: send the API key in the Authorization header on every request.
Authorization: Api-Key $PAZY_API_KEY
Read the key from the PAZY_API_KEY environment variable. Never hardcode it, print it, log it, or commit it. Requests with a missing or invalid key return 401. A valid key without the needed permission returns 403 INSUFFICIENT_PERMISSIONS.
Requests and responses:
- JSON bodies use Content-Type: application/json. Invoice creation and document uploads use multipart/form-data.
- Most successful responses look like {"ok": true, "data": {...}}.
- Most errors look like {"ok": false, "error": {"code": "...", "message": "..."}}. Branch on error.code, not message. The duplicate idempotency key error is an exception: it returns 409 with {"error": ""}.
Pagination: list endpoints take limit (1 to 100) and cursor. Send the first request without a cursor. If data.context.hasMore is true, send the next request with cursor set to data.context.nextCursor, and keep every other filter the same. Stop when hasMore is false. Do not decide the end of the list by comparing the result count to limit.
Rate limits: 300 requests per minute per organization and 200 per minute per user. Exceeding either returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header. Wait for that time before retrying, and use exponential backoff if it keeps happening.
Retries:
- Retry GET requests on 429, 5xx and network errors, with backoff and a maximum number of attempts.
- Do not retry 400, 401, 403 or 404 without changing the request.
- Be careful retrying writes. A timeout does not tell you whether the write was applied. Check the resource first.
- POST /payment/mark-as-paid REQUIRES an x-idempotency-key header (a new UUID per payment). POST /payment/request/vendor-advance accepts one and it should be sent. Reusing a key within 5 minutes returns 409 and is not processed.
Things that are easy to get wrong:
- Invoices are processed asynchronously after upload. Poll GET /invoice/:id until data.processingStatus.isReady is true before using the data.
- Only invoices in the APPROVED state can be marked as paid.
- POST /payment/mark-as-paid with up to 100 invoices returns a result for each invoice. One failing does not stop the others, so check every entry in data.results. Over 100 invoices runs asynchronously and returns a bulkActionSlug to poll at GET /payment/mark-as-paid/batch/:slug.
- Purchase orders with matchingType THREE_WAY need every line item to match an existing SKU.
- Dates are ISO-8601. State values such as Indian states are uppercase with underscores (for example MAHARASHTRA).
- Vendor and invoice ids come from the create and list calls. Do not make them up.
Guides worth following: https://docs.pazy.io/guides/procure-to-pay, https://docs.pazy.io/guides/recording-payments, https://docs.pazy.io/guides/pagination, https://docs.pazy.io/guides/errors-and-retries
## Endpoint index
Each line is METHOD PATH -> documentation page path. Prefix the page path with https://docs.pazy.io. Paths are relative to the base URL.
Vendor APIs:
- POST /vendor -> /apis/vendor-creation
- POST /vendor/invite -> /apis/vendor-invite-creation
- GET /vendors -> /apis/vendor-list
- GET /vendor/search -> /apis/vendor-search
- GET /vendor/:vendorId -> /apis/vendor-details
- PATCH /vendor/:vendorId -> /apis/vendor-update
- POST /vendor/:vendorId/taxation -> /apis/vendor-taxation-creation
- PATCH /vendor/:vendorId/taxation -> /apis/vendor-taxation-update
- GET /vendor/:id/documents -> /apis/vendor-documents
- POST /vendor/:vendorId/documents -> /apis/vendor-document-upload
- GET /vendor/:id/audit-trail -> /apis/vendor-audit-trail
- GET /vendor/:id/advances -> /apis/vendor-advances
- GET /vendor/:id/payments -> /apis/vendor-payments
Purchase Order APIs:
- POST /procurement/purchase-order -> /apis/po-creation
- GET /procurement/purchase-order/:poId -> /apis/po-details
- PATCH /procurement/purchase-order/:poId -> /apis/po-update
- GET /procurement/purchase-order/search -> /apis/po-search
- GET /procurement/purchase-orders -> /apis/po-list
Invoice APIs:
- POST /invoice -> /apis/invoice-creation
- GET /invoices -> /apis/invoice-list
- GET /invoice/:id -> /apis/invoice-details
- GET /invoice/:id/comments -> /apis/invoice-comments
- POST /invoice/:invoiceId/comment -> /apis/invoice-comment-add
- GET /invoice/:invoiceId/supporting-documents -> /apis/invoice-supporting-documents
- POST /invoice/:invoiceId/supporting-documents -> /apis/invoice-supporting-document-upload
- GET /invoice/:id/audit-trail -> /apis/invoice-audit-trail
Expense APIs:
- GET /expenses -> /apis/expense-list
- GET /expense/:expenseId -> /apis/expense-details
Payment APIs:
- POST /payment/mark-as-paid -> /apis/mark-as-paid
- GET /payment/mark-as-paid/batch/:slug -> /apis/mark-as-paid-batch-status
- GET /payment/requests -> /apis/payment-request-list
- GET /payment/request/:paymentRequestId -> /apis/payment-request-details
- POST /payment/request/vendor-advance -> /apis/vendor-advance-creation
Reimbursement APIs:
- GET /reimbursements -> /apis/reimbursement-list
- GET /reimbursement/:reimbursementId -> /apis/reimbursement-details
User APIs:
- GET /users -> /apis/user-list
- GET /user/:id -> /apis/user-details
Tags APIs:
- GET /tags -> /apis/tag-list
- POST /tag -> /apis/tag-creation
- GET /tags/:tagId/values -> /apis/tag-detail
- POST /tag/:tagId/value -> /apis/tag-value-creation
- PATCH /tag/:tagId/value -> /apis/tag-value-update
GRN APIs:
- POST /procurement/grn -> /apis/grn-creation
Inventory APIs:
- POST /inventory/skus/bulk -> /apis/sku-bulk-creation
Download APIs:
- GET /download/:resourceType -> /apis/download-file
Company APIs:
- GET /company/entities -> /apis/company-entities
- GET /company/configurations -> /apis/company-configurations
- PATCH /company/configurations -> /apis/company-configurations-update
Tax APIs:
- GET /taxes/tds -> /apis/taxes-tds
- POST /taxes/tds -> /apis/taxes-tds-creation
- GET /taxes/gst -> /apis/taxes-gst
- POST /taxes/gst -> /apis/taxes-gst-creation
## Code requirements
- Put the base URL and key in configuration, not in the code.
- Add a small client function that sets the headers, applies the retry rules above, and returns parsed JSON or a clear error that includes error.code.
- Handle pagination in a reusable helper.
- Make write operations safe to run twice where the API allows it.
- Log request ids and error codes, never the API key or full payloads that contain sensitive data.
- Finish by telling me how to run it and how to test it against the sandbox or with read-only calls first.
```
## What the assistant will ask you
The prompt makes the assistant ask these questions before it writes any code, so have the answers ready:
* What you're building, such as syncing vendors, creating purchase orders, uploading invoices or recording payments.
* Your language, framework, and where the code runs.
* Which Pazy resources you need, and whether you only read data or also write it.
* Whether this is a sandbox or production.
* Which permissions your API key has, and how you store it.
* How often it runs and how many records it handles.
* Whether it runs on a schedule, on demand, or when something changes in Pazy.
* What should happen when a call fails.
## Prefer to work in your AI client directly?
Set up the Pazy MCP server instead, so the assistant can use your Pazy data without you writing integration code. See the [MCP integration guide](/mcp-integration).
## Related
Authentication, rate limits, pagination and the quickstart.
Get notified when things change, instead of polling.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.