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 |
POST | /contracts | Create a new contract |
PATCH | /contracts/{id} | Update a contract or approve/reject |
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 |
approval_status | string | Contract approval status: PENDING, APPROVED, REJECTED |
approved_by_id | integer | The ID of the user who approved/rejected the contract |
approved_at | datetime | When the contract was approved/rejected |
is_active | boolean | Whether the contract is currently active (computed based on approval and dates) |
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 |
Creating Contracts
Providers can create contracts with existing client accounts. New contracts are created with PENDING
approval status and require approval from the client account.
POST /contracts
{
"client_account_id": 789,
"provider_client_account_id": 123,
"service_provided": "ACCOUNTING",
"start_date": "2025-01-01"
}
Response:
{
"id": 456,
"client_account_id": 789,
"provider_client_account_id": 123,
"service_provided": "ACCOUNTING",
"start_date": "2025-01-01",
"approval_status": "PENDING",
"is_active": false,
"created_at": "2025-01-01T10:00:00Z",
"created_by_id": 123
}
Contract Approval Workflow
Approval Status Values
- PENDING: Contract awaits approval from client account (default for new contracts)
- APPROVED: Contract has been approved and is active (if within date range)
- REJECTED: Contract has been rejected and will never be active
Who Can Approve/Reject
Only users with role_id 3 on the client account can approve or reject contracts. This ensures that only authorized client account administrators can make approval decisions.
Approving a Contract
PATCH /contracts/456
{
"approval_status": "APPROVED"
}
Response:
{
"id": 456,
"approval_status": "APPROVED",
"approved_by_id": 999,
"approved_at": "2025-01-01T11:00:00Z",
"is_active": true
}
Rejecting a Contract
PATCH /contracts/456
{
"approval_status": "REJECTED"
}
Response:
{
"id": 456,
"approval_status": "REJECTED",
"approved_by_id": 999,
"approved_at": "2025-01-01T11:00:00Z",
"is_active": false
}
Contract Activity Rules
A contract is considered active (is_active: true
) only when:
approval_status
isAPPROVED
- Current date is on or after
start_date
(if specified) - Current date is on or before
end_date
(if specified)
Authorization Rules
Contract Creation
- Only provider accounts can create contracts
- Provider must have access to their own provider account
- Provider must have access to the target client account
Contract Updates
- Regular updates: Only the provider can update contract details (dates, service description)
- Approval/Rejection: Only users with role_id 3 on the client account can approve/reject
- Core relationships (provider/client accounts) cannot be changed after creation
Auto-Approval Exception
Contracts created during client account creation (via POST /client-accounts with client_contracts) are automatically approved since the provider is creating both the account and contract.
Example Update Request
{
"service_provided": "Accounting and Tax Services",
"start_date": "2023-01-01",
"end_date": "2024-12-31"
}
Notes
- New contracts on existing client accounts require approval from client account users with role_id 3.
- Contracts created during client account creation are automatically approved.
- Only users with access to the provider client account can update contract details.
- Only users with role_id 3 on the client account can approve/reject 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.
- The approved_by_id and approved_at are automatically set when approval status changes.
- 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 approved contracts.
- Use the has_direct_role filter on /client-accounts to distinguish between direct and contract-based access.