Skip to main content
POST
Withdraw one of your asks
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Cancels one of your open asks with cancelReason: "withdrawn". The people it asked are told it no longer needs them. Name it by exactly one of humanTaskId and clientReference. The optional reason (up to 500 characters) is kept on the ask itself and returned to you alone as withdrawReason by Read one of your asks. It is never shown to the people asked and never written to any audit record. A repeat withdraw keeps the first reason. The answer is { humanTaskId, clientReference, outcome, state }. outcome is withdrawn, or already_closed when the ask had already completed or was canceled; state is the ask’s state after the call. A repeat is therefore safe, and a replay names the task. A withdraw emits human_task.canceled to your app’s subscription. Withdrawing does not free a place under the 24-hour caps on Ask a person: they count every ask you created, open or closed.

Answers

With an Idempotency-Key, a retry within 24 hours returns the recorded response only to the same requester while the ask still names them. A companion key records no Idempotency-Key; its repeat answers already_closed.

Example

The answer is { "data": { "humanTaskId": "…", "clientReference": "vendor-4711", "outcome": "withdrawn", "state": "canceled" }, "meta": { "requestId": "…" } }.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Body

application/json

Withdraw one of your own open asks, named by exactly one of humanTaskId and clientReference (otherwise 400 "Name exactly one of humanTaskId and clientReference").

humanTaskId
string

The task's id, as requestHumanTask returned it.

Minimum string length: 1
clientReference
string

Your own id for this ask: 1 to 128 of A-Z a-z 0-9 . _ -. A repeat of a reference you used before returns that ask (created: false), even a closed one; a reference is never reused.

Pattern: ^[A-Za-z0-9._-]{1,128}$
reason
string

Why; kept on the ask itself and returned to you alone as withdrawReason by getRequestedHumanTask, never shown to the people asked.

Maximum string length: 500

Response

The ask was withdrawn or was already closed

data
object
required

withdrawn when this request canceled the ask; already_closed when it had already completed or been canceled, with its state.

meta
object
required