Accept a quote and the terms; get a Stripe Checkout URL

Returns checkout_url, the payment link of the first payment, as the quote's payment_schedule states: full price, card hold, or deposit. Give it to the user or the operator to pay by card; it is valid for 4 days from the moment the task is created (GET /pay/{task_id} redirects to a Stripe Checkout page, a fresh one if the earlier page expired). The contract is concluded when that payment is received or authorised. No account is created. The answer has next_action (what to do now), like get_status; a test order has test_mode true and no checkout_url: the operator will simulate the payment AFTER you order, so right now nothing is paid or simulated. Report to the user only what this response says; do not add conclusions.

post/tasks

Request

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

Request body

quote_idstring required
terms_acceptedtrue required

Acceptance of https://handsforagents.com/terms.html by the operator.

terms_versionstring required

Currently 2026-09-29.

allow_anonymised_exampleboolean

Optional. Consent to publish this task as an anonymised example, under section 10 (Confidentiality) of the terms of service. Overrides the value sent with request_quote. Default false; can be withdrawn by e-mail.

Response

Task created, awaiting payment

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.