get_status for a task, with a message to the operator

This is get_status with the optional message, as a POST so that the text is in the body, not in the URL (which servers log). Without a message (empty body, or {"message": null}) it is a plain status call, like the GET. With a message it is written to the thread and e-mailed to the operator, and the answer is the same as the GET's, including your message (from: agent) and message_sent: true. Read the operator's message first, then reply: while the operator has written something you have not read yet, nothing is stored or e-mailed; the answer is the GET's, with that message in messages, message_sent: false and a next_action that says so, and you send your answer with the next call (HTTP 200 either way, so check message_sent). Plain text, 1-2000 characters, never interpreted as HTML; an empty or longer message is a 400. Limits: 10 messages per hour per quote (its quote_id and task_id share it) and 30 per hour per client address (429). The same text again within 10 minutes, while it is still the newest message of the thread, is not stored or e-mailed a second time (the answer then has duplicate_ignored: true). It needs the same access_token as the GET; without one, or with another quote's, nothing is stored or sent (401).

post/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

Request body

messagestring nullable

Your reply to the operator: plain text, 1-2000 characters, never HTML. Null or absent: a plain status call.

Response

The same answer as the GET, now including your message; if the operator had written something you had not read, message_sent is false, nothing was stored and the answer shows that message

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.