Accounts Payable

Business flow

Accounts Payable (AP) covers the flow of receiving e-invoices from your suppliers and managing them inside your system. With Staple, your team does not need to integrate directly with each country’s tax authority or with the Peppol network — Staple acts as the central hub between your business and every supported e-invoicing network.

The flow works as follows:

1. Staple receives the invoice. A supplier issues an e-invoice. The invoice is delivered to Staple through the relevant national e-invoicing platform (such as KSeF in Poland, MyInvois in Malaysia, or SDI in Italy) or through the Peppol network. Staple receives and stores the invoice on your behalf.
2. Staple notifies your system. A webhook is sent to your registered endpoint as soon as the invoice is uploaded into Staple. The notification carries the identifiers your system needs to retrieve the invoice in the next step.
3. Your system retrieves the invoice in STAR format. Using the documentId from the webhook, your system calls the Export endpoint and receives the invoice as a STAR JSON payload — the same unified schema Staple uses for every supported country. The response also includes validation proof from the tax authority or Peppol.
4. Your team acts on the invoice. Your AP team reviews the invoice in your accounting or ERP system and decides what to do with it. They can accept it, reject it, or mark it as paid once payment has been made.
5. You notify Staple of the decision. For each decision, your system calls the corresponding Staple endpoint — Accept, Reject, or Paid.
6. Staple synchronises the status. Where the tax authority or Peppol network requires the status to be reported back (for example, an invoice acknowledgement or a paid notification), Staple handles that synchronisation automatically.
7. The original document is available for download. Whenever you need the original e-invoice file — for audit, dispute resolution, or archival — you can retrieve it through the Download original document endpoint.

Document state machine

Every received e-invoice progresses through a small set of states inside Staple. The state machine below shows the valid transitions:

Received --accept--> Accepted --paid--> Paid
    |
    --reject--> Rejected

• A document starts in the Received state as soon as Staple receives it from the tax authority or the Peppol network.
• Calling Accept moves the document from Received to Accepted.
• Calling Reject moves the document from Received to Rejected.
• Calling Paid moves the document from Accepted to Paid. Paid is only valid from the Accepted state.
• Once a document is in Accepted, it cannot be rejected.
• Rejected and Paid are terminal states — no further transitions are possible.

Each AP endpoint requires you to identify the document being acted on. You can use either of two identifiers, depending on how the document entered Staple:

• documentId — used for paper invoices that customers send to Staple via email or other channels. Staple scans the document, extracts the data, and assigns a documentId. Paper invoices do not have a tax authority reference.
• taxAuthorityReference — used for e-invoices that Staple pulls from the tax authority or the Peppol network. This is the unique identifier assigned by the tax authority. The exact form depends on the country:

Webhook notifications

When a new e-invoice arrives at Staple, your system is notified through a webhook so you can retrieve the invoice and act on it without polling.

To start receiving webhook notifications, subscribe to the Document uploaded event in the Staple UI:

1. In Staple, open User Profile → Webhooks.
2. Configure a webhook URL on your server and subscribe to the Document uploaded event.

Webhook payload

When a new document — including an inbound e-invoice — is uploaded to Staple, the following payload is delivered to your registered webhook URL:

1
{
2
  "event": "document.uploaded",
3
  "payload": {
4
    "documentInfo": {
5
      "documentId": 123,
6
      "documentName": "invoice.pdf",
7
      "taxAuthorityReference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
8
      "uploadedAt": "2026-06-11T12:34:56.789Z"
9
    },
10
    "userInfo": {
11
      "email": "user@example.com",
12
      "firstName": "Jane",
13
      "lastName": "Doe"
14
    }
15
  }
16
}

For paper invoices, taxAuthorityReference will be null.

Use the documentId (or taxAuthorityReference if you prefer) from this payload to retrieve the e-invoice in STAR format through the Export endpoint described in the next section.

Export documents

POST https://api.staple.io/v1/documents/export

Export one or more received documents in your chosen format. For e-invoices, exporting in STAR format returns the invoice as a country-agnostic JSON payload that your accounting or ERP system can process consistently regardless of which country the invoice came from.

The response also includes a validation block confirming whether the invoice has been validated by the tax authority or the Peppol network — and when — so your system can rely on the data without performing its own validation.

1
POST https://api.staple.io/v1/documents/export
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "docIds": [9021],
7
  "formatType": "STAR"
8
}

The response contains the STAR payload for each requested document, along with a validation block.

