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"