Skip to main content

Getting started

This page walks through your first end-to-end invoice submission against the Partner API. By the end of it you will have:

  1. An api_key and rotation_secret for one of your customer's Nuntiq tenants.
  2. A successful invoice submission visible in the customer's portal.
  3. An invoice_token you can save for later status queries.

0. Prerequisites​

Before you can call anything, the customer has to:

  1. Create a partner account for you in their Nuntiq admin or customer portal.
  2. Add at least one of your email addresses as a notification recipient on that account.
  3. Click Send invitation on the account.

You will then receive an email with subject like:

Acme Corp: API access invitation for "Your Company"

with a single magic link button. Everything below starts from that email.

1. Claim your API key​

  1. Click the magic link. It opens the customer's supplier portal at https://<their-subdomain>.apquery.com/supplier-access/regenerate.
  2. The page asks you to Send verification code. Click it. A second email with a 6-digit code arrives at the same address.
  3. Enter the code on the same page.
  4. The page now asks for:
    • A label for the key (e.g. prod-ingest, billing-cron, anything that helps you recognize it later).
    • An expiration interval: 1 month, 3 months (default), 6 months, 1 year, or Never.
  5. Click Issue key.

The next screen shows your api_key and rotation_secret in plaintext. Copy them both into your secret store immediately. They will never be shown again. Closing the tab without saving means you have to generate a new key from scratch.

API Key:         nuntiq_pk_live_3f9a01bc_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
Rotation Secret: nuntiq_rs_live_7c8d9e0f_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
Expires:         8/18/2026, 1:37:35 AM

A partner_key_issued notification email also fires to every notification email on the account, so the customer's AP team knows a key was just issued. The key itself is not in that email.

See Key lifecycle for full mechanics.

2. Submit your first invoice​

curl -X POST https://api.apreceiving.com/api/v1/partner/invoices \
  -H "X-API-Key: $NUNTIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-erp-invoice-12345" \
  -d '{
    "invoice": {
      "supplier_number": "S-001",
      "invoice_number":  "INV-2026-0042",
      "invoice_date":    "2026-05-19",
      "currency":        "USD",
      "total_amount":    1234.56,
      "lines": [
        { "description": "Consulting, May 2026", "quantity": 1, "unit_price": 1234.56 }
      ]
    },
    "attachments": [
      {
        "type":     "IMAGE",
        "filename": "invoice.pdf",
        "content":  "JVBERi0xLjQKJ..."
      }
    ]
  }'

A successful response looks like:

{
  "success": true,
  "data": {
    "invoice_token":       "750e8400-e29b-41d4-a716-446655440002",
    "external_identifier": "ACME-001"
  }
}

All partner endpoints return the same envelope: { "success": true, "data": { ... } } (or { "success": false, "message": "..." } on error). The one exception is POST /partner/account/keys/{key_id}/rotate, which returns a bare credential object. See Key rotation for details.

That invoice_token is your handle for the submission; save it. Anything downstream (status queries, lifecycle events, attachment retrieval) runs through the Customer API with customer-issued credentials.

Two response headers worth noting:

  • Warning: present when Nuntiq accepted the invoice but had to fall back from your receiving_inbox to the customer's default inbox. Treat as soft: the invoice landed, but the routing field you supplied was unknown.
  • Idempotency-Key: echoed back. A retry of the same key within 24 hours returns the original invoice_token, not a duplicate.

See Submitting invoices for the full request shape (attachment rules, supported fields, validation).

A long-lived key is a long-lived risk. Either:

  • Have a human rotate it by regenerating from the supplier portal before each expiry (you will get reminder emails starting up to 60 days out), or
  • Have your backend rotate it by calling POST /partner/account/keys/:key_id/rotate with both the current X-API-Key and X-Rotation-Secret. You get a new key + new secret back, and the old key keeps working for 4 hours so you can roll your process restart without an outage window.

See Rotation.

4. Subscribe to the right reminders​

By default every notification email on your account receives all four types of email: advance expiry reminders (60/30 days out), imminent expiry reminders (7/3/1 days out), the "key expired" notice, and the "key issued" notice when a new key is minted.

If your team wants fewer emails, click manage email preferences in any reminder. See Email preferences.

What's next​