Skip to content
On this page

Customer

Customer management, archival, and per-customer statistics

Display a listing of customers

GET /api/v1/customers

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Parameters

Name In Type Required Description
search query string no
is_active query string no
sort query string no
page query integer no
per_page query integer no

Responses

Status Description
200 For non-paginated data, return as before
422

Example request

curl -X GET "https://kworia.com/api/v1/customers" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Store a newly created customer

POST /api/v1/customers

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.create

vat_number is THE customer's VAT number: it becomes the buyer VAT identifier on e-invoices (EN 16931 BT-48), in every country. tax_number is the local tax id, never used as the VAT number. An Italian business customer addressed by its codice destinatario (einvoicing_identifier_scheme IT:CUUO) needs vat_number: without it, an e-invoice send is refused before anything is transmitted. Both fields are stored encrypted and returned decrypted to the owning organization. Sending null or an empty string clears a field; leaving it out keeps it unchanged.

Request body

Field Type Required Description
name string yes
email string no
phone string no
website string no
tax_number string no
vat_number string no THE buyer VAT number (BT-48,); tax_number stays the local tax id.
address_line1 string no
address_line2 string no
city string no
state string no
postal_code string no
country string no
billing_subdivision_code string no ISO 3166-2 subdivision code for the billing address (e.g. CA-QC). Validated against the country_subdivisions reference table.
shipping_subdivision_code string no ISO 3166-2 subdivision code for the shipping address (e.g. CA-QC). Validated against the country_subdivisions reference table.
notes string no
language string no Customer locale defaults and e-invoicing network identifier. Scheme and value only make sense together; either both or neither.
currency string no
einvoicing_identifier_scheme string no
einvoicing_identifier_value string no

Responses

Status Description
201 For non-paginated data, return as before
422
403

Example request

curl -X POST "https://kworia.com/api/v1/customers" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "tax_number": "string",
    "vat_number": "string",
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string",
    "billing_subdivision_code": "string",
    "shipping_subdivision_code": "string",
    "notes": "string",
    "language": "string",
    "currency": "string",
    "einvoicing_identifier_scheme": "string",
    "einvoicing_identifier_value": "string"
}'

Display the specified customer

GET /api/v1/customers/{id}

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Parameters

Name In Type Required Description
id path integer yes

Responses

Status Description
200 For non-paginated data, return as before

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Update the specified customer

PUT /api/v1/customers/{id}

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.update

vat_number is THE customer's VAT number: it becomes the buyer VAT identifier on e-invoices (EN 16931 BT-48), in every country. tax_number is the local tax id, never used as the VAT number. An Italian business customer addressed by its codice destinatario (einvoicing_identifier_scheme IT:CUUO) needs vat_number: without it, an e-invoice send is refused before anything is transmitted. Both fields are stored encrypted and returned decrypted to the owning organization. Sending null or an empty string clears a field; leaving it out keeps it unchanged.

Parameters

Name In Type Required Description
id path integer yes

Request body

Field Type Required Description
name string no
email string no
phone string no
website string no
tax_number string no
vat_number string no THE buyer VAT number (BT-48,); tax_number stays the local tax id.
address_line1 string no
address_line2 string no
city string no
state string no
postal_code string no
country string no
billing_subdivision_code string no ISO 3166-2 subdivision code for the billing address (e.g. CA-QC). Validated against the country_subdivisions reference table.
shipping_subdivision_code string no ISO 3166-2 subdivision code for the shipping address (e.g. CA-QC). Validated against the country_subdivisions reference table.
notes string no
language string no Customer locale defaults and e-invoicing network identifier. Scheme and value only make sense together; either both or neither.
currency string no
einvoicing_identifier_scheme string no
einvoicing_identifier_value string no

Responses

Status Description
200 For non-paginated data, return as before
422
403

Example request

curl -X PUT "https://kworia.com/api/v1/customers/{id}" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "tax_number": "string",
    "vat_number": "string",
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string",
    "billing_subdivision_code": "string",
    "shipping_subdivision_code": "string",
    "notes": "string",
    "language": "string",
    "currency": "string",
    "einvoicing_identifier_scheme": "string",
    "einvoicing_identifier_value": "string"
}'

Remove the specified customer

DELETE /api/v1/customers/{id}

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.delete

Parameters

Name In Type Required Description
id path integer yes

Responses

Status Description
200 For non-paginated data, return as before

Example request

curl -X DELETE "https://kworia.com/api/v1/customers/{id}" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Get customer's invoices

GET /api/v1/customers/{id}/invoices

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Parameters

Name In Type Required Description
id path integer yes
status query string no
page query integer no
per_page query integer no

Responses

Status Description
200 For non-paginated data, return as before
422

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}/invoices" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Get customer's quotes

GET /api/v1/customers/{id}/quotes

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Parameters

Name In Type Required Description
id path integer yes
status query string no
page query integer no
per_page query integer no

Responses

Status Description
200 For non-paginated data, return as before
422

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}/quotes" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Customer statement of account

GET /api/v1/customers/{id}/statement

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Opening balance, invoice/payment/credit-note entries and closing balance for the period (date_from/date_to required), in the organization currency.

Parameters

Name In Type Required Description
id path integer yes
date_from query string yes
date_to query string yes

Responses

Status Description
200 For non-paginated data, return as before
422

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}/statement" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Get customer statistics

GET /api/v1/customers/{id}/statistics

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Parameters

Name In Type Required Description
id path integer yes

Responses

Status Description
200 For non-paginated data, return as before

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}/statistics" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"

Validate the customer's e-invoicing identifier on the network

GET /api/v1/customers/{id}/validate-network

Requires authentication (Bearer token) and the X-Organization-Id header.

API token scope: customers.view

Looks up the customer's stored einvoicing_identifier_scheme/einvoicing_identifier_value on the e-invoicing network of the provider resolved for the customer's country, and persists a successful verification (einvoicing_identifier_verified). Returns 422 when the customer has no identifier stored, when no country can be resolved (the customer country, billing country, or a country-specific identifier scheme all absent), or when the resolved provider (e.g. FNE clearance countries) does not support participant lookup. When the customer has no stored country it is inferred from a country-specific identifier scheme (e.g. 0208 → BE). A verified: false result never clears an earlier successful verification, because provider transport errors are indistinguishable from a genuine not-found.

Parameters

Name In Type Required Description
id path integer yes

Responses

Status Description
422
200 For non-paginated data, return as before

Example request

curl -X GET "https://kworia.com/api/v1/customers/{id}/validate-network" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "X-Organization-Id: {{organization_id}}" \
  -H "Accept: application/json"