> ## 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.

# Create a Disbursement

The `disbursementCreate` mutation allows you to create a single disbursement. You can create a disbursement in either `DRAFT` or `APPROVED` status. The disbursement will only receive a `url` once it reaches `APPROVED` status.

## Mutation

```graphql theme={"system"}
mutation DisbursementCreate($input: DisbursementCreateInput!) {
  disbursementCreate(input: $input) {
    id
    amount
    status
    url
    authorizedIdentities {
      type
      value
    }
    client {
      id
      clientName
    }
    matter {
      id
      name
    }
    fundingAccount {
      id
    }
  }
}
```

## Input Fields

### Required Fields

**amount** (Int)

The amount in cents to disburse to the client. Must be greater than 0 and less than or equal to 100000000 (i.e., greater than \$0.00 and less than or equal to \$1,000,000.00)

**authorizedIdentities** (Array of DisbursementIdentityInput)

The identities (email or phone) that are authorized to access and accept the disbursement. At least one identity is required. Each identity includes:

* **type** (DisbursementIdentityType): Either `EMAIL` or `PHONE`
* **value** (String): The email address or phone number
* **source** (DisbursementIdentitySource, optional): For informational purposes only. Used by Confido UI when identity comes from a known source, like a client.

**fundingAccountId** (String)

The ID of the bank account to pull the funds from for the disbursement.

### Optional Fields

**id** (String, nullable)

Optional client-supplied ID for the new disbursement. **Must be a valid UUID v4 string** if provided. If null, the ID will be generated automatically.

**status** (DisbursementStatus, nullable)

The initial status of the disbursement. Defaults to `DRAFT` if not specified.

* **DRAFT**: The disbursement is created but not yet approved. No `url` will be available. The disbursement must be approved before it can be accessed by the client.
* **APPROVED**: The disbursement is immediately approved and will have a `url` available. Only `FIRM_ADMIN` users can create disbursements in `APPROVED` status.

**allowedMethods** (Array of DisbursementMethod, nullable)

Specifies which payment methods are allowed for this disbursement. If left blank, the disbursement will use the firm's default allowed methods. Available methods:

* `ACH`: Slow ACH transaction via Plaid or manual entry of account and routing number
* `PUSH_TO_CARD`: Instant transaction to a Visa or Mastercard debit card
* `REQUEST_CHECK`: Firm will be informed that the client wants a check sent to them

**clientId** (String, nullable)

The ID of an existing client to associate with the disbursement. Should not be used together with `clientUpsert`.

**clientUpsert** (ClientUpsertInput, nullable)

Creates a new client or links an existing one to the disbursement based on the provided ID. This is useful when you want to automatically create a client if they don't exist, or link an existing client. Should not be used together with `clientId`. Fields:

* **id** (String): A UUID v4. This ID is first used to lookup the client. If no client is found, it will be used as the ID for a new client.
* **clientName** (String): The name of the client
* **email** (String, nullable): Client's email address
* **firstName** (String, nullable): Client's first name
* **lastName** (String, nullable): Client's last name
* **phone** (String, nullable): Client's phone number

**matterId** (String, nullable)

The ID of an existing matter to associate with the disbursement. Should not be used together with `matterUpsert`.

**matterUpsert** (MatterUpsertInput, nullable)

Creates a new matter or links an existing one to the disbursement based on the provided ID. This is useful when you want to automatically create a matter if it doesn't exist, or link an existing matter. Should not be used together with `matterId`. Fields:

* **id** (String): A UUID v4. This ID is first used to lookup the matter. If no matter is found, it will be used as the ID for a new matter.
* **clientId** (String): The ID of the client this matter belongs to
* **name** (String): The name of the matter

**enhancedSecurity** (Boolean, nullable)

If `true`, enables enhanced security for the disbursement. If `null`, uses the firm's default enhanced security settings.

**expiryDays** (Int, nullable)

The number of days until the disbursement expires. If `null`, uses the firm's default expiry days setting.

**metadata** (JSON, nullable)

A flexible JSON object that allows you to store 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:

```json theme={"system"}
{
  "metadata": {
    "mypartner_settlementId": "my_settlement_id",
    "externalReference": "REF123456"
  }
}
```

When the client accepts their funds, the corresponding transaction object will have this same metadata.

## URL Generation

The `url` field is only populated when the disbursement reaches `APPROVED` status. This means:

* Disbursements created in `DRAFT` status will have `url: null`
* Disbursements created in `APPROVED` status will have a `url` immediately
* Disbursements approved after creation (using `disbursementApprove`) will receive a `url` at that time
* The `url` will change whenever the disbursement is updated, so it's important to provide clients with the updated URL after any changes

## Example Request

```json theme={"system"}
{
  "input": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 25000,
    "authorizedIdentities": [
      {
        "type": "EMAIL",
        "value": "john.doe@example.com"
      },
      {
        "type": "PHONE",
        "value": "+15551234567"
      }
    ],
    "fundingAccountId": "bank_account_123",
    "clientUpsert": {
      "id": "client-uuid-here",
      "clientName": "John Doe",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "matterUpsert": {
      "id": "matter-uuid-here",
      "clientId": "client-uuid-here",
      "name": "Settlement Case 2024"
    },
    "allowedMethods": ["ACH", "PUSH_TO_CARD"],
    "enhancedSecurity": true,
    "expiryDays": 30,
    "metadata": {
      "settlementId": "SETT-2024-001"
    },
    "status": "APPROVED"
  }
}
```

## Example Response

```json theme={"system"}
{
  "data": {
    "disbursementCreate": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 25000,
      "status": "APPROVED",
      "url": "https://app.confidolegal.com/d/abc123xyz",
      "authorizedIdentities": [
        {
          "type": "EMAIL",
          "value": "john.doe@example.com"
        },
        {
          "type": "PHONE",
          "value": "+15551234567"
        }
      ],
      "client": {
        "id": "client-uuid-here",
        "clientName": "John Doe"
      },
      "matter": {
        "id": "matter-uuid-here",
        "name": "Settlement Case 2024"
      },
      "fundingAccount": {
        "id": "bank_account_123"
      }
    }
  }
}
```

## Authorization

* **FIRM\_ADMIN** users can create disbursements in either `DRAFT` or `APPROVED` status
* **FIRM\_USER** users can only create disbursements in `DRAFT` status and will receive an error if they attempt to create an `APPROVED` disbursement

## Related Operations

* To approve a draft disbursement, use the [`disbursementApprove`](/docs/send-money/disbursements) mutation
* To update a disbursement, use the [`disbursementUpdate`](/docs/send-money/disbursements) mutation
* To create multiple disbursements at once, see [Bulk Create Disbursements](/docs/send-money/bulk-disbursements)