Contracts

GET /api/v2/contracts

List contracts.

Every contract of the Organisation in ascending id order, at most 50 a page.

• Operation ID: listContracts
• Authentication: A Bearer token from a credential holding the read scope.
• Also served at /funding_system/api/v2/contracts, the documented product’s alias path.

curl "https://your-org.backed.giving/api/v2/contracts" \
  -H "Authorization: Bearer $BACKED_TOKEN"

Parameters

200 response

A JSON array of contracts.

[
  {
    "id": 640,
    "created_at": "2026-03-02T21:15:04.000Z",
    "updated_at": "2026-06-18T03:40:11.000Z",
    "title": "Funding agreement: Te Awa river restoration",
    "amount": "24500.0",
    "contract_start_date": "2026-08-01",
    "contract_end_date": "2027-07-31",
    "state": "signed",
    "contract_type": "standard",
    "registration_entity": {
      "id": 311,
      "name": "Te Awa Restoration Trust"
    },
    "lock_version": 1
  }
]

400 response

A query parameter is invalid, or a write’s body is not a JSON object.

{
  "error": "invalid_request",
  "error_description": "limit is invalid"
}

401 response

The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token.

Headers: WWW-Authenticate.

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

403 response

The request was sent over plain HTTP and was not processed.

{
  "error": "https_required"
}

404 response

An unknown host or path, or an id that is unknown, deleted or of another Organisation.

{
  "error": "not_found"
}

429 response

A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.

Headers: Retry-After.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "error": "server_error"
}

503 response

The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Headers: Retry-After.

{
  "error": "temporarily_unavailable"
}

GET /api/v2/contracts/{id}

Get one contract.

The same object as the list item.

• Operation ID: getContract
• Authentication: A Bearer token from a credential holding the read scope.
• Also served at /funding_system/api/v2/contracts/{id}, the documented product’s alias path.

curl "https://your-org.backed.giving/api/v2/contracts/42" \
  -H "Authorization: Bearer $BACKED_TOKEN"

Parameters

200 response

The contract.

{
  "id": 640,
  "created_at": "2026-03-02T21:15:04.000Z",
  "updated_at": "2026-06-18T03:40:11.000Z",
  "title": "Funding agreement: Te Awa river restoration",
  "amount": "24500.0",
  "contract_start_date": "2026-08-01",
  "contract_end_date": "2027-07-31",
  "state": "signed",
  "contract_type": "standard",
  "registration_entity": {
    "id": 311,
    "name": "Te Awa Restoration Trust"
  },
  "lock_version": 1
}

401 response

The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token.

Headers: WWW-Authenticate.

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

403 response

The request was sent over plain HTTP and was not processed.

{
  "error": "https_required"
}

404 response

An unknown host or path, or an id that is unknown, deleted or of another Organisation.

{
  "error": "not_found"
}

429 response

A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.

Headers: Retry-After.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "error": "server_error"
}

503 response

The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Headers: Retry-After.

{
  "error": "temporarily_unavailable"
}

POST /api/v2/contracts/{id}/status

Record a contract executed or terminated.

executed is the Administrator’s counter-signature (contracts.counter_sign); terminated is Terminate Contract (contracts.terminate) and needs a reason. Needs the Contracts module.

• Operation ID: recordContractStatus
• Authentication: A Bearer token from a credential holding the write:post_award scope. Runs as the credential’s Administrator, and needs an Idempotency-Key header.

curl -X POST "https://your-org.backed.giving/api/v2/contracts/42/status" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \
  -H "Content-Type: application/json" \
  -d '{"status":"executed"}'

Parameters

Request body

application/json, the ContractStatusChange schema. The status to record: executed (the Administrator’s counter-signature) or terminated (with a reason). Any other value is 409 invalid_transition.

{
  "status": "executed"
}

200 response

The contract as the single read answers it.

Headers: Idempotent-Replayed.

{
  "id": 640,
  "created_at": "2026-03-02T21:15:04.000Z",
  "updated_at": "2026-06-18T03:40:11.000Z",
  "title": "Funding agreement: Te Awa river restoration",
  "amount": "24500.0",
  "contract_start_date": "2026-08-01",
  "contract_end_date": "2027-07-31",
  "state": "signed",
  "contract_type": "standard",
  "registration_entity": {
    "id": 311,
    "name": "Te Awa Restoration Trust"
  },
  "lock_version": 1
}

400 response

idempotency_key_required: The write has no Idempotency-Key header of 1 to 255 characters. invalid_request: A query parameter is invalid, or a write’s body is not a JSON object.

{
  "error": "idempotency_key_required",
  "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}

{
  "error": "invalid_request",
  "error_description": "limit is invalid"
}

401 response

The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token.

Headers: WWW-Authenticate.

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

403 response

https_required: The request was sent over plain HTTP and was not processed. insufficient_scope: The credential does not hold the scope the route needs. run_as_disabled: The credential has no run-as Administrator, or that person is no longer one. forbidden: The run-as Administrator lacks the permission, or the record is outside their Data Access Rules.

Headers: WWW-Authenticate.

{
  "error": "https_required"
}

{
  "error": "insufficient_scope",
  "error_description": "This credential lacks the write:applications scope"
}

{
  "error": "run_as_disabled",
  "error_description": "This credential has no enabled run-as Administrator"
}

{
  "error": "forbidden",
  "error_description": "The run-as Administrator may not do this to this record"
}

404 response

not_found: An unknown host or path, or an id that is unknown, deleted or of another Organisation. module_disabled: The Organisation has the module this route belongs to turned off.

{
  "error": "not_found"
}

{
  "error": "module_disabled",
  "error_description": "This module is not enabled for the Organisation"
}

409 response

idempotency_in_progress: The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds. invalid_transition: The move is not open from where the record stands; current_status says where that is. invalid_state: The record is not in a state that admits this write.

Headers: Retry-After.

{
  "error": "idempotency_in_progress",
  "error_description": "The first request with this Idempotency-Key has not finished. If this persists it stopped part-way: check whether the record exists before writing again with a new key"
}

{
  "error": "invalid_transition",
  "error_description": "The record cannot make this move from approved",
  "current_status": "approved"
}

{
  "error": "invalid_state",
  "error_description": "The target does not take files in its current state"
}

413 response

The body, or the declared file, is larger than the limit that applies.

{
  "error": "payload_too_large",
  "error_description": "The request body is too large"
}

415 response

The body is not application/json, or the target does not accept the file’s content type.

{
  "error": "unsupported_media_type",
  "error_description": "The request body must be application/json"
}

422 response

idempotency_key_reused: The Idempotency-Key was used in the last 24 hours for a different method, path or body. unknown_field: The body has a property the route does not document; the first is named. validation_failed: Body values the product’s own form would refuse; fields names each.

{
  "error": "idempotency_key_reused",
  "error_description": "This Idempotency-Key was used for a different request"
}

{
  "error": "unknown_field",
  "error_description": "bank_account_number is not a writable field"
}

{
  "error": "validation_failed",
  "error_description": "Invalid fields: due_date",
  "fields": [
    "due_date"
  ]
}

429 response

A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.

Headers: Retry-After.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "error": "server_error"
}

503 response

The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Headers: Retry-After.

{
  "error": "temporarily_unavailable"
}