Ctrl+K

Get client allocation or deallocation

get/api/network/v1/enterprises/{enterpriseId}/clients/allocations/{allocationId}

Returns an allocation or deallocation. For use only by OES clients.

Error scenarios:

  • 400: Invalid Request Error

  • Occurs when the request parameters are invalid or incomplete.

  • Examples: Invalid UUID format for allocationId, invalid enterpriseId format.

  • 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 requested allocation does not exist for this client

  • Examples: Allocation with specified ID doesn't exist, allocation exists but belongs to different client

  • 500: Internal Server Error

  • Occurs when there's an unexpected error processing the request

  • Examples: Database connection failure, currency mapping error, error transforming allocation data for response

Path Parameters

  • allocationIdstringRequired
    The unique identifier of the allocation to retrieve. This is a UUID that uniquely identifies the allocation record.
  • enterpriseIdstringRequired
    The enterprise identifier of the client. This identifies the client enterprise that owns the allocation.
    Min length: >= 1 characters

200 Response

allocation object required
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.
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