Organization
Organization management, statistics, and user membership
List user's organizations
GET /api/v1/organizations
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: organization.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
search |
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/organizations" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Get organization details
GET /api/v1/organizations/{id}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: organization.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/organizations/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Update organization
PUT /api/v1/organizations/{id}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: organization.update
country is immutable once the organization exists and is not accepted here. currency is locked once any financial document (invoice/quote/expense/credit note) exists — attempting to change it then returns 422. subdivision_code is editable going-forward.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | no | |
currency |
string | no | Base currency (ISO 4217). Locked once financial documents exist; a locked change returns 422. |
timezone |
string | no | |
language |
string | no | |
subdivision_code |
string | no | ISO 3166-2 subdivision code (e.g. CA-QC). Validated against the country_subdivisions reference table. Editable going-forward. |
settings |
array | no | |
address_line1 |
string | no | Company-profile / legal-header fields |
address_line2 |
string | no | |
city |
string | no | |
postal_code |
string | no | |
state |
string | no | |
contact_name |
string | no | |
contact_email |
string | no | |
contact_phone |
string | no | |
logo |
string | no | |
tax_number |
string | no | |
registration_number |
string | no | |
legal_form |
string | no | |
website |
string | no |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 403 | |
| 422 | Validation failed, OR an immutable/locked field was changed — changing currency once financial documents exist (or country, which is never accepted) returns the reason under errors.currency / errors.country with error: field_immutable. |
Example request
curl -X PUT "https://kworia.com/api/v1/organizations/{id}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"currency": "string",
"timezone": "string",
"language": "string",
"subdivision_code": "string",
"settings": [],
"address_line1": "string",
"address_line2": "string",
"city": "string",
"postal_code": "string",
"state": "string",
"contact_name": "string",
"contact_email": "string",
"contact_phone": "string",
"logo": "string",
"tax_number": "string",
"registration_number": "string",
"legal_form": "string",
"website": "string"
}'
Get organization statistics (Core only)
GET /api/v1/organizations/{id}/statistics
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: organization.view
NOTE: Invoicing statistics moved to ReportingController (Invoicing plugin) to maintain plugin architecture. Core should not depend on plugins.
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/organizations/{id}/statistics" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
List organization users
GET /api/v1/organizations/{id}/users
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: users.view
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes | |
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/organizations/{id}/users" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"
Invite user to organization
POST /api/v1/organizations/{id}/users/invite
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: users.invite
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string | yes | |
role |
string | yes |
Responses
| Status | Description |
|---|---|
| 404 | |
| 201 | For non-paginated data, return as before |
| 400 | |
| 403 | |
| 422 |
Example request
curl -X POST "https://kworia.com/api/v1/organizations/{id}/users/invite" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"email": "string",
"role": "string"
}'
Update user role
PUT /api/v1/organizations/{id}/users/{userId}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: users.update
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes | |
userId |
path | integer | yes |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role |
string | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 400 | |
| 403 | |
| 422 |
Example request
curl -X PUT "https://kworia.com/api/v1/organizations/{id}/users/{userId}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"role": "string"
}'
Remove user from organization
DELETE /api/v1/organizations/{id}/users/{userId}
Requires authentication (Bearer token) and the X-Organization-Id header.
API token scope: users.delete
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | integer | yes | |
userId |
path | integer | yes |
Responses
| Status | Description |
|---|---|
| 200 | For non-paginated data, return as before |
| 400 | |
| 403 |
Example request
curl -X DELETE "https://kworia.com/api/v1/organizations/{id}/users/{userId}" \
-H "Authorization: Bearer {{access_token}}" \
-H "X-Organization-Id: {{organization_id}}" \
-H "Accept: application/json"