API reference

Contacts

One contact book for customers and vendors. Bank details and internal notes never leave KWN.

List contacts

GET/contacts

Needs: contacts.read
Scopes: sales:readpurchase:readcontacts:read

Customers and vendors, newest first: type=customer or vendor, search by name, TRN or email, active=false for the archived. Bank accounts and internal notes are never returned.

Parameters

Field	Type	Description
`type`Query	`string`	customer or vendor.
`search`Query	`string`
`active`Query	`boolean`	true (default) for active contacts, false for archived.
`limit`Query	`integer`	1 to 200; 50 by default.
`cursor`Query	`string`	The previous page's next.
`updatedSince`Query	`date`	Only rows changed at or after this instant.
`createdFrom`Query	`date`
`createdTo`Query	`date`
`externalId`Query	`string`	Only the row your system gave this id.

Code samples

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

Responses

200OK
Field Type Description
data object[] The rows of this page.
next string The cursor of the next page, to send as ?cursor=; null on the last page.
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

Field	Type	Description
`data`	`object[]`	The rows of this page.
`next`	`string`	The cursor of the next page, to send as ?cursor=; null on the last page.

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

Create a contact

POST/contacts

Needs: contacts.write
Scopes: sales:writepurchase:writecontacts:write

Send an Idempotency-Key header.

A customer by default (isCustomer), a vendor with isVendor. A UAE company's TRN is 15 digits. Requires Idempotency-Key.

Parameters

Field	Type	Description
`Idempotency-Key`HeaderRequired	`string`	1 to 100 visible ASCII characters, such as a UUID, unique to this request. Sent again with the same request, the first answer is replayed (Idempotent-Replayed: true); with another request, 422 IDEMPOTENCY_KEY_REUSED.

Request body

25 fields

Field	Type	Description
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`trn`	`string`	15 digits for a contact in the UAE.
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

Code samples

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 '{
  "name": "Al Noor Trading L.L.C.",
  "isCompany": true,
  "isCustomer": true,
  "trn": "100398765400003",
  "email": "accounts@alnoor.example",
  "phone": "+971 4 555 0142",
  "address": "Office 1204, Bay Square, Business Bay",
  "city": "Dubai",
  "emirate": "DUBAI",
  "country": "AE",
  "externalId": "CUST-0091"
}'

Responses

201Created

Field	Type	Description
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

422That Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).

Example

{
  "error": "That Idempotency-Key was used for a different request.",
  "code": "IDEMPOTENCY_KEY_REUSED"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

Read a contact

GET/contacts/{id}

Needs: contacts.read
Scopes: sales:readpurchase:readcontacts:read

One contact of this company.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Code samples

curl -sS -X GET "https://app.kwn.tax/api/v1/contacts/<id>" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

200OK

Field	Type	Description
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

Update a contact

PUT/contacts/{id}

Needs: contacts.write
Scopes: sales:writepurchase:writecontacts:write

An optional field left out keeps what is on file.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Request body

25 fields

Field	Type	Description
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`trn`	`string`	15 digits for a contact in the UAE.
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`	Your system's id for it, kept for good. Create only.

Code samples

curl -sS -X PUT "https://app.kwn.tax/api/v1/contacts/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Al Noor Trading L.L.C.",
  "isCompany": true,
  "isCustomer": true,
  "trn": "100398765400003",
  "email": "accounts@alnoor.example",
  "phone": "+971 4 555 0142",
  "address": "Office 1204, Bay Square, Business Bay",
  "city": "Dubai",
  "emirate": "DUBAI",
  "country": "AE",
  "externalId": "CUST-0091"
}'

Responses

200OK

Field	Type	Description
`id`	`string`
`customerNo`	`string`
`name`	`string`
`isCompany`	`boolean`
`isCustomer`	`boolean`
`isVendor`	`boolean`
`active`	`boolean`
`trn`	`string`
`email`	`string`
`phone`	`string`
`mobile`	`string`
`website`	`string`
`address`	`string`
`street2`	`string`
`city`	`string`
`zip`	`string`
`state`	`string`
`emirate`	`ABU_DHABI \| DUBAI \| SHARJAH \| AJMAN \| UMM_AL_QUWAIN \| RAS_AL_KHAIMAH \| FUJAIRAH`
`country`	`string`
`parentId`	`string`
`companyName`	`string`
`paymentTermId`	`string`
`vendorPaymentTermId`	`string`
`fiscalPositionId`	`string`
`salespersonId`	`string`
`creditLimit`	`number`
`tags`	`string[]`
`externalId`	`string`
`createdAt`	`date`
`updatedAt`	`date`

400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

Archive a contact

POST/contacts/{id}/archive

Needs: contacts.write
Scopes: sales:writepurchase:writecontacts:write

The contact leaves the lists; its documents keep it. Archived already: alreadyDone.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/contacts/<id>/archive" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

200OK
Field Type Description
alreadyDone boolean True when the document was already where the action takes it; nothing changed.
document object
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

Field	Type	Description
`alreadyDone`	`boolean`	True when the document was already where the action takes it; nothing changed.
`document`	`object`

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}

Restore a contact

POST/contacts/{id}/restore

Needs: contacts.write
Scopes: sales:writepurchase:writecontacts:write

Active already: alreadyDone.

Parameters

Field	Type	Description
`id`PathRequired	`string`

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/contacts/<id>/restore" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

200OK
Field Type Description
alreadyDone boolean True when the document was already where the action takes it; nothing changed.
document object
400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).
Example
```
{
  "error": "Lines: at least one line is required.",
  "code": "REQUEST_INVALID"
}
```
401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).
Example
```
{
  "error": "That API key is not valid, or it was revoked.",
  "code": "API_KEY_INVALID"
}
```
403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).
Example
```
{
  "error": "This key's scopes do not include sales.approve.",
  "code": "ROLE_TOO_LOW"
}
```
404Not found: another type under this route, or another company's (NOT_FOUND).
Example
```
{
  "error": "Not found.",
  "code": "NOT_FOUND"
}
```

Field	Type	Description
`alreadyDone`	`boolean`	True when the document was already where the action takes it; nothing changed.
`document`	`object`

409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

Example

{
  "error": "That externalId is already used by another record of this company.",
  "code": "EXTERNAL_ID_TAKEN"
}

429Too many requests: wait retryAfter seconds (RATE_LIMITED).

Example

{
  "error": "Too many requests. Wait a little and try again.",
  "code": "RATE_LIMITED"
}