Get started

Quickstart

Create a key, make your first call, and send an invoice for clearance.

1. Create a key

Sign in to KWN as the company’s Owner, or as a user who manages Settings.
Open Settings → Integrations → API keys and choose New key.
Name it after the system that will use it, and tick the scopes it needs — for this guide, Sales: approve and Contacts: write.
Copy the key. It is shown once; KWN keeps only a hash of it. Keep it in your secret store, never in source code or a browser.

A company holds at most ten active keys. A key is never more powerful than the person who created it, and never reaches an app outside the company’s plan.

2. Make your first call

GET /me needs no scope. It answers which company the key belongs to and what it may do — the call to make whenever a key is new.

bash

curl -sS https://app.kwn.tax/api/v1/me \
  -H "X-Api-Key: $KWN_API_KEY"

json

{
  "merchant": { "id": "cm…", "name": "Al Noor Trading", "legalName": "Al Noor Trading L.L.C.", "trn": "100234567800003" },
  "key": { "id": "cm…", "name": "Shop connector", "prefix": "kwn_live_3f2", "scopes": ["sales:approve", "contacts:read"], "createdAt": "2026-10-21T08:12:00Z" },
  "capabilities": ["sales.read", "sales.write", "sales.approve", "contacts.read", "products.read"],
  "apps": ["sales", "contacts"],
  "eInvoicing": { "mode": "LIVE", "available": true }
}

3. Add a customer

Every creating POST needs an Idempotency-Key, so a retry never creates twice. externalId is your own system’s id for the record; find it again with ?externalId=.

bash

curl -sS -X POST https://app.kwn.tax/api/v1/contacts \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "CUST-1042",
    "name": "Gulf Office Supplies L.L.C.",
    "isCompany": true,
    "trn": "100398765400003",
    "email": "accounts@gulfoffice.example",
    "city": "Dubai",
    "emirate": "DUBAI",
    "country": "AE"
  }'

4. Send an invoice for clearance

One call checks the invoice, files it in Sales, approves it and submits it to the FTA. It takes one invoice credit, once — the same externalId sent again takes no second credit.

bash

curl -sS -X POST https://app.kwn.tax/api/v1/einvoices \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "INV-2026-00042",
    "sellerTrn": "100234567800003",
    "issueDate": "2026-10-15",
    "customer": {
      "name": "Al Noor Trading L.L.C.", "isCompany": true, "trn": "100398765400003",
      "address": "Office 1204, Bay Square", "city": "Dubai", "emirate": "DUBAI", "country": "AE"
    },
    "lines": [
      { "description": "Bookkeeping, October 2026", "quantity": 1, "unitPrice": 2500, "taxRate": 5 }
    ],
    "expectedTotal": 2625
  }'

http

HTTP/1.1 201 Created
{ "id": "cm…", "externalId": "INV-2026-00042", "number": "INV-2026-0042",
  "status": "PENDING", "total": 2625, "duplicate": false, "resubmitted": false, … }

5. Follow its status

Clearance is asynchronous. Read the e-invoice until it is CLEARED, REJECTED or FAILED — or list them with updatedSince to pick up every change at once (Pagination and sync).

bash

curl -sS https://app.kwn.tax/api/v1/einvoices/<id> \
  -H "X-Api-Key: $KWN_API_KEY"
# …until "status" is CLEARED, REJECTED or FAILED