Menu

Customers

CRM-side: who you invoice. Business and individual (sole-trader) customers with VIES validation.

Endpoints


GET /api/v1/companies/:companyId/customers

customers.list · scope customers:read

List customers for a company.

Returns active customers in created-first order. Pass ?include_archived=true to include archived rows. Use ?search to match against name or org_number.

Use when: You need a customer roster: for building a UI picker, syncing a CRM, or resolving a customer_id before creating an invoice.

Don't use for: Fetching a single customer you already know the id of: use GET /api/v1/companies/{companyId}/customers/{id}. Suppliers are a separate resource.

Pitfalls

  • Archived customers are hidden by default; the dashboard makes the same choice.
  • org_number is included so callers can match against external CRM identifiers, except where it is a natural person's identity number: a sole trader (enskild firma) has no org number of its own, so its org_number and vat_number come back null in the list. Read the record with GET /customers/{id} for the full value.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
customer_type"individual" | "swedish_business" | "eu_business" | "non_eu_business"noOnly customers of this type.
searchstringnoCase-insensitive match on the name (anywhere) or the org number (prefix), 1-200 characters.
include_archived"true" | "false"notrue also returns archived customers. Default: false.
cursorstringnoOpaque cursor from the previous page's meta.next_cursor. Omit for the first page.
limitnumbernoPage size, 1-100 (default 50). Larger values are clamped to 100.

Response fields

NameTypeDescription
[].idstring
[].handlestring (optional)Typed handle of this customer: cus_ plus its id as 32 lowercase hex. Accepted wherever the id is.
[].namestring
[].customer_type"individual" | "swedish_business" | "eu_business" | "non_eu_business"
[].emailstring | null
[].org_numberstring | null
[].vat_numberstring | null
[].default_payment_termsnumber
[].party_idstring | null (optional)
[].archived_atstring | null
[].created_atstring

Example response

