Companies API
The Companies API allows you to manage companies in your BillOver account.
Contents
- Base URL
- Field Definitions
- List Companies
- Get Company
- Create Company
- Update Company
- Delete Company
- Example Usage
Base URL
https://api.billover.com/v1/companies/
Field Definitions
Common Fields
| Field | Type | Description | Required |
|---|---|---|---|
| uid | UUID | Unique identifier for the company | Read-only |
| hf_id | string | Human-friendly ID | Read-only |
| name | string | Company name | Yes |
| address | string | Company address | Yes (can be blank) |
| tax_number | string | Tax number | Yes (can be blank) |
| tax_office | string | Tax office | Yes (can be blank) |
| phone | string | Phone number | Yes (can be blank) |
| permissions | object | User permissions for this company | Read-only |
| created_at | datetime | Creation date | Read-only |
| updated_at | datetime | Last update date | Read-only |
List Companies
Retrieve a list of all companies.
GET /v1/companies/
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| query | string | Search in name, tax number, tax office, phone, address, and human-friendly ID |
Response
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"hf_id": "ABC",
"name": "Acme Corporation",
"address": "123 Main St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+1234567890",
"permissions": {
"can_update": true,
"can_delete": true
},
"created_at": "2024-01-30T12:00:00Z",
"updated_at": "2024-01-30T12:00:00Z"
},
{
"uid": "89ef0123-4567-89ab-cdef-0123456789ab",
"hf_id": "XYZ",
"name": "Beta Industries",
"address": "456 Other St, City",
"tax_number": "0987654321",
"tax_office": "East Tax Office",
"phone": "+0987654321",
"permissions": {
"can_update": true,
"can_delete": true
},
"created_at": "2024-01-29T12:00:00Z",
"updated_at": "2024-01-29T12:00:00Z"
}
]
}
Get Company
Retrieve a specific company by ID.
GET /v1/companies/{uid}
Response
{
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"hf_id": "ABC",
"name": "Acme Corporation",
"address": "123 Main St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+1234567890",
"permissions": {
"can_update": true,
"can_delete": true
},
"created_at": "2024-01-30T12:00:00Z",
"updated_at": "2024-01-30T12:00:00Z"
}
Create Company
Create a new company.
POST /v1/companies/
Request Body
{
"name": "Acme Corporation",
"address": "123 Main St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+1234567890"
}
Response
{
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"hf_id": "ABC",
"name": "Acme Corporation",
"address": "123 Main St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+1234567890",
"permissions": {
"can_update": true,
"can_delete": true
},
"created_at": "2024-01-30T12:00:00Z",
"updated_at": "2024-01-30T12:00:00Z"
}
Update Company
Update an existing company.
PUT /v1/companies/{uid}
Request Body
{
"name": "Acme Corporation Updated",
"address": "456 New St, City",
"phone": "+9876543210"
}
Response
{
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"hf_id": "ABC",
"name": "Acme Corporation Updated",
"address": "456 New St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+9876543210",
"permissions": {
"can_update": true,
"can_delete": true
},
"created_at": "2024-01-30T12:00:00Z",
"updated_at": "2024-01-30T12:30:00Z"
}
Delete Company
Delete an existing company.
DELETE /v1/companies/{uid}
Response
HTTP/1.1 204 No Content
Example Usage
List Companies
curl -X GET \
'https://api.billover.com/v1/companies/?search=Acme' \
-H 'Api-Key: YOUR_API_KEY'
Get Company
curl -X GET \
https://api.billover.com/v1/companies/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY'
Create a Company
curl -X POST \
https://api.billover.com/v1/companies/ \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Acme Corporation",
"address": "123 Main St, City",
"tax_number": "1234567890",
"tax_office": "Central Tax Office",
"phone": "+1234567890"
}'
Update a Company
curl -X PUT \
https://api.billover.com/v1/companies/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Acme Corporation Updated",
"address": "456 New St, City",
"phone": "+9876543210"
}'
Delete Company
curl -X DELETE \
https://api.billover.com/v1/companies/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY'