Build on the nuqo API

1What the API does

The API lets your own systems — an ERP, the middleware in front of it, a planning tool or a script — read what your organization decided in nuqo, without anyone copying it from the screen. It is mostly for reading: your system asks, nuqo answers. The one thing it takes is your parts, from your ERP.

2Sign in

1. Create a key. In nuqo, an owner or admin of your organization opens Settings → API keys, names the key (say, “ERP middleware”) and creates it. The key is shown once: nq_live_ followed by 43 characters. Put it in your secret store.
2. Send it on every request as Authorization: Bearer nq_live_…. No cookie, no CSRF token. Every address starts with https://backend.nuqo.io/api/v1.
3. Test it. GET /organization answers the organization the key belongs to.

curl https://backend.nuqo.io/api/v1/organization \
  -H "Authorization: Bearer $NUQO_KEY"

{ "id": 318, "name": "Example Assemblies Inc" }

Revoke it under Settings → API keys; it stops at once. A lost key can’t be shown again: create a new one, switch your system over, then revoke the old one.

A key acts as your organization, never as a person, and sees only your organization’s data. Every key can read. A key your admin created with “Can also push parts” ticked can also send your parts to nuqo: see Push your parts.

3Read finalized quotes

The list

GET /quotes answers your finalized quotes, oldest finalization first, 50 a page (limit up to 100). Page with next_cursor while has_more is true. Then keep the last next_cursor and poll with it later: it resumes after the last quote you saw, so you get only what was finalized since. A cursor is opaque — pass it back unchanged, never build one. To start from a date instead, send finalized_since; sent together with a cursor, both apply.

curl "https://backend.nuqo.io/api/v1/quotes?finalized_since=2026-10-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "quotes": [
    {
      "id": 5087,
      "number": "139-1",
      "revision": 1,
      "finalized_at": "2026-10-14T08:52:40.611093Z",
      "valid_until": null,
      "customer": null,
      "total": { "amount": 3920.5, "currency": "EUR" }
    },
    {
      "id": 5120,
      "number": "147-2",
      "revision": 2,
      "finalized_at": "2026-10-20T14:03:11.204518Z",
      "valid_until": "2026-11-19T22:59:59Z",
      "customer": { "id": 903, "name": "Sample Machines Ltd" },
      "total": { "amount": 21480, "currency": "EUR" }
    }
  ],
  "next_cursor": "MjAyNi0xMC0yMFQxNDowMzoxMS4yMDQ1MTgrMDA6MDB8NTEyMA",
  "has_more": false
}

A quote reopened, revised and finalized again comes back later with a higher revision and a new number (147-2 after 147-1): replace your copy. While it is being revised it is not in the list, and reading it answers 409.

One quote and its work plan

GET /quotes/{quote_id} answers the header, each assembly with its work plan, and the parts list. The names nuqo gives (assemblies, work centers) come in English; add ?lang=de for German. Text from your customer’s documents, such as a line’s description, stays as written. A draft, or a quote reopened for a revision, answers 409 quote_not_finalized. A finalized quote that has no work plan answers work_plan_available: false and no assemblies. Every field is in the reference; the work plan is the part most systems map first:

One sales-order line per assembly

Each assembly states its price as its row on the quote PDF: unit_price for one piece (per: "pcs") and amount for the quantity ordered, net, in the currency of total. amount is quantity × unit_price, so a sales-order line built from the three matches the PDF. The rest of the quote is in total only: setup the rows don’t carry, shipping, extra charges, the discount, and on an older quote its overall margin. An assembly nobody ordered a quantity of has unit_price: null and amount: null.

The parts list

parts lists every line of the quote’s bill of materials, in its order — including a line that matched nothing (part: null). quantity is what the whole order needs of the part; ordered is what is bought, in the same unit: the need rounded up to the supplier’s pack, minimum order and order multiple. Order ordered. unit_price is the supplier’s list price per unit, in the currency the part is bought in; line_total is what buying ordered costs, in the quote’s currency.

Since 29 October 2026, a line counted in feet or inches states unit_price per foot or per inch, and per says which ("ft" or "in"); before, it was stated per metre. This is a one-off exception to the rule that nothing under /v1/ changes its meaning, made while no integrator uses the API.

4Events

Events tell your system which quote to fetch and which order to hold. Poll GET /events every minute or so, sending the last event id you handled as after (0 the first time).

curl "https://backend.nuqo.io/api/v1/events?after=20870" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "data": [
    {
      "id": 20871,
      "type": "quote.reopened",
      "created_at": "2026-10-19T08:41:55.120334Z",
      "quote": { "id": 5120, "revision": 2 }
    },
    {
      "id": 20872,
      "type": "quote.finalized",
      "created_at": "2026-10-20T14:03:11.394120Z",
      "quote": { "id": 5120, "revision": 2 }
    }
  ],
  "next_after": 20872
}

• Store next_after and send it as after next time. A full page (limit, 100 by default) means more are waiting: ask again at once. A shorter page is the end for now.
• Dedupe on id. Delivery is at least once: if your system fails between handling an event and storing its id, it gets the event again.
• Ignore types you don’t know. New ones may be added.
• Events are kept 30 days. An after older than that answers the oldest events still kept; read the quotes list to catch up.

