Skip to main content

Customer API

The Nuntiq Customer API lets you push invoices into the platform, post processed invoices to your ERP, and keep master data in step: suppliers, organization units, purchase orders, PO lines, receipts, customer data tables and users. It also carries payments, lifecycle messages, exchange rates and webhooks.

The API reference is generated from the API's OpenAPI specification. Treat it as the source of truth for fields and parameters. The Postman collection covers the same API.

Every request​

  • Authentication. Send your API key in the X-API-Key header. Keys start with nk_, are shown once, expire after at most 365 days and can be rotated with a grace period, also by the integration itself: see API keys and rotation.
  • Errors are problem documents: type, title, status, code, detail and request_id. Every answer carries an X-Request-Id header.
  • Idempotency. Send an Idempotency-Key header on every POST, PATCH and DELETE. A retry with the same key and body within 24 hours replays the first answer (Idempotent-Replayed: true). The same key while the first request still runs answers 409; with another body, 422. Leave it off the key rotation call: its answer holds the new key.
  • Organization-scoped keys see and change only the records of their organizations. Users and the inactivity sweep are tenant-wide and answer 403 to a scoped key.

Master data​

Suppliers, organization units, purchase orders, PO lines, receipts, customer data tables and users follow one contract:

  • Keys. A record is found by its Nuntiq id, by source_system plus its source key (source_record_id; purchase order source_document_id, PO line source_line_id, receipt source_receipt_line_id), or by its natural key.

  • POST sends full records: fields you leave out get their defaults. PATCH merges the fields you send and never creates; a child with "_delete": true is removed. DELETE soft-deletes by key.

  • Source system and ownership. The source system of a write is the API user's own (its Source system setting, else its name); the URL cannot choose another one (source_system_override_not_allowed). Which records the integration may change and remove is the API user's record ownership:

    • All records where the source system matches (default): its own records; a record entered in the portal is taken over when the integration updates it.
    • All integrated records where the source system matches: its own records only.
    • All integrated records: every record that came from an integration, never one entered in the portal.
    • All records: every record.

    Under the last two, a record may name another source system in its source_system field to reach that system's records; under the first two a different value is refused (source_system_mismatch). Other records are refused with owned_by_other_source.

  • Answers list one result per record (created, updated, unchanged, deleted, not_found, rejected with errors), with HTTP 200, 207 or 422. all_or_none=true applies a request only when every record is valid.

  • Reads page with a cursor (next_cursor), take exact filters, updated_since and include_deleted.

  • Full loads are sync runs: start a run, send the batches with its sync_run_id, then complete it: records of your source that the run did not see are removed. A run that saw nothing refuses to complete; failing a run changes nothing.

Invoice posting​

Claim invoices that are ready for integration. Each claim returns a lease; acknowledge, release and the integration result need its lease_token while the invoice is claimed (lease_token_required, lease_mismatch). An invoice whose lease ran out is offered to the next claim. The bulk calls take up to 100 invoices.

  • Connector framework: the Python SDK connectors use. It calls the same API with a job token.
  • Invoice lifecycle code catalog: the full list of code values accepted by POST /v1/invoices/{token}/lifecycle-messages, grouped by tier, with state-transition rules.