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

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:

  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.

Relaterte artikler