5The parts sync

Push your parts

Your ERP sends nuqo its parts — prices, stock, article data — instead of someone exporting a file and uploading it. They land on your ERP sync price list, which nuqo ranks against your other price lists like any of them. You need a key an owner or admin created under Settings → API keys with “Can also push parts” ticked; it can’t be added to a key later, and a key without it answers 403.

1. Send a batch of up to 1,000 rows. A row has the fields of a GET /materials row, under the same names, so a row read from nuqo can be sent back as it is; mpn and manufacturer are required. The maker, mpn and supplier say which part a row is, so send the same ones every time: a row that leaves its supplier out is another part. Any other field a row leaves out, or sends as null, keeps the value nuqo holds, and a part the batch leaves out stays as it is. valid_from and valid_to are the days the row’s tiers hold, so send them with those tiers: tiers without them hold from now with no end, and dates without tiers are refused.

   A part you no longer sell: send its row with "removed": true, e.g. {"mpn": "1-968849-1", "manufacturer": "TE Connectivity", "supplier": {"name": "Example Supply", "sku": "ES-968849"}, "removed": true}. It stops being priced from your ERP sync list; your other price lists keep theirs. Its maker, mpn and supplier say which part, as on any row; its other fields are ignored. It still reads back from GET /materials, with prices_quotes false (not as obsolete: that is a part a user deleted), and sending its row again without removed lists it again. Removals apply after the batch’s other rows, so a batch that sends and removes the same part ends with it removed.

   curl https://backend.nuqo.io/api/v1/materials/batches \
     -H "Authorization: Bearer $NUQO_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "rows": [
       {
         "org_sku": "A-10442",
         "mpn": "1-968849-1",
         "manufacturer": "TE Connectivity",
         "description": "Receptacle 2.8 mm, tin",
         "supplier": { "name": "Example Supply", "sku": "ES-968849" },
         "tiers": [{"min_qty": 1, "max_qty": null, "price": {"amount": 0.42, "currency": "EUR"}}],
         "valid_from": "2026-11-01",
         "valid_to": "2027-03-31",
         "quantity_in_stock": 4200
       }
     ]
   }'

   { "batch_id": 88214 }

   The whole batch is checked before any of it is taken. A refused row answers 422 and nothing is queued; the message names the first bad row, e.g. rows[3]: tiers.0.price.amount: Input should be a valid number …. Fix it and send the batch again.

2. Poll the batch every few seconds while its status is pending or running.

   curl https://backend.nuqo.io/api/v1/materials/batches/88214 \
     -H "Authorization: Bearer $NUQO_KEY"

   { "id": 88214, "status": "done", "summary": {"rows": 1, "imported": 1, "removed": 0, "not_imported": []} }

   done carries the summary: the rows sent, how many were imported and removed, and in not_imported each row nuqo didn’t write, by its index in your batch, with the reason: a removal of a part your list doesn’t hold is one, “nothing to remove”. failed means the import stopped: send the batch again. That is safe: a row sent twice writes the same part, and a removal sent twice finds nothing left to remove. While a batch is pending or running, another answers 409 batch_in_progress: send it once the poll says done.

3. Read them back with GET /materials, changed_since set a minute before you sent the batch, so a clock of yours running ahead misses nothing: every part that changed since, the batch’s among them, as nuqo holds them, with nuqo’s listing_id and part_id. A row that changed nothing doesn’t come back. A change is served once it is 3 minutes old.

   curl "https://backend.nuqo.io/api/v1/materials?changed_since=2026-10-30T08:00:00Z" \
     -H "Authorization: Bearer $NUQO_KEY"

   {
     "materials": [
       {
         "listing_id": 918377,
         "part_id": 4410951,
         "catalogue": { "id": 131, "name": "ERP-Sync" },
         "org_sku": "A-10442",
         "mpn": "1-968849-1",
         "manufacturer": "TE Connectivity",
         "description": "Receptacle 2.8 mm, tin",
         "category_leaf": null,
         "supplier": { "name": "Example Supply", "sku": "ES-968849" },
         "tiers": [{"min_qty": 1, "max_qty": null, "price": {"amount": 0.42, "currency": "EUR"}}],
         "unit_price": { "amount": 0.42, "currency": "EUR", "per": "pcs" },
         "valid_from": "2026-11-01",
         "valid_to": "2027-03-31",
         "order_unit": null,
         "content_unit": "pcs",
         "no_cu_per_ou": 1,
         "price_quantity": 1,
         "minimum_order_quantity": null,
         "order_multiple": null,
         "lead_time_days": null,
         "quantity_in_stock": 4200,
         "notes": null,
         "prices_quotes": true,
         "status": "active",
         "changed_at": "2026-10-30T08:00:41.208113Z"
       }
     ],
     "next_cursor": "MjAyNi0xMC0zMFQwODowMDo0MS4yMDgxMTMrMDA6MDB8NDQxMDk1MXw5MTgzNzc",
     "has_more": false
   }

