> ## 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. # Manually trigger an orchestration > Force an immediate batch of all currently-`PENDING` deposits for the address, regardless of the configured mode. Useful for `SCHEDULED` addresses that you want to drain ahead of schedule, for `THRESHOLD` addresses that haven't crossed yet, or simply for operational backfill. **Idempotent.** If no PENDING deposits exist (or the address was deactivated between the read and the row lock), returns 200 with `triggered: false` and a `reason`. For `SCHEDULED` addresses, manual trigger does NOT advance `nextRunAt` — the scheduled tick still fires at its appointed time (it'll find zero PENDING deposits and no-op). The endpoint serializes against concurrent THRESHOLD webhooks and the SCHEDULED job via a `FOR UPDATE` row lock, so at most one batch is ever produced for a given set of PENDING deposits. ## OpenAPI ````yaml https://production.hifi.com/api/v2/openapi.json post /v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/orchestrate openapi: 3.0.0 info: title: Hifi API version: 2.0.0 description: API documentation for Hifi servers: - url: https://production.hifibridge.com description: Production server - url: https://sandbox.hifibridge.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Kyc description: Kyc endpoints - name: Wallet description: Wallet endpoints - name: Account description: Account endpoints - name: External Account description: External Account endpoints for managing beneficiary bank accounts - name: Fiat Account description: Fiat Account endpoints - name: Virtual Account description: Virtual Account endpoints - name: Onramp description: Onramp endpoints - name: Offramp description: Offramp endpoints - name: Orchestration Address description: >- Orchestration Address endpoints — persistent on-chain wallets that automatically off-ramp incoming stablecoin deposits to a USD bank account - name: Crypto Transfer description: Crypto Transfer endpoints - name: Cross-Chain Bridge description: Cross-Chain Bridge endpoints - name: Token Swap description: Token Swap endpoints - name: Canton Offers description: Canton Offers endpoints - name: Transfer Rules description: Transfer approval rules and configuration - name: Transfer Approvals description: Transfer approval workflow and admin actions - name: File description: File endpoints - name: Reporting description: Reporting and metrics endpoints paths: /v2/users/{userId}/orchestration-addresses/{orchestrationAddressId}/orchestrate: post: tags: - Orchestration Address summary: Manually trigger an orchestration description: | Force an immediate batch of all currently-`PENDING` deposits for the address, regardless of the configured mode. Useful for `SCHEDULED` addresses that you want to drain ahead of schedule, for `THRESHOLD` addresses that haven't crossed yet, or simply for operational backfill. **Idempotent.** If no PENDING deposits exist (or the address was deactivated between the read and the row lock), returns 200 with `triggered: false` and a `reason`. For `SCHEDULED` addresses, manual trigger does NOT advance `nextRunAt` — the scheduled tick still fires at its appointed time (it'll find zero PENDING deposits and no-op). The endpoint serializes against concurrent THRESHOLD webhooks and the SCHEDULED job via a `FOR UPDATE` row lock, so at most one batch is ever produced for a given set of PENDING deposits. 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 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 - validation error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object description: Field-specific validation errors UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Resource not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string 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' Unauthorized: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message InternalServerError: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed 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 ````