NNudgeProAPI v1
On this page

Reference

NudgePro API

Push purchase orders into NudgePro from your own ERP, importer, or automation tool — then let NudgePro chase the supplier exactly as if the PO were created in the dashboard.

Available on the Pro and Business plans. Manage keys in Settings → API.

Base URL

https://nudgepro.com.au/api/v1

Getting started

Authentication

Every request is authenticated with a secret API key. Create one in Settings → API; the full key is shown once at creation. Send it as a Bearer token:

HTTP header
Authorization: Bearer npk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are scoped to your organisation. Revoke a compromised key any time from Settings → API — revocation takes effect immediately.

Keep your key secret

Treat npk_live_ keys like a password. Never embed them in browser code, mobile apps, or public repositories — call the API only from your server.

Limits

Rate limits

Limits are applied per API key across two windows:

60 / minutesliding window

Short-burst protection.

1000 / dayfixed window

Daily ceiling per key.

Exceeding either limit returns 429 with a Retry-After header (seconds) alongside X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Conventions

Errors

All errors follow RFC 7807 application/problem+json:

json
{
  "type": "https://nudgepro.com.au/errors/validation-failed",
  "title": "Request validation failed",
  "status": 422,
  "errors": { "po_number": ["Required"] }
}
401unauthorized

Missing, malformed, invalid, or revoked key.

403forbidden

Your plan does not include API access.

404not found

Resource is not in your organisation.

409conflict

Duplicate po_number.

422unprocessable

Validation failed, or the vendor could not be resolved.

429rate limited

Rate limit exceeded.

Conventions

Idempotency

Safely retry POST requests by sending an Idempotency-Key header (a UUID). A repeat with the same key replays the original response for 24 hours, with Idempotency-Replayed: true set on the replayed response.

Idempotency is independent of the duplicate-PO guard: a repeated po_number always returns 409 with the existing PO, regardless of the key.

Purchase orders

Create a purchase order

POST/api/v1/purchase-orders

Reference the vendor by either an inline vendor object (matched or created by external_id) or an existing vendor_id — exactly one.

Body parameters

po_numberstringrequired

Unique per organisation.

external_idstring

Your own PO id — enables read-back by it.

issue_datestring (date)required

ISO date the PO was issued.

etastring (date)

Expected delivery date, if known.

status"pending" | "draft"

Defaults to pending.

send_nudgesboolean

Defaults to true.

vendorobject

Inline vendor (one of vendor / vendor_id).

line_itemsarrayrequired

At least one item.

Responses

201 Created
json
{
  "id": "po-uuid",
  "po_number": "PO-1234",
  "external_id": "erp-po-987",
  "status": "pending",
  "vendor": { "id": "v-uuid", "external_id": "V-1234", "name": "Acme Steel" },
  "total_aud": 2500.00,
  "created_at": "2026-05-27T01:00:00.000Z",
  "nudges_enabled": true
}
409 Conflict
json
{
  "type": "https://nudgepro.com.au/errors/duplicate-po",
  "title": "Purchase order already exists",
  "status": 409,
  "detail": "PO-1234 already exists for this organisation",
  "existing": { "id": "po-uuid", "po_number": "PO-1234" }
}
curl -X POST https://nudgepro.com.au/api/v1/purchase-orders \
  -H "Authorization: Bearer npk_live_xxx" \
  -H "Idempotency-Key: 6f1c…(uuid)" \
  -H "Content-Type: application/json" \
  -d '{
    "po_number": "PO-1234",
    "external_id": "erp-po-987",
    "issue_date": "2026-05-27",
    "eta": "2026-06-15",
    "status": "pending",
    "send_nudges": true,
    "reference": "Project Alpha",
    "vendor": {
      "external_id": "V-1234",
      "name": "Acme Steel",
      "contact_email": "ops@acme.com",
      "abn": "12345678901",
      "state": "QLD"
    },
    "line_items": [
      { "description": "Steel beam 6m", "qty": 10, "unit_price": 250.00 }
    ]
  }'

Test from a block