The first full load is the same, many times: send batches of up to 1,000 rows one after another, each polled to done before the next.

Read your parts from nuqo

GET /materials answers the rows of your Materials tab in nuqo, with the same values, least recently changed first.

1. First, a full pull: no changed_since, include_removed=true, paging with next_cursor while has_more is true. A part changed while the pull runs comes again, further on, with its new values: replace the copy you hold.
2. Then the changes: keep the last next_cursor and poll with it (and include_removed=true). You get the parts added, edited, repriced or deleted since. A change is served once it is 3 minutes old.
3. Nightly, a full pull and compare. It catches the few changes no delta can show: a part of nuqo’s global catalog you removed from your parts is gone, not marked, and nuqo’s own housekeeping (a manufacturer’s name merged, a category refiled) doesn’t move a part’s change time.

curl "https://backend.nuqo.io/api/v1/materials?include_removed=true&limit=100" \
  -H "Authorization: Bearer $NUQO_KEY"

{
  "materials": [
    {
      "listing_id": 918204,
      "part_id": 4410273,
      "catalogue": { "id": 112, "name": "Example Supply 2026" },
      "org_sku": "300-118",
      "mpn": "EX-H4",
      "manufacturer": "Example Housings",
      "description": "Housing, 4 pole, black",
      "category_leaf": "Connectors > Housings",
      "supplier": { "name": "Example Supply", "sku": "ES-H4-01" },
      "tiers": [
        { "min_qty": 1, "max_qty": 499, "price": {"amount": 1.58, "currency": "EUR"} },
        { "min_qty": 500, "max_qty": null, "price": {"amount": 1.42, "currency": "EUR"} }
      ],
      "unit_price": { "amount": 1.58, "currency": "EUR", "per": "pcs" },
      "valid_from": "2026-01-01",
      "valid_to": "2026-12-31",
      "order_unit": null,
      "content_unit": "pcs",
      "no_cu_per_ou": 1,
      "price_quantity": 1,
      "minimum_order_quantity": 100,
      "order_multiple": 50,
      "lead_time_days": 14,
      "quantity_in_stock": 2400,
      "notes": null,
      "prices_quotes": true,
      "status": "active",
      "changed_at": "2026-10-21T16:20:05.774812Z"
    }
  ],
  "next_cursor": "MjAyNi0xMC0yMVQxNjoyMDowNS43NzQ4MTIrMDA6MDB8NDQxMDI3Mw",
  "has_more": false
}

A part’s identity is part_id. org_sku is your article number where you set one, but two parts can share it, so it isn’t a key. A full pull is one request per 100 parts: 24,000 parts are 240 requests, about two minutes under the rate limit.

6Errors, limits and changes

An error answers a stable code for your program and a message for people, which may change.

{
  "error": { "code": "quote_not_finalized", "message": "The quote is a draft or a revision in progress." }
}

Besides the 1010 answer above, only a server error, 500, doesn’t carry this body. Treat any answer without a code by its status. Retry a 500, a 502–504 or a network error with a growing wait (say 2, 4, 8 … seconds, five times), then give up until your next run.

Rate limit

120 requests a minute per key, across every address. Over it, the answer is 429 rate_limited with a Retry-After header giving the whole seconds to wait.

How the API changes

• Additions arrive without notice. A new field, address, parameter or event type can appear any day. Your system ignores what it doesn’t read.
• A field is retired slowly. It is marked deprecated here and in a response header, announced in the changelog, and removed no sooner than 6 months later.
• A real break ships as /v2/ next to /v1/, which keeps running while you move. A check on every change of ours refuses anything else.

7What we assume about your system

We built v1 on these assumptions. Tell us which hold for your system and correct the ones that don’t — the numbers are enough.

1. A1
   Events

   Your system polls GET /events, or it can take HTTPS calls from the internet.

   If not: Tell us which. If it takes inbound HTTPS, webhooks move up our list.

2. A2
   Sign-in

   A static key in an Authorization header is fine for your system.

   If not: Tell us what it needs (e.g. OAuth2 client credentials).

3. A3
   Quotes

   Your ERP keys an assembly on your own number for it, shop_part_number, and it is set on every quote you finalize.

   If not: Tell us which number your ERP files a work plan under.

4. A4
   Work plan

   A work-plan row with no work center (work_center_id: null, with its name and time) is acceptable.

   If not: Every row must name a work center, and we’ll need a default one from you.

5. A5
   Revisions

   A higher revision of a quote replaces the plan you hold for it.

   If not: Tell us how your ERP keeps revisions side by side.

6. A6
   Parts sync

   Your ERP leads on prices, stock, lead time and article data.

   If not: Name the groups nuqo should lead.

7. A7
   Parts sync

   Your article number (org_sku) is your key for a part.

   If not: Tell us the field that is.

8. A8
   Parts sync

   A few thousand parts, synced once a day, and parts added in nuqo don’t need to become new articles in your ERP.

   If not: Tell us your row count, how often, and whether new parts should flow back.