Assets
Assets represent items of value owned by a company, such as equipment, vehicles, or property. The assets API allows you to manage and track these assets within Snapbooks.
Endpoints
List Assets
GET /api/v2/assets
Retrieves a paginated list of assets.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| client_account_id | integer | No | Filter assets by client account |
| page | integer | No | Page number (default: 1) |
| per_page | integer | No | Items per page (default: 100, max: 100) |
| with | string | No | Include related resources (supported: client_account, created_by) |
Response
{
"data": [
{
"id": 123,
"name": "Office Equipment",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789,
"client_account": { // Only included when with=client_account
"id": 456,
"unique_name": "company-abc",
"display_name": "Company ABC"
},
"created_by": { // Only included when with=created_by
"id": 789,
"first_name": "John",
"last_name": "Doe",
"created_at": "2023-01-01T00:00:00Z",
"profile_image_url": null,
"last_login": "2024-03-15T14:30:00Z"
}
}
],
"meta": {
"page": 1,
"pages": 1,
"per_page": 100,
"records": 1
}
}
Get Asset
GET /api/v2/assets/{id}
Retrieves a specific asset by ID.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| with | string | No | Include related resources (supported: client_account, created_by) |
Response
{
"id": 123,
"name": "Office Equipment",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Create Asset
POST /api/v2/assets
Creates a new asset.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The name of the asset |
| client_account_id | integer | Yes | The ID of the client account |
Example Request
{
"name": "Office Equipment",
"client_account_id": 456
}
Response
{
"id": 123,
"name": "Office Equipment",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T10:00:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Update Asset
PUT /api/v2/assets/{id}
Updates an existing asset.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The new name for the asset |
Example Request
{
"name": "Updated Equipment Name"
}
Response
{
"id": 123,
"name": "Updated Equipment Name",
"client_account_id": 456,
"sequence_number": 1,
"created_at": "2024-03-15T10:00:00Z",
"updated_at": "2024-03-15T15:30:00Z",
"created_by_id": 789,
"updated_by_id": 789
}
Error Responses
| Status Code | Description |
|---|---|
| 400 | Invalid request (e.g., missing required fields) |
| 403 | Forbidden (no access to client account) |
| 404 | Asset not found |
Business Rules
- Assets are associated with a specific client account
- Users must have access to the client account to manage its assets
- The client_account_id cannot be changed after asset creation
- Each asset is automatically assigned a unique sequence number
- Creation and update timestamps and user IDs are automatically tracked
Common Use Cases
- Creating an inventory of company assets
- Tracking office equipment and furniture
- Managing vehicle fleet assets
- Recording property and real estate holdings
Best Practices
- Use clear and descriptive names for assets
- Maintain consistent naming conventions
- Regularly review and update asset information
- Use the sequence_number for internal reference