One-time code (OTP)¶

The overview describes the common field interpretation rules, failure reasons, and full/light file formats.

Parent: otp_results[]. All stored phone verification records, newest first. An empty array means there are no records.

Fields of an otp_results[] item.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field	JSON type	Purpose and conditions
`phone_number`	string	Required. Phone number being verified, up to 20 characters.
`provider`	string, enum	Required. Currently the only value is `telegram`.
`status`	string, enum	Required. Values are listed below.
`result`	boolean	Stored technology result: `true` means accepted, `false` means a negative result. May be absent before calculation; consider the status and the details below.
`failure_reason`	object	Failure reason, if recorded; see the structure.

Values of otp_results[].status.

Do not confuse these lowercase statuses with the uppercase session statuses.

Field	JSON type	Purpose and conditions
`pending`	string	Waiting for code verification.
`wrong_code`	string	An incorrect code was supplied; this state does not necessarily mean that no retries remain.
`verified`	string	The code was verified.
`failed`	string	Verification ended with an error.
`expired`	string	Verification expired.
`cancelled`	string	Verification was canceled.

The OTP code itself, attempt count, and provider request identifier are not returned. A subsequent attempt may update the existing record or add a new one, depending on the scenario.

JSON examples¶

Fragments of the root response object, not complete responses. All values and URLs are illustrative. File formats follow the explanations on this page.

{
  "otp_results": [
    {
      "phone_number": "+70000000000",
      "provider": "telegram",
      "status": "verified",
      "result": true
    }
  ]
}