1
{
2
  "exportDocumentByDocIds": {
3
    "data": [
4
      {
5
        "docId": 9021,
6
        "star": {
7
          "Country": "DE",
8
          "DocNumber": "INV-0001",
9
          "IssueDate": "2026-05-09",
10
          "Currency": "EUR",
11
          "Supplier": {
12
            "Name": "Mustermann GmbH",
13
            "TaxID": { "Country": "DE", "Code": "111111125" }
14
          },
15
          "Customer": {
16
            "Name": "Buyer GmbH",
17
            "TaxID": { "Country": "DE", "Code": "222222229" }
18
          },
19
          "Lines": [
20
            {
21
              "Quantity": "1.00",
22
              "Item": { "Name": "Consulting service", "Price": "1000.00" },
23
              "Taxes": [{ "Cat": "VAT", "Rate": "standard" }]
24
            }
25
          ]
26
        },
27
        "validation": {
28
          "status": "validated",
29
          "validatedAt": "2026-05-09T09:21:00Z",
30
          "source": "tax_authority",
31
          "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
32
        }
33
      }
34
    ],
35
    "message": "Documents exported successfully."
36
  }
37
}

Validation block

The full STAR schema reference is documented in Schema Objects.

Accept

POST https://api.staple.io/v1/documents/move/accepted

Notify Staple that your AP team has accepted an invoice. This moves the document from Received to Accepted. For e-invoices, Staple synchronises the acceptance status to the relevant tax authority or the Peppol network. For paper invoices, only the local state is updated.

1
POST https://api.staple.io/v1/documents/move/accepted
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "taxAuthorityReference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
7
}

Reject

POST https://api.staple.io/v1/documents/move/rejected

Notify Staple that your AP team has rejected an invoice. This moves the document from Received to Rejected. For e-invoices, Staple synchronises the rejection to the tax authority or the Peppol network. For paper invoices, only the local state is updated.

Once a document has been accepted, it can no longer be rejected through this endpoint.

1
POST https://api.staple.io/v1/documents/move/rejected
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "documentId": "9021",
7
  "reasons": ["duplicate", "incorrect_amount"]
8
}

Paid

POST https://api.staple.io/v1/documents/move/paid

Notify Staple that an accepted invoice has been paid. This moves the document from Accepted to Paid. Payment metadata is required for e-invoices, where the payment status must be reported externally. For paper invoices, payment metadata is optional.

1
POST https://api.staple.io/v1/documents/move/paid
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "taxAuthorityReference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7
  "payment": {
8
    "paidAt": "2026-05-21T10:30:00Z",
9
    "amount": "1500.00",
10
    "currency": "EUR",
11
    "paymentReference": "TXN-12345",
12
    "paymentMethod": "bank_transfer"
13
  }
14
}

syncStatus values

Every response from the Accept, Reject, and Paid endpoints includes a syncStatus field. This indicates whether and how the state change has been synchronised externally with the tax authority or the Peppol network.

Search documents

POST https://api.staple.io/v2/search/documents

Search for documents using filters such as document ID, tax authority reference, status, date range, and queue. This endpoint is useful when your buyer-side team needs to look up a specific e-invoice or list all e-invoices in a given state.

filter object fields

pagination object fields

1
POST https://api.staple.io/v2/search/documents
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "filter": {
7
    "queue": [4173],
8
    "tab": ["RECEIVED"],
9
    "uploadedAt": {
10
      "from": "01/05/2026",
11
      "to": "31/05/2026"
12
    }
13
  },
14
  "pagination": {
15
    "skip": 0,
16
    "take": 50
17
  }
18
}

The underlying endpoint supports additional filters used elsewhere in the Staple platform (such as filename and content search) — those filters are omitted here as they are not commonly used in e-invoice workflows.

Download original document

POST https://api.staple.io/v1/documents/download

Download the original files of one or more received documents. The response is a ZIP archive containing the original files (for example, the raw XML for an e-invoice or the source PDF for a scanned paper invoice).

This endpoint is useful for audit, dispute resolution, or archival — when you need the exact file Staple received from the supplier or the tax authority.

1
POST https://api.staple.io/v1/documents/download
2
Authorization: Bearer <token>
3
Content-Type: application/json
4
5
{
6
  "docIds": [9021, 9022, 9023]
7
}

The response is a stream of ZIP-archive bytes containing the original file for each requested document. Save the response stream to disk and unzip to access the individual files.