Disbursements

The Disbursements API allows you to retrieve information about payment disbursements for approved grants. Disbursements represent individual payments made to grantees.

Security Note

Bank account details in disbursement records are partially redacted for security. Only the last 4 digits of account numbers and last 2 digits of sort codes are visible.

List Disbursements

Retrieve a paginated list of disbursements with optional filtering.

Endpoint

GET /api/v1/disbursements

Query Parameters

Pagination:

limit (number, default: 100, max: 250) - Maximum number of disbursements to return
offset (number, default: 0) - Number of disbursements to skip for pagination

Filtering:

fundId (string) - Filter by fund ID
grantId (string) - Filter by grant application ID
status (string) - Filter by disbursement status:
- PENDING - Payment pending
- SCHEDULED - Payment scheduled
- PAID - Payment completed
- CANCELLED - Payment cancelled
- FAILED - Payment failed

Response

{
  "disbursements": [
    {
      "disbursementId": "disb_abc123",
      "managedBy": "org123",
      "grantId": "app_xyz789",
      "fundId": "fund_456",
      "identifier": "CDF-2025-042-001",
      "amount": 11000,
      "currency": "GBP",
      "status": "PAID",
      "dates": {
        "scheduled": "2025-02-01T00:00:00.000Z",
        "processed": "2025-02-01T10:30:00.000Z"
      },
      "payment": {
        "method": "BACS",
        "reference": "CDF2025042001"
      },
      "bankAccount": {
        "accountName": "Community Youth Trust",
        "accountNumber": "****5678",
        "sortCode": "****00",
        "bankName": "Barclays Bank"
      },
      "description": "First instalment - 50% of grant",
      "notes": "Payment processed successfully",
      "modifiedBy": "user_001",
      "dataSource": "manual",
      "updated": "2025-02-01T10:30:00.000Z"
    }
  ],
  "offset": 0,
  "limit": 100,
  "total": 89
}

Example Requests

List all disbursements:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements" \
  -H "x-api-key: sk_your_api_key"

Filter by fund:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?fundId=fund_456" \
  -H "x-api-key: sk_your_api_key"

Filter by grant:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?grantId=app_xyz789" \
  -H "x-api-key: sk_your_api_key"

Filter by status:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?status=PAID" \
  -H "x-api-key: sk_your_api_key"

Combine filters:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?fundId=fund_456&status=PENDING" \
  -H "x-api-key: sk_your_api_key"

Get Single Disbursement

Retrieve a specific disbursement by ID.

Endpoint

GET /api/v1/disbursements/:disbursementId

Path Parameters

disbursementId (string, required) - The unique identifier of the disbursement

Response

{
  "disbursement": {
    "disbursementId": "disb_abc123",
    "managedBy": "org123",
    "grantId": "app_xyz789",
    "fundId": "fund_456",
    "identifier": "CDF-2025-042-001",
    "amount": 11000,
    "currency": "GBP",
    "status": "PAID",
    "dates": {
      "scheduled": "2025-02-01T00:00:00.000Z",
      "processed": "2025-02-01T10:30:00.000Z"
    },
    "payment": {
      "method": "BACS",
      "reference": "CDF2025042001"
    },
    "bankAccount": {
      "accountName": "Community Youth Trust",
      "accountNumber": "****5678",
      "sortCode": "****00",
      "bankName": "Barclays Bank"
    },
    "description": "First instalment - 50% of grant",
    "notes": "Payment processed successfully",
    "modifiedBy": "user_001",
    "dataSource": "manual",
    "updated": "2025-02-01T10:30:00.000Z"
  }
}

Example Request

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements/disb_abc123" \
  -H "x-api-key: sk_your_api_key"

Response Fields

Disbursement Object

Field	Type	Description
`disbursementId`	string	Unique identifier for the disbursement
`managedBy`	string	Organisation ID managing this disbursement
`grantId`	string	Associated grant application ID
`fundId`	string	Associated fund ID
`identifier`	string	Human-readable payment reference
`amount`	number	Payment amount
`currency`	string	Currency code (e.g., GBP)
`status`	string	Payment status
`dates`	object	Payment dates
`payment`	object	Payment method details
`bankAccount`	object	Bank account details (redacted)
`description`	string	Payment description
`notes`	string	Additional notes
`modifiedBy`	string	User ID who last modified
`dataSource`	string	Data source (manual, import, etc.)
`updated`	string	Last update timestamp (ISO 8601)

Dates Object

Field	Type	Description
`scheduled`	string	Scheduled payment date
`processed`	string	Actual processing date

Payment Object

Field	Type	Description
`method`	string	Payment method (BACS, CHAPS, etc.)
`reference`	string	Payment reference number

Bank Account Object

Field	Type	Description
`accountName`	string	Account holder name
`accountNumber`	string	Account number (redacted: ****XXXX)
`sortCode`	string	Sort code (redacted: ****XX)
`bankName`	string	Bank name

Disbursement Status Values

Status	Description
`PENDING`	Payment is pending approval or processing
`SCHEDULED`	Payment has been scheduled
`PAID`	Payment has been successfully processed
`CANCELLED`	Payment was cancelled
`FAILED`	Payment processing failed

Use Cases

Track Grant Payments

To see all payments for a specific grant:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?grantId=app_xyz789" \
  -H "x-api-key: sk_your_api_key"

Monitor Pending Payments

To view all pending disbursements that need processing:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?status=PENDING" \
  -H "x-api-key: sk_your_api_key"

Fund-Level Reporting

To get all disbursements for a specific fund for reporting:

curl -X GET "https://app.plinth.org.uk/api/v1/disbursements?fundId=fund_456&limit=250" \
  -H "x-api-key: sk_your_api_key"

Error Responses

Status	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Disbursement not found
500	Internal Server Error