{
  "data": [
    {
      "id": "a8f1…",
      "name": "Acme AB",
      "customer_type": "swedish_business",
      "email": "finance@acme.example",
      "org_number": "556677-8899",
      "vat_number": "SE556677889901",
      "default_payment_terms": 30,
      "archived_at": null,
      "created_at": "2025-04-12T08:30:00Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12",
    "next_cursor": null
  }
}

GET /api/v1/companies/:companyId/customers/:id

customers.get · scope customers:read

Retrieve a single customer by id.

Returns the full customer record. Pass ?expand=invoices to embed any open invoices (sent / partially_paid / overdue) for the customer in the same response; each carries the status the invoice endpoints report, so a sent invoice past its due_date with remaining_amount > 0 reads overdue. Pass ?expand=party to embed the party (motpart) behind the customer: legal name, org and VAT number, country, the SCB company-register summary and what the ledger has seen for it. Private individuals have no party.

Use when: You need the full customer record: address, payment terms, VAT validation status, contact details: before invoicing or syncing to another system.

Don't use for: Listing customers (use the list endpoint). Looking up arbitrary supplier or employee records (different resources).

Pitfalls

  • archived_at is non-null when the customer has been soft-deleted; the customer is still queryable by id but excluded from default lists.
  • vat_number_validated reflects the last successful VIES check; it can become stale if the EU registry revokes a number.
  • personal_number is always returned in the masked form ********-1234; the stored value is encrypted and never leaves the API.

Risk: low · Idempotent: yes · Reversible: no · Dry-run supported: no

Query parameters

NameTypeRequiredDescription
expandstringnoComma-separated related records to embed: invoices, party. An unknown key returns 400 VALIDATION_ERROR.

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this customer: cus_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
customer_typestring
customer_numberstring | null
contact_personstring | null
emailstring | null
phonestring | null
invoice_email_cc_addressesstring[] | null
invoice_email_bcc_addressesstring[] | null
address_line1string | null
address_line2string | null
postal_codestring | null
citystring | null
address_statestring | null
countrystring
org_numberstring | null
vat_numberstring | null
vat_number_validatedboolean
personal_numberstring | null
language"sv" | "en"
default_payment_termsnumber
invoice_referencestring | null
invoice_markingstring | null
notesstring | null
party_idstring | null
archived_atstring | null
created_atstring
updated_atstring
partyobject | null (optional)

Example response

{
  "data": {
    "id": "a8f1…",
    "name": "Acme AB",
    "customer_type": "business",
    "email": "finance@acme.example",
    "org_number": "556677-8899",
    "vat_number": "SE556677889901",
    "vat_number_validated": true,
    "country": "SE",
    "default_payment_terms": 30,
    "archived_at": null,
    "created_at": "2025-04-12T08:30:00Z",
    "updated_at": "2026-04-30T11:22:09Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/customers

customers.create · scope customers:write

Create a customer.

Creates a new customer for the company. Requires Idempotency-Key (UUID). Supports ?dry_run=true for input validation without committing: the dry-run response shows the would-be record minus id and timestamps. EU-business customers with a VAT number are auto-validated against VIES on commit.

Use when: You need to register a new customer before invoicing them. Use dry-run first to catch validation errors before committing.

Don't use for: Updating an existing customer (PATCH instead). Creating suppliers (different resource).

Pitfalls

  • Idempotency-Key is mandatory: calls without it return 400 VALIDATION_ERROR.
  • org_number uniqueness is enforced at the database level; duplicate inserts return 409 CUSTOMER_DUPLICATE_ORG_NUMBER.
  • A personnummer-shaped org_number on customer_type=individual is treated as the personnummer submitted in the wrong field: it is stored encrypted as personal_number, returned masked (********-1234), and org_number is left empty. Prefer passing it as personal_number. Next to a different personal_number in the same body it is a 400.
  • An org_number shaped like a Swedish personnummer is accepted on customer_type=swedish_business: a sole trader (enskild firma) has no separate org number, so its owner's personnummer is the firm's identifier, and the list endpoint masks it. It is rejected for eu_business and non_eu_business, which cannot have one.
  • personal_number is accepted only for customer_type=individual, stored encrypted, and returned in the masked form ********-1234.
  • An individual has no org number: an org_number on customer_type=individual that is not a personnummer is a 400. Leave it empty, or use customer_type=swedish_business for a business.
  • If default_payment_terms is omitted, it defaults to the company setting invoice_default_days, falling back to 30.
  • VIES validation runs only on commit. Dry-run skips the external call and leaves vat_number_validated=false in the preview.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
namestringyes
customer_type"individual" | "swedish_business" | "eu_business" | "non_eu_business"yes
customer_numberstring | nullno
contact_personstring | nullno
emailstringno
phonestringno
invoice_email_cc_addressesstring[] | nullno
invoice_email_bcc_addressesstring[] | nullno
address_line1stringno
address_line2stringno
postal_codestringno
citystringno
address_statestringno
countrystringno
org_numberstringno
vat_numberstringno
personal_numberstring | nullno
language"sv" | "en"no
default_payment_termsnumberno
invoice_referencestring | nullnoFakturareferens: the Er referens (your_reference) a new invoice to this customer gets when the request states none.
invoice_markingstring | nullnoMärkning: the invoice_marking (Peppol BT-13 OrderReference) a new invoice to this customer gets when the request states none.
notesstringno

Response fields

NameTypeDescription
idstring | null
handlestring (optional)Typed handle of this customer: cus_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
customer_type"individual" | "swedish_business" | "eu_business" | "non_eu_business"
customer_numberstring | null
contact_personstring | null
emailstring | null
phonestring | null
invoice_email_cc_addressesstring[] | null
invoice_email_bcc_addressesstring[] | null
address_line1string | null
address_line2string | null
postal_codestring | null
citystring | null
address_statestring | null
countrystring
org_numberstring | null
vat_numberstring | null
vat_number_validatedboolean
personal_numberstring | null
language"sv" | "en"
default_payment_termsnumber
invoice_referencestring | null
invoice_markingstring | null
notesstring | null
party_idstring | null
archived_atstring | null
created_atstring | null
updated_atstring | null

Example request

{
  "name": "Acme AB",
  "customer_type": "swedish_business",
  "email": "finance@acme.test",
  "org_number": "556677-8899",
  "default_payment_terms": 30
}

Example response

{
  "data": {
    "id": "0e9c…",
    "name": "Acme AB",
    "customer_type": "swedish_business",
    "email": "finance@acme.test",
    "org_number": "556677-8899",
    "vat_number_validated": false,
    "default_payment_terms": 30,
    "archived_at": null,
    "created_at": "2026-05-12T16:00:00Z",
    "updated_at": "2026-05-12T16:00:00Z"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/customers/bulk-create

customers.bulk-create · scope customers:write

Create up to 50 customers in one call (partial-success).

Bulk-create endpoint mirroring /invoices/bulk-create. Each customer is validated and inserted independently: per-item failures do not roll back items that succeeded. Returns a results array plus a summary. Idempotent over the whole batch. Dry-runnable.

Use when: You're importing a roster of customers from another CRM, or seeding a fresh company with its existing client list. Use dry-run first to validate the batch.

Don't use for: Updating existing customers: PATCH /customers/{id} once per customer. Bulk uploads of > 50 customers: split into pages of 50. Transactional all-or-nothing imports: passing all_or_nothing: true returns 501 NOT_IMPLEMENTED.

Pitfalls

  • Idempotency-Key is mandatory and covers the WHOLE batch. A retried bulk-create returns the cached full response: it does not retry only the failed items.
  • Passing all_or_nothing: true returns 501 NOT_IMPLEMENTED. Today only partial-success batches exist; omit the flag or pass false.
  • org_number uniqueness is enforced at the DB level: items with duplicates fail individually with CUSTOMER_DUPLICATE_ORG_NUMBER.
  • VIES validation for eu_business customers is best-effort per item; a VIES timeout leaves vat_number_validated=false but does NOT fail the item.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequired
customersobject[]yes
all_or_nothingbooleanno

Response fields

NameType
resultsobject[]
summaryobject

Example request

{
  "customers": [
    {
      "name": "Acme AB",
      "customer_type": "swedish_business",
      "org_number": "556677-8899"
    },
    {
      "name": "Foo OY",
      "customer_type": "eu_business",
      "vat_number": "FI12345678"
    }
  ]
}

Example response

{
  "data": {
    "results": [
      {
        "ok": true,
        "request_index": 0,
        "data": {
          "id": "0e9c…",
          "name": "Acme AB"
        }
      },
      {
        "ok": true,
        "request_index": 1,
        "data": {
          "id": "4d2a…",
          "name": "Foo OY"
        }
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/customers/merge

customers.merge · scope customers:write

Merge duplicate customers into one.

Moves every invoice (quotes, proformas and credit notes included), sales order, recurring invoice, deadline and import source mapping of the merged customers to the survivor in one transaction, then archives the merged customers (kept, never deleted: issued invoices named them). Nothing on the survivor changes and no verifikat is touched. Refuses customers that state different org numbers, VAT numbers or personal numbers. The dry run answers the same counts and writes nothing. Requires Idempotency-Key.

Use when: One buyer has two or more customer cards, e.g. a card created by hand before an import from Fortnox or Visma, and its invoice history is split between them. Dry-run first and check the counts.

Don't use for: Two different buyers that share an org number (departments of one authority): those are separate customers. Merging counterparties (Motparter), which have their own merge in the dashboard. Correcting a customer's details (PATCH the customer).

Pitfalls

  • Idempotency-Key is mandatory.
  • The survivor must be an active customer; a merged customer may already be archived.
  • Issued invoices show the survivor's name and address from now on: pick the card whose details are right, or correct it first.
  • Archived merged customers stay in the register for the retention period and cannot be hard-deleted.
  • Undo is in the dashboard for 30 days (the toast after the merge).

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes · Stage for approval: yes (?stage=true)

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.
stagestringnotrue stages the write for approval instead of committing it: 202 with the pending operation to approve via POST /pending-operations/{id}/approve. Absent or false commits; other values are 400. A reason in the body (why you propose it, at most 500 characters) is shown to the approver as agent_reason and kept with the decision.

Request body

NameTypeRequiredDescription
survivor_customer_idstringyesThe customer card that stays (gnubok_list_customers). Nothing on it changes.
merged_customer_idsstring[]yesThe duplicate cards. Their invoices, orders, recurring invoices and deadlines move to the survivor, then they are archived.

Response fields

NameType
survivorobject
mergedobject[]
totalsobject

Example request

{
  "survivor_customer_id": "7c1e…",
  "merged_customer_ids": [
    "9a42…"
  ]
}

Example response

{
  "data": {
    "survivor": {
      "customer_id": "7c1e…",
      "name": "Exempel AB",
      "customer_number": "120"
    },
    "merged": [
      {
        "customer_id": "9a42…",
        "name": "Exempel AB",
        "customer_number": "120",
        "merge_id": "3f0d…",
        "was_archived": false,
        "invoices": 1,
        "sales_orders": 0,
        "recurring_invoice_schedules": 0,
        "deadlines": 0,
        "source_records": 0
      }
    ],
    "totals": {
      "invoices": 1,
      "sales_orders": 0,
      "recurring_invoice_schedules": 0,
      "deadlines": 0
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

POST /api/v1/companies/:companyId/customers/merges/:mergeId/undo

customers.merge.undo · scope customers:write

Undo a customer merge.

Within 30 days of a merge: moves the invoices, sales orders, recurring invoices, deadlines and import source mappings the merge moved back to the merged customer, where they still point at the survivor, and restores the merged customer's archived state. Rows written to the survivor after the merge stay. The dry run checks the merge exists and can be undone. Requires Idempotency-Key.

Use when: A merge joined two customers that are not the same buyer.

Don't use for: Splitting rows that were on the survivor before the merge: only what the merge moved comes back.

Pitfalls

  • merge_id is merged[].merge_id from the merge's answer.
  • Refused with CUSTOMER_MERGE_UNDO_BLOCKED while the survivor has since been merged into another customer: undo that merge first.
  • After 30 days: CUSTOMER_MERGE_UNDO_EXPIRED.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Response fields

NameType
merge_idstring
survivor_customer_idstring
restored_customer_idstring
restoredobject

Example response

{
  "data": {
    "merge_id": "3f0d…",
    "survivor_customer_id": "7c1e…",
    "restored_customer_id": "9a42…",
    "restored": {
      "invoices": 1,
      "sales_orders": 0,
      "recurring_invoice_schedules": 0,
      "deadlines": 0,
      "source_records": 0
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

PATCH /api/v1/companies/:companyId/customers/:id

customers.update · scope customers:write

Partially update a customer.

Patches the customer with the supplied fields. All fields optional. Idempotent (mandatory Idempotency-Key). Dry-runnable: the dry run answers the would-be record with changes (each changed field, from and to). When vat_number changes on an eu_business customer, VIES re-validation runs on commit (best-effort).

Use when: You need to change a customer's contact details, payment terms, address, or VAT registration. Use dry-run first to confirm the merged record before committing.

Don't use for: Archiving a customer (use DELETE: sets archived_at). Replacing the entire record (no PUT verb is exposed; PATCH is partial).

Pitfalls

  • Idempotency-Key is mandatory; calls without it return 400.
  • An empty body returns 400 VALIDATION_ERROR; an unknown id returns 404 CUSTOMER_NOT_FOUND.
  • org_number uniqueness is enforced at DB level: 23505 → 409 CUSTOMER_DUPLICATE_ORG_NUMBER.
  • VIES re-validation is best-effort and runs only on commit. A VIES timeout does not fail the update.
  • personal_number: a plaintext value is stored encrypted (individual customers only); the masked form a read returned (********-1234) means "leave unchanged" and is never stored; null clears it. Changing customer_type away from individual clears any stored personal_number.
  • An org_number shaped like a Swedish personnummer is accepted on customer_type=swedish_business: an enskild firma has no separate org number, so it is the firm's identifier, and the list endpoint masks it. It is rejected for eu_business and non_eu_business (400 CUSTOMER_ORG_NUMBER_IS_PERSONAL). On an individual it is the personnummer in the wrong field: it is stored encrypted as personal_number and org_number is cleared; next to a different personal_number in the same body it is 400 CUSTOMER_PERSONAL_NUMBER_CONFLICT.
  • An individual has no org number: any other non-empty org_number on customer_type=individual, including one the row would keep through a type change, is 400 CUSTOMER_ORG_NUMBER_ON_INDIVIDUAL. Send org_number "" with the type change to clear it.

Risk: low · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Request body

NameTypeRequiredDescription
namestringno
customer_type"individual" | "swedish_business" | "eu_business" | "non_eu_business"no
customer_numberstring | nullno
contact_personstring | nullno
emailstring | nullno
phonestringno
invoice_email_cc_addressesstring[] | nullno
invoice_email_bcc_addressesstring[] | nullno
address_line1stringno
address_line2stringno
postal_codestringno
citystringno
address_statestringno
countrystringno
org_numberstringno
vat_numberstringno
personal_numberstring | nullno
language"sv" | "en"no
default_payment_termsnumberno
invoice_referencestring | nullnoFakturareferens: the Er referens (your_reference) a new invoice to this customer gets when the request states none.
invoice_markingstring | nullnoMärkning: the invoice_marking (Peppol BT-13 OrderReference) a new invoice to this customer gets when the request states none.
notesstringno

Response fields

NameTypeDescription
idstring
handlestring (optional)Typed handle of this customer: cus_ plus its id as 32 lowercase hex. Accepted wherever the id is.
namestring
customer_typestring
customer_numberstring | null
contact_personstring | null
emailstring | null
phonestring | null
invoice_email_cc_addressesstring[] | null
invoice_email_bcc_addressesstring[] | null
address_line1string | null
address_line2string | null
postal_codestring | null
citystring | null
address_statestring | null
countrystring
org_numberstring | null
vat_numberstring | null
vat_number_validatedboolean
personal_numberstring | null
language"sv" | "en"
default_payment_termsnumber
invoice_referencestring | null
invoice_markingstring | null
notesstring | null
party_idstring | null
archived_atstring | null
created_atstring
updated_atstring
partyobject | null (optional)

Example request

{
  "default_payment_terms": 14,
  "notes": "New payment terms agreed 2026-05-12."
}

Example response

{
  "data": {
    "id": "0e9c…",
    "name": "Acme AB",
    "default_payment_terms": 14,
    "notes": "New payment terms agreed 2026-05-12."
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}

DELETE /api/v1/companies/:companyId/customers/:id

customers.delete · scope customers:write

Archive a customer (soft-delete).

Sets archived_at on the customer; the record is preserved (invoices and audit history remain intact) but excluded from default list responses. To un-archive, PATCH archived_at back to null. Idempotent: archiving an already-archived customer is a no-op. Dry-runnable.

Use when: You want to remove a customer from active rosters without losing their history. Idempotent: re-archiving is safe.

Don't use for: Permanently deleting a customer with all history: the public API does not expose hard-delete. GDPR erasure requests go through a dedicated workflow.

Pitfalls

  • Idempotency-Key is mandatory.
  • A customer who still owes on an invoice (sent / partially_paid / overdue with an amount remaining) cannot be archived: returns 409 CUSTOMER_HAS_INVOICES. Credit notes and fully credited invoices do not count. Issue a kreditfaktura first if you need to close the relationship cleanly. This protects ML 17 kap 24§: the customer record is the canonical source of buyer name/address for invoice reissuance.
  • 204 No Content is returned on success: there is no response body to parse.

Risk: medium · Idempotent: yes · Reversible: yes · Dry-run supported: yes

Query parameters

NameTypeRequiredDescription
dry_runstringnotrue (any case) previews the write without committing it, like the X-Dry-Run: true header. Any other value commits.

Example response

{
  "data": null,
  "meta": {
    "request_id": "req_…",
    "api_version": "2026-05-12"
  }
}