get_status for a task

Always read next_action: one or two sentences on what to do now (wait; review the quote and call create_task; pay checkout_url; call confirm_delivery), with paid, quote_valid_until and expected_ship_date. messages is the thread with the operator, newest first (from: operator or agent). Every status can change at any time: call again whenever the user asks, never answer from memory, and report only what the response says, without conclusions of your own. This REST answer is always the complete record; the MCP tools get_status, create_task and confirm_delivery answer briefly by default (get_status with full=true returns this complete record). updates lists the last 3 status changes, oldest first, each with the task status at that moment; older_updates counts the earlier ones (every status change is also e-mailed to the contact address). To answer an operator question, call get_status with message: send the same request as POST with a JSON body {"message": "..."} (plain text, 1-2000 characters); it is stored in the same thread and e-mailed to the operator, and the answer is the usual status, including your message (message_sent: true). Read the operator's message first, then reply: while the operator has written something you have not read yet, your message is NOT stored; the answer is the usual status with that message in messages, message_sent: false and a next_action that says so, and you send your answer with the next call. Send it once and only with what the user told you: the same text again within 10 minutes is ignored (duplicate_ignored: true). E-mail to tasks@handsforagents.com with the quote_id in the subject still works. test_mode true marks a test order: nothing is paid or invoiced.

get/tasks/{task_id}

Request

  • Base URL: https://api.handsforagents.com/v1
  • URL: https://api.handsforagents.com/v1/tasks/{task_id}
  • Auth: HTTP bearer

Path parameters

task_idstring required

Response

Task status, updates, evidence and shipments

task_idstring required
quote_idstring required
status'awaiting_payment' | 'paid' | 'in_progress' | 'awaiting_balance' | 'delivered' | 'confirmed' | 'disputed' | 'refunded' | 'cancelled' required

The only task statuses there are, in the usual order: awaiting_payment, paid, in_progress, delivered, confirmed (awaiting_balance with a deposit; disputed, refunded, cancelled). paid is not in_progress: the operator sets in_progress when the work starts, and delivered (not the parcel arriving) is what allows accepting with confirm_delivery.

checkout_urlstring uri

The payment link of the payment that is due now (GET /pay/{task_id}, signed; opening it redirects to a Stripe Checkout page). Present while status is awaiting_payment or awaiting_balance and the link is valid: 4 days from when the payment was created, 28 for a balance. Never present for a test order.

checkout_expires_atstring date-time

When checkout_url stops working. Present together with checkout_url.

invoice_urlstring uri
paidboolean

True when nothing is owed right now: a payment is settled (paid, card hold authorised, or simulated in a test order) and none is awaiting.

quote_valid_untilstring date
expected_ship_datestring date

The delivery or dispatch date stated in the quote.

scopestring

What was quoted, as stated in the quote.

deliverablesstring

What you receive, as stated in the quote.

next_actionstring

One or two sentences in English: what the agent or the client should do now.

duplicate_ignoredboolean

Present and true only in the answer to a POST whose message was ignored because the same text was already the newest message of the thread (sent within the last 10 minutes).

message_sentboolean

Present only in the answer to a POST with a message: true, the message was stored and e-mailed to the operator; false, it was NOT stored because the operator had written something you had not read yet (that message is in messages, now marked as read; next_action says so): send your answer again. Absent when the same text was ignored (duplicate_ignored) and in every plain status call.

test_modeboolean

Present and true only for a test order: no payment link; the operator simulates the payment after the order is placed (until then nothing is paid or simulated); no invoice, no contract.

performed_bystring

Name of the person who did the work.

older_updatesinteger

How many earlier updates are not listed. Present only when there are any; every status change is also e-mailed to the contact address.

Changes

No recorded changes to this operation across all 1 revision of this API.