> ## Documentation Index
> Fetch the complete documentation index at: https://docs.confidolegal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Disbursements

export const supportEmail = 'support@confidolegal.com';

Securely send money to Clients with Disbursements. Here's the high-level overview.

### Prerequisites

Firms must be **`ACTIVE`** for payments in general, but **disbursements are gated separately**: the API returns an error if disbursements are not enabled for that Firm (`disbursements are not allowed for this firm`). Enabling disbursements is an additional setup step in onboarding, not something that automatically turns on the moment `firm.status` becomes `ACTIVE`. If creation fails, the Firm needs disbursements enabled in Confido (completed by Confido operations)—contact **{supportEmail}** if you are unsure of the Firm’s status.

<Steps>
  <Step title="Create a Disbursement">
    Create a disbursement link and specify the email or phone number that can
    access the link.
  </Step>

  <Step title="Distribute the link">
    Get the link to the Client. The Client can then access the link to accept
    the disbursement.
  </Step>

  <Step title="Client accepts">
    Client unlocks link by verifying ownership of email or phone. Client enters
    account information.
  </Step>

  <Step title="Funds sent">
    Funds are sent from the Firm's account to the Client's account.
  </Step>
</Steps>

## The Disbursement Object

For complete details of all available fields, see the Disbursement Object in our [GraphQL Playground](https://api.sandbox.gravity-legal.com/).

```typescript theme={"system"}
type Disbursement = {
  allowedMethods: DisbursementMethod[];
  amount: Int;
  authorizedIdentities: Identity[];
  client?: Client;
  fundingAccount: BankAccount;
  id: string;
  matter?: Matter;
  metadata?: JSON;
  status: DisbursementStatus;
  url?: string;
};
```

**allowedMethods: DisbursementMethod\[]**

A list of methods that the client is allowed to use when accepting the disbursement from the payout page. The allowed methods will fall back to the Firm’s defaults unless set specifically on the disbursement.

`DisbursementMethod.ACH` Slow ACH transaction via Plaid or manually entering account number and routing number.

`DisbursementMethod.PUSH_TO_CARD` Instant transaction to a Visa or Mastercard debit card.

`DisbursementMethod.REQUEST_CHECK` Firm would be informed that the client wants a check sent to them.

**amount: Int**

The amount to disburse to the client. If the client chooses an instant method from the payout page, the net disbursement to them will be **amount - instant\_fee**.

**authorizedIdentities: Identity\[]**

The identities that are authorized to accept the disbursement. Any of the authorized identities can be used on the payout page to access the disbursement. After the client authenticates on the payout page, we verify that the email or phone they used matches one of the authorizedIdentities.

**client**

The client that the disbursement is associated with. This is optional.

**fundingAccount**

The bank account the disbursement will come out of.

**id**

Unique identifier for the disbursement. UUID format.

**matter**

The matter the disbursement is associated with. This is optional.

**metadata**

A flexible JSON object that allows you to store and transfer arbitrary data. When a transaction is created for the disbursement, this metadata object is copied and added to the transaction. This lets you associate transactions with external entities and pass through custom data as needed.

**status**

`DRAFT` The disbursement has been created but has not been approved. At this stage there is no `url` and no funds can be transferred.

`APPROVED` The disbursement has been approved and is ready for the client to accept. At this status, the disbursement will have a unique `url`.

`FUNDS_IN_TRANSIT` The client has visited the payout page, entered their method details, and accepted the funds but the funds have not reached the client’s account yet.

`DELIVERED` The client has received the funds in their account.

**transactions: Transaction\[]**

When the client accepts the disbursement a Transaction is created. Most disbursements will only have one transaction in this list.

A disbursement may have two transactions in scenarios such as ACH returns. For example, if an ACH payout is initiated but the receiving bank rejects it, the transaction is returned. In this case, the disbursement would include two transactions: one for the initial payout and one for the ACH return.

**url**

The URL where the payout page is hosted, allowing the client to accept their funds. This field is nullable and will only be populated once the disbursement reaches the APPROVED status. The URL will change whenever the disbursement is updated, so it's important to provide the client with the new URL after any update, as the previous one will no longer be valid.

## Create a Disbursement

Use the `disbursementCreate` mutation to create a new disbursement.

**Input**

```typescript theme={"system"}
type DisbursementCreateInput = {
  allowedMethods?: DisbursementMethod[];
  amount: number; // in cents
  authorizedIdentities: AuthorizedIdentity[];
  clientId?: string;
  clientUpsert?: ClientCreateInput;
  fundingAccountId: string;
  matterId?: string;
  matterUpsert?: MatterCreateInput;
  metadata?: JSON;
  status?: DRAFT | APPROVED;
};
```

**allowedMethods**

This lets you specify certain allowed methods for this disbursement only. If left blank, the disbursement will fall back to the Firm’s default methods.

**clientUpsert**

Links an existing client or creates and links a new one to the disbursement. This is useful for checking if the client is already in the system and linking them, or creating a new record if needed. This should not be used with `clientId`.

**metadata**

A flexible JSON object that allows you to store and transfer arbitrary data. When a transaction is created for the disbursement, this metadata object is copied and saved on the transaction. This lets you associate transactions with external entities and pass through custom data as needed. For example, you could create a disbursement with `metadata = { mypartner_settlementId: 'my_settlement_id' }`. Then, when the client accepts their funds, the corresponding transaction object would have this same metadata.

**status**

You can pass `status=APPROVED` into the create call if you want to skip the approval process. Otherwise, the disbursement will be created in `DRAFT` and will need to be approved.

## Update a Disbursement

Use the `disbursementUpdate` mutation to update a disbursement. Disbursements can only be updated in `DRAFT` and `APPROVED` status.

**Input**

```
type DisbursementUpdateInput = {
  allowedMethods?: DisbursementMethod[];
  amount: number; // in cents
  authorizedIdentities: AuthorizedIdentity[];
  clientId?: string;
  clientUpsert?: CreateClientInput;
  fundingAccountId: string;
  matterId?: string;
  matterUpsert?: CreateMatterInput;
}

```

## Approve a Disbursement

Use the `disbursementApprove` mutation to approve a disbursement. If successful, the disbursement will now have a unique URL.

## Unapprove a Disbursement

You can use the `disbursementUnapprove` mutation to send the disbursement back to `DRAFT` and invalidate the previous URL. When the disbursement is approved again, you will get a new URL.

## Delete a Disbursement

Use the `disbursementDelete` mutation to delete a Disbursement. Disbursements can only be deleted in `DRAFT` and `APPROVED` status.

## Get a Disbursement

Fetch a single disbursement with `disbursementGet` query.

## List Disbursements

List disbursements that match the given query params with `disbursementList`.

For a full list of available query parameters, see our [GraphQL Playground](https://api.sandbox.gravity-legal.com/).

## Webhooks

Get a webhook when a Disbursement is updated with the `disbursement.updated` webhook. Also get webhooks when a Disbursement is accepted via the `transaction.created` webhook. See the [webhooks docs](https://docs.confidolegal.com/docs/webhooks/configure)