Pazy Documentation

Authentication

All requests require an API key in the request headers. Headers:

Authorization: Api-Key YOUR_API_KEY

Request

Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the invoice to retrieve

Code Examples

curl -X GET https://api.pazy.io/v1.0/invoice/invoice_identifier \
  -H "Authorization: Api-Key YOUR_API_KEY"

Success Response

HTTP Status: 200 OK Response Fields:

Field	Type	Description
`ok`	boolean	Indicates whether the request was successful
`data`	object	Contains the invoice detail response data
`data.id`	string	Unique identifier for the invoice
`data.invoiceNumber`	string	Invoice number as specified on the invoice document
`data.description`	string	Description or notes about the invoice
`data.invoiceDate`	string	Date when the invoice was issued (ISO 8601 format)
`data.dueDate`	string	Due date for invoice payment (ISO 8601 format)
`data.amount`	number	Total invoice amount
`data.currency`	string	Currency code (e.g., INR, USD)
`data.state`	string	Current state of the invoice. Possible values include: `DRAFTED`, `PENDING`, `APPROVED`, `PAID`, `DECLINED`, `DELETED`, `APPROVAL_PENDING`, etc.
`data.paymentState`	string	Payment state of the invoice. Possible values include: `PAID`, `MARKED_AS_PAID`, `PARTIALLY_PAID`, `UNPAID`, etc.
`data.amountPaid`	number	Amount that has been paid towards this invoice
`data.dateCreated`	string	Date when the invoice was created in the system (ISO 8601 format)
`data.remarks`	string	Additional remarks or notes associated with the invoice
`data.source`	string	Source of invoice creation. Possible values: `API`, `WEB`, `EMAIL`, `SLACK`, `WHATSAPP`, `APP`, etc.
`data.syncedReferenceId`	string	Reference identifier from the accounting system if the invoice has been synced
`data.tax`	object	Tax information object containing tax breakdown
`data.tax.subTotal`	number	Subtotal amount before taxes
`data.tax.gst`	number	GST (Goods and Services Tax) amount
`data.tax.tds`	number	TDS (Tax Deducted at Source) amount
`data.tax.roundOff`	number	Round-off adjustment amount
`data.vendor`	object	Vendor information object
`data.vendor.id`	string	Unique identifier for the vendor
`data.vendor.name`	string	Display name of the vendor
`data.vendor.legalName`	string	Legal name of the vendor
`data.vendor.logo`	string	URL to the vendor’s logo image
`data.vendor.locality`	string	Vendor locality type. Possible values: `DOMESTIC`, `INTERNATIONAL`
`data.syncState`	string	Synchronization state with accounting system. Possible values: `SYNCED`, `NOT_SYNCED`, `SYNCED_WITH_ERRORS`, etc.
`data.accountingDate`	string	Date recorded in the accounting system (ISO 8601 format)
`data.approvedDate`	string	Date when the invoice was approved (ISO 8601 format)
`data.paymentDate`	string	Date when the invoice was paid (ISO 8601 format)
`data.selfUrl`	string	Shareable URL for viewing the invoice in the web interface
`data.accountingPlatform`	string	Name of the connected accounting platform (e.g., “Tally”, “Zoho Books”, “Oracle Fusion”) if available
`data.processingStatus`	object	Processing status information for invoices that are still being processed
`data.processingStatus.processingId`	string	Identifier for the processing job
`data.processingStatus.status`	string	Current processing status. Possible values: `QUEUED`, `PROCESSING`, `PROCESSED`, `FILLED`, `FAILED`, `USER_CANCELLED`, `DISCARDED`
`data.processingStatus.isReady`	boolean	Indicates whether the invoice processing is complete and the invoice is ready for use
`data.lineItems`	array	List of line items on the invoice, ordered by sequence number
`data.lineItems[].sequenceNumber`	number	Position of the line item on the invoice (1-based)
`data.lineItems[].quantity`	number	Quantity of the line item
`data.lineItems[].rate`	number	Unit rate of the line item
`data.lineItems[].skuName`	string	Name of the SKU associated with this line item, if any
`data.lineItems[].amount`	number	Total amount for the line item (quantity × rate after taxes)
`data.lineItems[].taxApplied`	string	Name of the tax applied to this line item (e.g., “GST 18%”), if any
`data.lineItems[].description`	string	Description of the line item
`data.flags[]`	array	List of flags on the invoice
`data.flags[].code`	string	The flag code which is of enum values. Click here for more details.
`data.flags[].description`	string	The flag code description.

Flag Code Enum Description

