Contracts API

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:

1. Direct Access: Regular customers have direct access to their own client account through ClientAccountUser associations
2. 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

Query Parameters

The GET /contracts endpoint supports the following query parameters:

Attributes

Relationships

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

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:

1. approval_status is APPROVED
2. Current date is on or after start_date (if specified)
3. 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.