{
  "id": "po-uuid",
  "po_number": "PO-1234",
  "external_id": "erp-po-987",
  "status": "pending",
  "vendor": { "id": "v-uuid", "external_id": "V-1234", "name": "Acme Steel" },
  "total_aud": 2500.00,
  "created_at": "2026-05-27T01:00:00.000Z",
  "nudges_enabled": true
}

Purchase orders

Retrieve a purchase order

GET/api/v1/purchase-orders/:id

:id is the NudgePro UUID or your own external_id. Returns 404 if the PO is not in your organisation.

Responses

200 OK
json
{
  "id": "po-uuid",
  "po_number": "PO-1234",
  "status": "pending",
  ...
}
curl https://nudgepro.com.au/api/v1/purchase-orders/po-uuid \
  -H "Authorization: Bearer npk_live_xxx"

Test from a block

{
  "id": "po-uuid",
  "po_number": "PO-1234",
  "status": "pending",
  ...
}

Purchase orders

List purchase orders

GET/api/v1/purchase-orders

Returns a paginated list of purchase orders. POs are returned in descending order by creation date.

Query parameters

pageinteger

Page number to retrieve, default is 1.

limitinteger

Number of items per page, default is 50. Maximum is 100.

statusstring

Filter by status (e.g., pending, draft).

vendor_idstring

Filter by specific NudgePro vendor UUID.

external_idstring

Filter by your ERP vendor ID.

Responses

200 OK
json
{
  "data": [
    {
      "id": "po-uuid",
      "po_number": "PO-1234",
      "external_id": "erp-po-987",
      "status": "pending",
      "issue_date": "2026-05-27",
      "eta": null,
      "total_aud": 2500.00,
      "vendor": {
        "id": "v-uuid",
        "external_id": "V-1234",
        "name": "Acme Steel"
      },
      "created_at": "2026-05-27T01:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total_count": 142,
    "total_pages": 29
  }
}
curl "https://nudgepro.com.au/api/v1/purchase-orders?limit=5&status=pending" \
  -H "Authorization: Bearer npk_live_xxx"

Test from a block

{
  "data": [
    {
      "id": "po-uuid",
      "po_number": "PO-1234",
      "external_id": "erp-po-987",
      "status": "pending",
      "issue_date": "2026-05-27",
      "eta": null,
      "total_aud": 2500.00,
      "vendor": {
        "id": "v-uuid",
        "external_id": "V-1234",
        "name": "Acme Steel"
      },
      "created_at": "2026-05-27T01:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total_count": 142,
    "total_pages": 29
  }
}

Vendors

Create / upsert a vendor

POST/api/v1/vendors

Matched by (org, external_id): returns 200 when an existing vendor is reused, 201 when created.

Body parameters

external_idstringrequired

Your vendor id — the upsert key.

namestringrequired

Required when creating a new vendor.

contact_emailstring

Where nudges are sent.

abnstring

Verified against the ABR inline.

statestring

AU state.

Response

200 / 201
json
{
  "id": "v-uuid",
  "external_id": "V-1234",
  "name": "Acme Steel"
}
curl -X POST https://nudgepro.com.au/api/v1/vendors \
  -H "Authorization: Bearer npk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "V-1234",
    "name": "Acme Steel",
    "contact_email": "ops@acme.com",
    "abn": "12345678901",
    "state": "QLD"
  }'

Test from a block

{
  "id": "v-uuid",
  "external_id": "V-1234",
  "name": "Acme Steel"
}

Vendors

Retrieve a vendor

GET/api/v1/vendors/:id

:id is the NudgePro UUID or your external_id. Returns 404 if the vendor is not in your organisation.

curl https://nudgepro.com.au/api/v1/vendors/V-1234 \
  -H "Authorization: Bearer npk_live_xxx"

Test from a block

{
  "id": "v-uuid",
  "external_id": "V-1234",
  "name": "Acme Steel"
}

Ready to start? Create a key in Settings → API and send your first purchase order.

NudgePro — Planet Sense Pty Ltd · Brisbane, Australia