AthausDocs

Reject a proposal

Request, parameters, response and errors of POST /v1/proposals/{id}/reject.

Last updated:

Says no to a pending proposal. Nothing is sent, and the proposal ends as rejected. Needs the key scope decide (and approve), which the office switches on when it creates the key; without it the answer is 403 insufficient_permissions. With a test key the scope is not needed: in the test office nobody else can say yes. Only a proposal of this API key can be decided, and only a reply or a follow-up to an inquiry: for any other kind, the publication of a listing included, which only a person says yes to in the app (the office's automation level decides whether it needs one), the answer is 403 forbidden. The decision runs the same code as the click in the app, with the same checks, the same 409 when the proposal was decided or has lapsed, and the same history, where it is recorded as made by this key, never by the person who created the key. Send an Idempotency-Key to retry safely. At most 30 decisions a minute per key. Needs write access to inquiries.

Requires the scope propose.

Request

POST https://api.athaus.ai/v1/proposals/{id}/reject

Parameters

Path

NameTypeRequiredDescription
idstring (uuid)yesUUID of the proposal.

Header

NameTypeRequiredDescription
Athaus-VersionstringnoOptional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported.
Idempotency-KeystringnoMakes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again.

Example

curl -X POST "https://api.athaus.ai/v1/proposals/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17/reject" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)"

Response

On success the status is 200 with Proposal.

Proposal

FieldTypeDescription
objectstringAlways proposal.
idstringUUID of the proposal.
statusstringOne of pending, approved, executed, failed, rejected, expired.
actionstringWhat the proposal does once it is approved. The list is open: new actions arrive, and a client treats an unknown one as a proposal it follows by status. One of inquiry.reply, inquiry.follow_up, listing.publish.
targetobjectWhat the action is about: an inquiry, or the listing (its listingId) to publish.
target.objectstringOne of inquiry, listing.
target.idstring
textstringThe message that goes to the person who inquired; for listing.publish a sentence naming the listing. Where a human changed a message before approving, the changed text.
livemodebooleanfalse for a proposal of the test office (test keys): approving it records the message as sent in the thread with a note that it was not delivered, and nothing leaves Athaus.
createdAtstring (date-time)
decidedAtstring (date-time) | nullWhen a human, an API key with the scope decide or the automation of the office said yes or no, or the proposal expired. Null while pending.
decidedByobject | nullThe API key that said yes or no. Null while pending and when a person or the office's automation decided.
decidedBy.objectstringAlways api_key.
decidedBy.idstring
decidedBy.namestring | null
executedAtstring (date-time) | nullWhen the message was delivered, or the listing went online. Null until then.

Response headers

HeaderDescription
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
ETagA strong entity tag of this state of the resource. Send it as If-Match to change or delete the resource only if it is unchanged, or as If-None-Match to read it only if it changed.
RateLimit-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.
Idempotent-Replayedtrue when this is the stored answer to an earlier request with the same Idempotency-Key.

Errors

Every error arrives as problem details. Branch on code, not on title or detail.

StatusCodesMeaning
400invalid_id, api_version_unsupportedInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
409proposal_already_decidedThe request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.
422The idempotency key was already used with a different request body.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Keep reading

On this page