Auth

Poll a mobile-app-approval checkpoint

Polls the pending mobile-app-approval challenge for account_id and advances it; call repeatedly until active. Returns active once approved, pending while waiting, or checkpoint_required if it chains. A code-based checkpoint here returns 422; use checkpoint/solve.

post/v1/auth/checkpoint/poll

Request

  • Base URL: https://api.curviate.com
  • URL: https://api.curviate.com/v1/auth/checkpoint/poll
  • Auth: HTTP bearer

Request body

account_idstring required

The account whose mobile-app-approval connect is mid-flight (returned with the 202 checkpoint_required response).

Response

The current state of the action-based (mobile-app-approval) challenge. object:"account" + status:"active" once approved (the account is now connected); object:"checkpoint" + status:"pending" while still waiting; status:"checkpoint_required" when the collect chained to a new challenge (e.g. approval -> 2FA), switch to submitting the new challenge_type; status:"expired"/"failed" on timeout/failure. object:"account" + recovered:true means the approval reactivated an account you had previously disconnected, which keeps its original id; its status is that account's real observed state, so it may be reconnect_needed rather than active.

object'account' | 'checkpoint'

Response type discriminator: account on approval, checkpoint while pending/chained/terminal.

status'active' | 'reconnect_needed' | 'restricted' | 'disconnected' | 'pending' | 'checkpoint_required' | 'expired' | 'failed'
recoveredboolean

Present and true only when this approval reactivated an account you had previously disconnected, instead of opening a brand-new one. Absent on a normal approval. The account keeps its original id, and its status reflects its real observed state, which may need a reconnect.

account_idstring

Present on status:"active" (the connected account) and status:"checkpoint_required" (the account whose next challenge is pending).

full_namestring nullable

Present on status:"active".

headlinestring nullable

Present on status:"active".

seat_idstring nullable

The seat this account occupies (canonical, supersedes the deprecated attached_seat_id). Present on status:"active".

attached_seat_idstring nullable

Deprecated, use seat_id (same value). Removed at the GA /v1 cutover. Present on status:"active".

external_idstring nullable

Your own id for this account's end user, as passed on connect. Present on status:"active".

expires_atstring

ISO-8601 expiry. Present on status:"pending" and status:"checkpoint_required".

challenge_type'mobile_app_approval' | 'otp' | 'two_factor_sms' | 'two_factor_app' | 'two_factor_whatsapp' | 'contract_selection' | 'challenge_selection'

Machine-readable challenge discriminator. On status:"checkpoint_required" it is the NEW challenge to submit; on status:"expired" it renders the right recovery guidance.

recovery_hintstring

Human-readable, actionable next step when the approval timed out. Present on status:"expired".

Example response

{
  "safety_warning": {
    "row": "profile_views",
    "reset_at": "2026-09-05T00:00:00.000Z",
    "hint": {
      "parameter": "profile_views.ceiling",
      "message": "This account is at its ceiling for profile_views. This action went through because profile_views.posture is warn, and it counted: 101 of 100 this window. Raise profile_views.ceiling, or wait for the window to reset at 2026-09-05T00:00:00.000Z."
    },
    "reason": "ceiling",
    "blocked": false
  }
}

Changes

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