Ctrl+K

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.

Path Parameters

  • enterpriseIdstringRequired
    Min length: >= 1 characters

Query Parameters

  • allocationIdsarray[string]
    Optional array of allocationIds. If provided will only return allocations/deallocations with those ids. allocationIds are unique identifiers (UUIDs) for allocations. UUIDs must be submitted as a comma-separated string.
  • typesarray[string]
    Optional array of types. If provided will only return allocations/deallocations with those types. Types must be submitted as a comma-separated string. allocation = records for allocations to connections. deallocation = records for deallocations from connections.
    Enum: allocation deallocation
  • statusesarray[string]
    Optional array of statuses. If provided will only return allocations/deallocations with those statuses. Statuses must be submitted as a comma-separated string. cleared = records for allocations that have been cleared. released = records for allocations that have been released. reserved = records for allocations that are still reserved.
    Enum: cleared released reserved
  • currenciesarray[string]
    Optional array of currencies. If provided will only return allocations/deallocations with those currencies. Currencies must be submitted as a comma-separated string.
  • connectionIdsarray[string]
    Optional array of connectionIds. If provided will only return allocations/deallocations for those connectionIds. ConnectionIds must be submitted as a comma-separated string.
  • partnerIdsarray[string]
    Optional array of partnerIds. If provided will only return allocations/deallocations for those partnerIds. PartnerIds must be submitted as a comma-separated string.
  • createdOnOrAfterstring<date-time>
    Optional date start range filter for createdAt (ISO Date). If provided will only return allocations/deallocations created on or after this date. This date should be in ISO 8601 format (e.g., 2023-01-01T00:00:00Z).
  • createdBeforestring<date-time>
    Optional date end range filter for createdAt (ISO Date). If provided will only return allocations/deallocations created on or before this date. This date should be in ISO 8601 format (e.g., 2023-01-01T00:00:00Z).
  • pageNumberstring<integer>
    The page number (integer) you wish to fetch. When provided, the API will skip pageSize * pageNumber records. Page numbers are zero-based, so the first page is 0. If not provided, defaults to 0.
  • pageSizestring
    The page size (integer) you wish to fetch. When provided, the API will return at most pageSize records per page. If not provided, a default page size defined by the server will be used.
  • sortFieldstring
    The field to sort results on. Possible values: - id: Sort by allocation ID. - updatedAt: Sort by the last updated timestamp. - quantity: Sort by the allocation amount quantity. - currency: Sort by the allocation currency code. Note: A finals sort is always applied on createdAt ascending and id ascending, regardless of the specified sortField. This ensures consistent ordering for items with the same primary sort value.
    Enum: id updatedAt quantity currency
  • sortDirectionstring
    The direction to sort results. Possible values: - ASC: Ascending order (lowest to highest, A to Z, oldest to newest). - DESC: Descending order (highest to lowest, Z to A, newest to oldest). If not specified, defaults to ASC (ascending).
    Enum: ASC DESC

200 Response

allocations array[object] required
Array of allocation records matching the query criteria. The array may be empty if no allocations match the query criteria.
id string required
The unique identifier of the allocation/deallocation. This is a UUID that uniquely identifies the allocation record.
amountOne ofrequired
The amount of the allocation/deallocation. Contains both the currency identifier and the quantity in base units.
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.
Min length: >= 1 characters
partnerExternalId string
External identifier of the allocation/deallocation in the partner system. May be populated when partners provide their own identifier for the allocation.
Min length: >= 1 characters
initiatedBy string required
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
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.
Min length: >= 1 characters
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.
Min length: >= 1 characters
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.
Min length: >= 1 characters
policyResult string
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.
Allowed values: approved rejected
reason
string or null
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.
Min length: >= 1 characters
status string required
Status of the allocation/deallocation. Possible values: - reserved: The amount for allocation/deallocation is reserved but operation has not completed. This is a temporary state awaiting final resolution. - cleared: Terminal state; the amount for allocation/deallocation is cleared and funds have been successfully allocated. This indicates a successful operation. - released: Terminal state; the amount for allocation/deallocation is released and funds have been returned. This indicates the operation failed, either because balance was insufficient for allocation/deallocation, or that the partner rejected the request to allocate/deallocate.
Allowed values: cleared released reserved
type string required
The type of the entity. Possible values: - allocation: Represents an allocation of funds to a connection. This moves funds from a client's BitGo account to make them available for the specified connection. - deallocation: Represents a deallocation of funds from a connection. This moves funds from a connection back to the client's BitGo account.
Allowed values: allocation deallocation

400 Response

401 Response

error string required

403 Response

error string required

404 Response

error string required

500 Response

error string required