Code	Description
`DUPLICATE`	An invoice with the same number already exists in your organization.
`NON_ACTIVE_FINANCIAL_YEAR`	This invoice falls outside the current financial year.
`INACTIVE_CURRENCY`	The currency used in this invoice is no longer active for your organization.
`MISSING_RECEIPTS`	One or more receipts are missing for this invoice.
`GST_MISMATCH`	The GST number on this invoice does not match the organization’s registered GST number.
`PROFORMA`	This is a proforma invoice.
`BANK_ACCOUNT_MISMATCH`	The bank account on this invoice does not match the vendor’s registered bank account.
`OVERDUE`	This invoice is overdue and the payment has not been made.
`MSME_VENDOR`	The vendor associated with this invoice is classified as MSME.
`OUT_OF_POLICY`	This invoice does not comply with the organization’s policy.
`PO_MISMATCH`	This invoice line items does not match with purchase order line items.
`LI_PO_RATE_OVERCHARGE`	The unit rate for one or more line items exceeds the rate specified in the purchase order.
`LI_QUANTITY_OVERCHARGE`	The quantity for one or more line items exceeds the quantity specified in the purchase order.
`LI_AMOUNT_OVERCHARGE`	The amount for one or more line items exceeds the amount specified in the purchase order.
`AMOUNT_MISMATCH`	The total invoice amount does not match the sum of its line items.

Response Example

{
  "ok": true,
  "data": {
    "id": "invoice_identifier",
    "invoiceNumber": "INV-2024-001",
    "description": "Monthly services invoice",
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "amount": 50000.00,
    "currency": "INR",
    "state": "APPROVED",
    "paymentState": "UNPAID",
    "amountPaid": 0.00,
    "dateCreated": "2024-01-15T10:30:00Z",
    "remarks": "Payment due in 30 days",
    "source": "API",
    "syncedReferenceId": "ACC-REF-12345",
    "tax": {
      "subTotal": 44000.00,
      "gst": 6000.00,
      "tds": 0.00,
      "roundOff": 0.00
    },
    "vendor": {
      "id": "vendor_identifier",
      "name": "ABC Suppliers",
      "legalName": "ABC Suppliers Private Limited",
      "logo": "https://cdn.pazy.io/logos/vendor_logo.png",
      "locality": "DOMESTIC"
    },
    "syncState": "SYNCED",
    "accountingDate": "2024-01-15",
    "approvedDate": "2024-01-16T14:20:00Z",
    "paymentDate": null,
    "selfUrl": "https://app.pazy.io/invoice/invoice_identifier",
    "accountingPlatform": "Tally",
      "flags": [
      {
        "code": "OVERDUE",
        "description": "This invoice is overdue and the payment has not been made."
      }
    ],
    "processingStatus": {
      "processingId": "job_123456",
      "status": "FILLED",
      "isReady": true
    },
    "lineItems": [
      {
        "sequenceNumber": 1,
        "quantity": 2,
        "rate": 20000.00,
        "skuName": "Laptop Stand",
        "amount": 40000.00,
        "taxApplied": "GST 18%",
        "description": "Ergonomic laptop stand"
      },
      {
        "sequenceNumber": 2,
        "quantity": 1,
        "rate": 10000.00,
        "skuName": null,
        "amount": 10000.00,
        "taxApplied": null,
        "description": "Setup and installation"
      }
    ]
  }
}

Error Responses

Missing Invoice ID

HTTP Status: 400 Bad Request

{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Invoice ID is required"
  }
}

Invoice Not Found

HTTP Status: 404 Not Found

{
  "ok": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice not found"
  }
}

Access Denied

HTTP Status: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view your own invoices or invoices where you are the vendor owner"
  }
}

Authentication Errors

HTTP Status: 401 Unauthorized

{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}

Permission Errors

HTTP Status: 403 Forbidden

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}

Best Practices

Access Control

Only invoices you created or where you are the vendor owner are accessible (unless you have admin or auditor role)
Use the invoice id returned from the invoice creation endpoint to retrieve details
Check the processingStatus.isReady field to ensure the invoice is fully processed before using its data

Invoice States

Common invoice states: DRAFTED, PENDING, APPROVED, PAID, DECLINED
Use processingStatus field to track invoice processing for newly uploaded invoices
Check syncState to verify accounting system synchronization status

Documentation Index

​Authentication

​Request

​Path Parameters

​Code Examples

​Success Response

​Flag Code Enum Description

​Response Example

​Error Responses

​Missing Invoice ID

​Invoice Not Found

​Access Denied

​Authentication Errors

​Permission Errors

​Best Practices

​Access Control

​Invoice States