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:         sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
Rotation Secret: rs_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":         "01HX5W6YEXAMPLE...",
    "invoice_id":            12345,
    "source_document_id":    98765,
    "workflow":              "full_enrichment",
    "effective_workflow":    "full_enrichment",
    "invoice_status":        20,
    "receiving_inbox":       "ap@your-customer.nuntiq-receiving.com",
    "resolution_path":       "default_fallback",
    "pdf_will_be_generated": true
  }
}

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 everything downstream: status queries, lifecycle events, attachment retrieval (via the Customer API).

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).

3. Set up rotation (recommended)

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

• Authentication: the full header story.
• Submitting invoices: every field on the invoice payload, every error response.
• Keys: rotation + grace: how to rotate without downtime.
• Keys: expired-key error response: the helpful 401 you will see if a key lapses.