Search for disbursements

You might need to access a specific disbursement, but you do not know the disbursement ID. You can use the following endpoint to search for disbursements:

  • POST /billing/v1/search/disbursements

In the request body, you can specify search parameters. The response contains an array of disbursements that match all the search parameters.

String and typekey search parameters

Some search parameters are strings, such as accountNumber. For all string search parameter fields, BillingCenter supports partial string matching. The search value must match the beginning of the string.

For example, the following matches a disbursement with a payee named "Michael Adams."

{
    "data": {
        "attributes": {
            "payee": "mich"
        }
    }
}

The following does not match, because the beginning of the string is not included:

{
  "data": {
    "attributes": {
      "payeeName": "adams"
    }
  }
}

You can also search using typekey references. Typekey references do not match on partial strings. However, they are case-insensitive.

For example, you can use the following request payload to search for disbursements with a specific status:

{
  "data": {
    "attributes": {
      "status": {
        "code": "approved"
      }
    }
  }
}

Searching with no search parameters

You can search without including any criteria using an empty data wrapper.

{
  "data": {
    "attributes": {
    }
  }
}

If there are more than 300 disbursements to be returned, BillingCenter throws an error.

Response details

BillingCenter returns a list of disbursements. The returned disbursements do not necessarily contain the information sent as search parameters.

The following is an example of a request that returns disbursements:

Command

POST /billing/v1/search/disbursements

Request body

{
  "data": {
    "attributes": {
      "status": {
        "code": "approved"
      }
    }
  }
}

Response

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "account": {
                    "displayName": "Torpedo-144-Snail",
                    "id": "bc:SQbi2og-5byU39QFGF9ra",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:SQbi2og-5byU39QFGF9ra"
                },
                "address": "111 Address Lane Suite 1, City, CO 12345",
                "amount": {
                    "amount": "55.00",
                    "currency": "usd"
                },
                "disbursementNumber": "1000000002",
                "dueDate": "2026-06-04",
                "id": "bc:SVPPFkJdCY9QWcftMZATR",
                "mailTo": "test test",
                "payTo": "test test",
                "paymentInstrument": {
                    "displayName": "Check",
                    "id": "bc:StTTnY_7fQx6ko0PXy7pY",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:StTTnY_7fQx6ko0PXy7pY"
                },
                "reason": {
                    "code": "Cancellation",
                    "name": "Cancellation"
                },
                "status": {
                    "code": "Approved",
                    "name": "Approved"
                },
                "unappliedFund": {
                    "displayName": "Default",
                    "id": "bc:SGYOKZ4mLdio-jpPo__IL",
                    "type": "UnappliedFund",
                    "uri": "/billing/v1/accounts/bc:SQbi2og-5byU39QFGF9ra/unapplied-funds/bc:SGYOKZ4mLdio-jpPo__IL"
                }
            },
            "checksum": "0",
            "links": {
                "approve": {
                    "href": "/billing/v1/disbursements/bc:SVPPFkJdCY9QWcftMZATR/approve",
                    "methods": [
                        "post"
                    ]
                },
                "reject": {
                    "href": "/billing/v1/disbursements/bc:SVPPFkJdCY9QWcftMZATR/reject",
                    "methods": [
                        "post"
                    ]
                },
                "reject-and-hold": {
                    "href": "/billing/v1/disbursements/bc:SVPPFkJdCY9QWcftMZATR/reject-and-hold",
                    "methods": [
                        "post"
                    ]
                },
                "self": {
                    "href": "/billing/v1/disbursements/bc:SVPPFkJdCY9QWcftMZATR",
                    "methods": [
                        "get",
                        "patch"
                    ]
                },
                "void": {
                    "href": "/billing/v1/disbursements/bc:SVPPFkJdCY9QWcftMZATR/void",
                    "methods": [
                        "post"
                    ]
                }
            }
        },
        {
            "attributes": {
                "account": {
                    "displayName": "Torpedo-144-Snail",
                    "id": "bc:SQbi2og-5byU39QFGF9ra",
                    "type": "Account",
                    "uri": "/billing/v1/accounts/bc:SQbi2og-5byU39QFGF9ra"
                },
                "address": "111 Address Lane Suite 1, City, CO 12345",
                "amount": {
                    "amount": "35.00",
                    "currency": "usd"
                },
                "disbursementNumber": "1000000003",
                "dueDate": "2026-06-04",
                "id": "bc:SJT7FhbJOmddqGyz2yPH2",
                "mailTo": "Michael Douglass",
                "payTo": "Michael Douglass",
                "paymentInstrument": {
                    "displayName": "Check",
                    "id": "bc:StTTnY_7fQx6ko0PXy7pY",
                    "type": "UniversalPaymentInstrument",
                    "uri": "/billing/v1/universal-payment-instruments/bc:StTTnY_7fQx6ko0PXy7pY"
                },
                "reason": {
                    "code": "Other",
                    "name": "Other"
                },
                "status": {
                    "code": "Approved",
                    "name": "Approved"
                },
                "unappliedFund": {
                    "displayName": "Default",
                    "id": "bc:SGYOKZ4mLdio-jpPo__IL",
                    "type": "UnappliedFund",
                    "uri": "/billing/v1/accounts/bc:SQbi2og-5byU39QFGF9ra/unapplied-funds/bc:SGYOKZ4mLdio-jpPo__IL"
                }
            },
            "checksum": "0",
            "links": {
                "approve": {
                    "href": "/billing/v1/disbursements/bc:SJT7FhbJOmddqGyz2yPH2/approve",
                    "methods": [
                        "post"
                    ]
                },
                "reject": {
                    "href": "/billing/v1/disbursements/bc:SJT7FhbJOmddqGyz2yPH2/reject",
                    "methods": [
                        "post"
                    ]
                },
                "reject-and-hold": {
                    "href": "/billing/v1/disbursements/bc:SJT7FhbJOmddqGyz2yPH2/reject-and-hold",
                    "methods": [
                        "post"
                    ]
                },
                "self": {
                    "href": "/billing/v1/disbursements/bc:SJT7FhbJOmddqGyz2yPH2",
                    "methods": [
                        "get",
                        "patch"
                    ]
                },
                "void": {
                    "href": "/billing/v1/disbursements/bc:SJT7FhbJOmddqGyz2yPH2/void",
                    "methods": [
                        "post"
                    ]
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/billing/v1/search/disbursements",
            "methods": [
                "post"
            ]
        },
        "self": {
            "href": "/billing/v1/search/disbursements",
            "methods": [
                "post"
            ]
        }
    }
}