Quickstart

Three calls, about five minutes, from a new key to a customer you created.

Get a key

An Owner creates a key in Settings → API keys. Pick Read and write, so the third call below works. The key is shown once, when you create it. Copy it somewhere safe: Nummio keeps only a fingerprint of it and cannot show it to you again.

Every request sends that key as a bearer token, and every path starts with https://www.numm.io/api/v1. Requests take JSON and give JSON back.

1. List your businesses

Start here. It proves the key works, and it gives you the business ids every other call takes.

curl "https://www.numm.io/api/v1/businesses" \
  -H "Authorization: Bearer nmo_live_REPLACE_WITH_YOUR_KEY"

The response:

{
  "accountName": "Acme Bookkeeping",
  "businesses": [
    {
      "id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002",
      "name": "Acme Co"
    }
  ]
}

accountName is your account. Each id under businesses is what entityId means everywhere else. A key limited to particular businesses sees only those here.

2. List invoices for one business

Swap the entityId below for an id from step 1. If this key can reach only one business you can leave entityId out entirely; when it can reach several, a call that omits it is refused. The example filters to sent invoices; drop status for all of them.

curl "https://www.numm.io/api/v1/invoices?entityId=0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f1002&status=sent" \
  -H "Authorization: Bearer nmo_live_REPLACE_WITH_YOUR_KEY"

You get back an invoices array and a nextCursor. A null cursor means you have everything. See Rate limits and pagination for walking a longer list.

3. Create a customer

Your first write. The Idempotency-Key header makes it safe to send again if the connection drops. See Idempotency and safe retries.

curl -X POST "https://www.numm.io/api/v1/customers" \
  -H "Authorization: Bearer nmo_live_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0190a1b2-c3d4-7e5f-8a9b-0c1d2e3fee00" \
  -d '{
  "name": "Acme Co",
  "email": "ap@acme.example"
}'

You get back id and created. A customer this call created answers 201. If one with that name already exists, that one comes back with created set to false, nothing changes, and the status is 200.

What to read next

• Authentication and keeping keys safe, for what each access level opens and where a key must never go.
• Errors, for the one error shape and the code to branch on.
• Rate limits and pagination, for how much you can ask for and how to page.
• Idempotency and safe retries, before you write anything in earnest.
• What the API will never do, for the limits and the two calls that email your customer before they return.
• The reference, for every endpoint, field by field.