> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # Trigger orchestration > Manually trigger settlement for an orchestration address. ## OpenAPI ````yaml https://production.hifi.com/api/v3/openapi.json post /v3/users/{userId}/orchestration-addresses/{orchestrationAddressId}/orchestrate openapi: 3.0.0 info: title: Hifi API version: 3.0.0 description: API documentation for HIFI servers: - url: https://production.hifi.com description: Production server - url: https://sandbox.hifi.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Counter Party description: Counter party endpoints - name: Crypto Transfer description: Crypto transfer and batch transfer endpoints - name: Wallet description: Wallet and wallet offer endpoints - name: External Account description: External bank account endpoints (under a counter party) - name: External Wallet description: External wallet endpoints (under a counter party) - name: External Card description: External card endpoints (under a counter party) - name: Token Swap description: Token swap endpoints - name: Bridge description: Bridge endpoints - name: Virtual Account description: Virtual account endpoints - name: Compliance description: Compliance and compliance link endpoints - name: Webhook Endpoint description: Webhook endpoint endpoints - name: File description: File upload endpoints - name: Onramp description: Onramp (fiat to crypto) endpoints - name: Offramp description: Offramp (crypto to fiat) endpoints - name: Orchestration Address description: Orchestration (liquidation) address endpoints - name: KYC Link description: Hosted and custom KYC/KYB link endpoints - name: Transfer Approval description: Transfer approval endpoints - name: Corridor description: Supported fiat/crypto transfer corridor endpoints - name: Migration description: v2-to-v3 ID mapping endpoints paths: /v3/users/{userId}/orchestration-addresses/{orchestrationAddressId}/orchestrate: post: tags: - Orchestration Address summary: Trigger orchestration description: Manually trigger settlement for an orchestration address. operationId: v3TriggerOrchestration parameters: - $ref: '#/components/parameters/UserIdPathParameter' - $ref: '#/components/parameters/OrchestrationAddressIdPathParameter' responses: '200': $ref: '#/components/responses/OrchestrationManualTriggerResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: parameters: UserIdPathParameter: name: userId in: path schema: type: string pattern: ^user_[A-Za-z0-9]+$ description: ID of the user. required: true OrchestrationAddressIdPathParameter: name: orchestrationAddressId in: path schema: type: string format: uuid required: true description: ID of the orchestration address. responses: OrchestrationManualTriggerResponse: description: | Result of `POST /orchestrate`. Either a freshly-created batch (`triggered: true`, with `batch` populated) or an idempotent no-op (`triggered: false`, with `reason` indicating why). content: application/json: schema: $ref: '#/components/schemas/OrchestrationManualTriggerObject' BadRequestResponse: description: Bad Request — the request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: VALIDATION_ERROR message: One or more fields are invalid or missing. fields: - code: invalid_value message: Must be a valid email address field: email UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFound' InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: OrchestrationManualTriggerObject: description: > Result of a manual `POST /orchestrate` call. Either a freshly-created batch (`triggered: true`) or an idempotent no-op (`triggered: false`). oneOf: - $ref: '#/components/schemas/OrchestrationManualTriggerTriggered' - $ref: '#/components/schemas/OrchestrationManualTriggerNoOp' ApiError: type: object description: >- Standard v3 error shape, returned by validation failures and business-logic errors alike. properties: type: type: string description: >- Machine-readable error type, e.g. VALIDATION_ERROR, ACTION_NOT_ALLOWED, RESOURCE_CONFLICT. example: VALIDATION_ERROR message: type: string description: Human-readable error message. example: One or more fields are invalid or missing. fields: type: array description: >- Present on field-level validation errors. One entry per problem field. items: type: object properties: code: type: string description: Error code related to the field issue. message: type: string description: Error message for the specific issue. field: type: string description: The name of the field that has an issue. Unauthorized: type: object properties: type: type: string description: Unauthorized enum example: UNAUTHORIZED message: type: string description: Unauthorized message example: Authentication required NotFound: type: object properties: type: type: string example: RESOURCE_NOT_FOUND description: The error type, e.g., RESOURCE_NOT_FOUND message: type: string description: A descriptive error message fields: type: array description: List of specific field errors items: type: object properties: code: type: string description: Error code related to the field issue message: type: string description: Error message for the specific issue field: type: string description: The name of the field that has an issue InternalServerError: type: object properties: type: type: string example: INTERNAL_SERVER_ERROR description: Internal server error enum message: type: string example: An internal server error occurred description: Internal server error message OrchestrationManualTriggerTriggered: type: object description: Response shape when the manual trigger produced a new batch. properties: triggered: type: boolean enum: - true batch: $ref: '#/components/schemas/OrchestrationBatchObject' required: - triggered - batch OrchestrationManualTriggerNoOp: type: object description: > Response shape when the manual trigger was an idempotent no-op (no PENDING deposits, or the address was deactivated under the row lock). properties: triggered: type: boolean enum: - false reason: $ref: '#/components/schemas/OrchestrationManualTriggerReasonEnum' batch: type: object nullable: true description: Always `null` in the no-op variant. example: null required: - triggered - reason - batch OrchestrationBatchObject: type: object description: >- A batch of one or more deposits rolled up into a single offramp transaction. properties: id: type: string format: uuid orchestrationAddressId: type: string format: uuid totalAmount: type: string description: Sum of the included deposits' amounts, in the source `currency`. example: '150.000000' currency: type: string enum: - usdc - usdt status: $ref: '#/components/schemas/OrchestrationBatchStatusEnum' failureReason: $ref: '#/components/schemas/OrchestrationBatchFailureReasonEnum' nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time depositIds: type: array description: IDs of all deposits included in this batch. items: type: string format: uuid offrampTransactionId: type: string format: uuid nullable: true description: | ID of the offramp transaction produced from this batch. `null` while `status=PENDING` (the worker has not yet created the offramp). Call `GET /v2/offramps/{transferId}` for full offramp details. OrchestrationManualTriggerReasonEnum: type: string enum: - no_pending_deposits - address_no_longer_active - below_offramp_minimum description: | Reason the manual trigger was a no-op (returned when `triggered=false`). * `no_pending_deposits` — the address has no `PENDING` deposits to batch. * `address_no_longer_active` — the address was deactivated between the read and the row-lock acquisition. * `below_offramp_minimum` — the summed `PENDING` deposits are below the destination rail's offramp minimum, so they are held to accumulate rather than batched. OrchestrationBatchStatusEnum: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED description: | Batch lifecycle. * `PENDING` — created; the worker has not yet picked it up. * `PROCESSING` — the linked offramp has been created and is in flight. * `COMPLETED` — the linked offramp reached `COMPLETED`. * `FAILED` — terminal failure. See `failureReason`. OrchestrationBatchFailureReasonEnum: type: string enum: - ADDRESS_NOT_ACTIVE - NOT_INITIATED - QUOTE_FAILED - CRYPTO_FAILED - FIAT_FAILED - EXPIRED - REJECTED - CANCELLED description: > Populated when `status=FAILED`. * `ADDRESS_NOT_ACTIVE` — the address was deactivated before the worker created the offramp. The only input condition that terminally fails a batch. * All other values are terminal statuses surfaced from the linked offramp transaction (e.g. lost product access → `NOT_INITIATED`, a rejected AML review → a terminal status). Internal inconsistencies (missing address, payout account lost its rail, a processor-validation bug) do **not** appear here — the worker pauses the batch (leaves it `PENDING`) and alerts ops instead of marking it `FAILED`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````