Optional array of allocationIds. allocationIds are unique identifiers (UUIDs) for allocations. If UUIDs are provided, only allocations/deallocations with those UUIDs are returned. UUIDs must be submitted as a comma-separated string.
typesarray[string]
Optional array of types. If types are provided, only allocations/deallocations with those types are returned. Types must be submitted as a comma-separated string. allocation = records for allocations to connections. deallocation = records for deallocations from connections.
Enum: allocationdeallocation
statusesarray[string]
Optional array of statuses. If statuses are provided, only allocations/deallocations with those statuses are returned. 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: clearedreleasedreserved
currenciesarray[string]
Optional array of currencies. If currencies are provided, only allocations/deallocations with those currencies are returned. Currencies must be submitted as a comma-separated string.
connectionIdsarray[string]
Optional array of connectionIds. If connectionIDs are provided, only allocations/deallocations for those connectionIds are returned. ConnectionIds must be submitted as a comma-separated string.
partnerIdsarray[string]
Optional array of partnerIds. If partnerIds are provided, only allocations/deallocations for those partnerIds are returned. PartnerIds must be submitted as a comma-separated string.
clientIdsarray[string]
Optional array of clientIds. If clientIds are provided, only allocations/deallocations for those clientIds are returned. ClientIds must be submitted as a comma-separated string.
trustOrgstringRequired
Enum: BitGo TrustBitGo New YorkBitGo GermanyBitGo SwitzerlandBitGo Europe ApSFrankfurt DE TrustBitGo SingaporeBitGo KoreaBitGo Custody MENA FZEBitGo IndiaBitGo Sister Trust 1
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<integer>
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: idupdatedAtquantitycurrency
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: ASCDESC
200 Response
allocationsarray[object]required
Array of allocation records matching the query criteria. The array may be empty if no allocations match the query criteria.
idstringrequired
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.
connectionIdstringrequired
The unique identifier of the connection this allocation is for. This identifies a connection between a client and partner.
clientExternalIdstringrequired
External identifier provided by the client when creating the allocation/deallocation. Used for idempotence and correlation with client systems.
Min length: >= 1 characters
partnerExternalIdstring
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
initiatedBystringrequired
The identifier of the user that initiated the allocation/deallocation. Represents the user ID from the BitGo platform.
Min length: >= 1 characters
notesstring
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
createdAtstring<date-time>required
The date and time when the allocation/deallocation was created. Represented as an ISO 8601 formatted date string.
updatedAtstring<date-time>required
The date and time when the allocation/deallocation was last updated. Represented as an ISO 8601 formatted date string.
retriablebooleanrequired
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.
evaluationIdstring
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
pendingApprovalIdstring
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
policyResultstring
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: approvedrejected
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
statusstringrequired
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: clearedreleasedreserved
typestringrequired
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.