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

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

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

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

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
}

Deactivate Asset

DELETE /api/v2/assets/{id}

Deactivates an asset by setting its is_active status to false. The asset record is preserved for historical purposes.

Response

{
  "id": 123,
  "name": "Office Equipment",
  "client_account_id": 456,
  "sequence_number": 1,
  "is_active": false,
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T16:00:00Z",
  "created_by_id": 789,
  "updated_by_id": 789
}

Deactivation Validation

When attempting to deactivate an asset, the system performs validation to ensure data integrity:

• Balance Checking: The system checks if any accounting accounts with mandatory asset dimensions have non-zero balances for this specific asset.
• Validation Failure: If any accounts have non-zero balances, the deactivation is denied with a 400 Bad Request error.
• Error Details: The error message includes specific account codes and their balances to help identify which transactions need to be resolved.

Example Error Response

{
    "error": "Cannot deactivate asset: account 1200: 15000.00, account 1210: -2500.00",
    "status": 400
}

This validation ensures that assets cannot be deactivated while they still have outstanding balances, maintaining the integrity of your accounting records.

Error Responses

Business Rules

1. Assets are associated with a specific client account
2. Users must have access to the client account to manage its assets
3. The client_account_id cannot be changed after asset creation
4. Each asset is automatically assigned a unique sequence number
5. Creation and update timestamps and user IDs are automatically tracked

Common Use Cases

1. Creating an inventory of company assets
2. Tracking office equipment and furniture
3. Managing vehicle fleet assets
4. Recording property and real estate holdings

Best Practices

1. Use clear and descriptive names for assets
2. Maintain consistent naming conventions
3. Regularly review and update asset information
4. Use the sequence_number for internal reference