---
title: "List client allocations and deallocations"
method: GET
path: "/api/network/v1/enterprises/{enterpriseId}/clients/allocations"
tags: ["Client Allocations & Deallocations"]
---

# List client allocations and deallocations

`GET /api/network/v1/enterprises/{enterpriseId}/clients/allocations`

This API call allows clients to get a list of allocations and deallocations for any connected network account.
or "deallocation" to view deallocations.

Error scenarios:
- 400: Invalid Request Error
- Occurs when the request parameters are invalid or malformed.
- Examples: Empty string provided for enterpriseId, invalid UUID format for allocationId.
invalid date format for createdOnOrAfter/createdBefore, invalid pagination parameters.

- 401: Authentication Error
- Occurs when the request is not authorized.
- Examples: Caller is not a member of the enterprise..

- 403: Permission Denied Error
- Occurs when the authenticated partner doesn't have access to the requested allocation.
- Examples: Enterprise does not have OES license.

- 404: Not Found Error
- Occurs when the specified enterprise cannot be found.
- Examples: Enterprise ID doesn't exist or doesn't belong to the client.

- 500: Internal Server Error
- Occurs when there's an unexpected server error processing the request.
- Examples: Database connection issues, error retrieving allocations data,
error transforming allocation data for response.

**Requires access token scope:** `settlement_network_read`

## Path parameters

- `enterpriseId` string, required

## Query parameters

- `allocationIds` string[]
- `types` string[]
- `statuses` string[]
- `currencies` string[]
- `connectionIds` string[]
- `partnerIds` string[]
- `createdOnOrAfter` string, date-time
- `createdBefore` string, date-time
- `pageNumber` string, integer
- `pageSize` string
- `sortField` 'id' | 'updatedAt' | 'quantity' | 'currency'
- `sortDirection` 'ASC' | 'DESC'

## Response `200`

OK

- V1AllocationsGetPayload
  - `allocations` object[], required
    - `id` string, required — The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
    - `amount` union, required
      - PositiveCurrencyAmount
        - `currency` string, required
        - `quantity` string, required
      - PositiveBigNumberCurrencyAmount
        - `currency` string, required
        - `quantity` string, required
    - `connectionId` string, required — The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
    - `clientExternalId` string, required — External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
    - `partnerExternalId` string — External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
    - `initiatedBy` string, required — The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
    - `notes` string — Optional notes provided by the client when creating the allocation/deallocation. Can contain additional context or information about the purpose of the allocation.
    - `createdAt` string, date-time, required — The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
    - `updatedAt` string, date-time, required — The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
    - `retriable` boolean, required — Indicates whether or not the allocation/deallocation is retriable. When true, clients may retry the operation if it did not complete successfully. Retry can be performed by re-sending the same allocation request that was originally sent.
    - `evaluationId` string — The unique identifier of the policy evaluation for this allocation/deallocation. Present when policy evaluation was performed as part of the allocation flow.
    - `pendingApprovalId` string — The unique identifier of the pending approval for this allocation/deallocation. Present when policy evaluation resulted in a PENDING status requiring manual approval.
    - `policyResult` 'approved' | 'rejected' — The result of the policy evaluation for this allocation/deallocation. - 'approved': Policy evaluation passed and the operation was allowed - 'rejected': Policy evaluation failed and the operation was denied Not present if no policy evaluation was performed or if evaluation is still pending.
    - `reason` string, nullable, required — The reason that the allocation/deallocation is not cleared. Provides a descriptive explanation for why the allocation is in the reserved state. Will not be defined if the allocation is cleared.
    - `status` 'cleared' | 'released' | 'reserved', required
    - `type` 'allocation' | 'deallocation', required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/bitgo/apis/bitgo-api.md) · [All operations](https://skmtc.net/bitgo/apis/bitgo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitgo/bitgo-api/revisions/e445c15e5bee/schema)