Contracts
Contracts define service agreements between client accounts, where one account acts as a service provider (like an accounting firm) and another as a customer. Contracts are a key part of Snapbooks’ access control system:
- Direct Access: Regular customers have direct access to their own client account through ClientAccountUser associations
- Contract-Based Access: Service providers (like accountants and auditors) gain access to their clients’ accounts through contracts, without needing direct user associations
This dual access model enables:
- Customers to manage their own company directly
- Service providers to efficiently manage multiple client accounts
- Clear separation between direct users and external service providers
Endpoints
| Method |
Endpoint |
Description |
| GET |
/contracts |
List contracts |
| GET |
/contracts/{id} |
Get a specific contract |
| PUT |
/contracts/{id} |
Update a contract |
Query Parameters
The GET /contracts endpoint supports the following query parameters:
| Parameter |
Type |
Required |
Description |
| client_account_id |
integer/string |
No |
Filter by client account ID(s). Multiple IDs can be separated by comma, semicolon, or space. If not provided, returns contracts for all eligible client accounts |
| page |
integer |
No |
Page number for pagination (default: 1) |
| per_page |
integer |
No |
Number of items per page (default: 100) |
Attributes
| Attribute |
Type |
Description |
| id |
integer |
The unique identifier of the contract |
| created_at |
datetime |
When the contract was created |
| created_by_id |
integer |
The ID of the user who created the contract |
| client_account_id |
integer |
The ID of the customer client account |
| provider_client_account_id |
integer |
The ID of the provider client account |
| service_provided |
string |
Description of the service being provided |
| start_date |
date |
Start date of the contract |
| end_date |
date |
End date of the contract |
Relationships
| Relationship |
Type |
Description |
| client_account |
ClientAccount |
The customer client account |
| provider_client_account |
ClientAccount |
The provider client account |
Example Response
{
"id": 1,
"created_at": "2023-05-10T12:00:00Z",
"created_by_id": 1,
"client_account_id": 2,
"provider_client_account_id": 1,
"service_provided": "Accounting Services",
"start_date": "2023-01-01",
"end_date": "2023-12-31",
"client_account": {
"id": 2,
"display_name": "Customer Corp"
},
"provider_client_account": {
"id": 1,
"display_name": "Accounting Services Inc"
}
}
Error Responses
| Status Code |
Description |
| 400 |
Invalid request parameters |
| 403 |
User not authorized to access or modify contract |
| 404 |
Contract not found |
| 422 |
Invalid contract dates or service details |
Example Update Request
{
"service_provided": "Accounting and Tax Services",
"start_date": "2023-01-01",
"end_date": "2024-12-31"
}
Notes
- Only users with access to the provider client account can update contracts.
- The provider and customer client accounts cannot be changed after contract creation.
- Client account IDs in query parameters must be from the user’s eligible client accounts.
- Multiple client account IDs can be provided in the query using various separators (comma, semicolon, space).
- All dates are returned in ISO 8601 format.
- The created_by_id is automatically set to the authenticated user’s ID.
- Client account relationships can be included by specifying them in the with_relations parameter.
- Users from the provider account gain access to the customer account through the contract.
- Use the has_direct_role filter on /client-accounts to distinguish between direct and contract-based access.