> ## Documentation Index
> Fetch the complete documentation index at: https://otpless.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Check API

> Poll the current auth status for a requestId. Returns the auth factor plus phone and device-fingerprinting detail when available.

The Status Check API is the **authoritative source of truth** for the authentication flow. Your backend polls it with the `requestId` (ARID token) from the [Create API](/docs/server-initiated-auth/create-api) to determine the final auth outcome. Poll until the `PRIMARY` factor reaches a terminal status (`SUCCESS` or `FAILED`).

<Warning>
  This is a **server-to-server** call. It requires your `clientId` and `clientSecret` headers. Confirm a successful login based on this response — not on the SDK callback alone.
</Warning>

<Note>
  The `deviceFingerprinting` block is enriched **only if the OTPless Device Intelligence SDK is imported and initialized** in your client app. If it isn't, the field is omitted from the response — the rest of the auth status is unaffected.
</Note>

<Accordion title="Interpreting the result">
  Read the `PRIMARY` factor's `status` in `auths[]`:

  | `auths[].status` | Meaning | Action |
  | - | - | - |
  | `PENDING` | Authentication is still in progress. | Keep polling. |
  | `SUCCESS` | Authentication completed and the identity was verified. `verifiedTimestamp` is populated. | Log the user in and proceed with the journey. |
  | `FAILED` | Authentication could not be completed. An `error` object with `errorCode` and `message` is present. | Show a failure / retry flow. |

  Before auth is initialized you may receive an **HTTP 400** with `errorCode` `7170` ("Auth not started yet"). This is **not** terminal — if auth has been initiated, keep polling. A `7119` ("Invalid request Id") means the `requestId` is malformed.

  Poll until the `PRIMARY` factor reaches a terminal status (`SUCCESS` or `FAILED`), or until the request expires — the `expiry` you set in the [Create API](/docs/server-initiated-auth/create-api) bounds the request's validity.
</Accordion>

## Verification error codes

When `auths[].status` is `FAILED`, inspect `auths[].error.errorCode` to determine the failure and your next step. See the full [API Error Codes](/docs/server-initiated-auth/api-error-codes) reference for the complete list of `SP*` codes and their messages.

## Polling guidance

Begin polling after starting authentication on the client. Recommended strategy:

| Parameter | Recommended value |
| - | - |
| Interval | 1 – 2 seconds |
| Terminal states | `SUCCESS` or `FAILED` — stop polling immediately. |
| Timeout | If still `PENDING` after your max attempts (bounded by `expiry`), treat as timeout and show a retry flow. |

<Note>
  An HTTP 400 with `errorCode` `7170` is transient — it can appear briefly before auth initializes. Keep polling if auth was initiated; only `7119` indicates a malformed `requestId`.
</Note>


## OpenAPI

````yaml server-initiated-auth/server-initiated-auth-api.yaml GET /auth/v2/status
openapi: 3.0.3
info:
  title: OTPless Server-Initiated Auth APIs
  description: >
    Server-to-server APIs for the server-initiated authentication flow.


    - **Create** — register a user's identity (phone number or email) and obtain
    a `requestId`. Pass this `requestId` to the SDK on the client to perform
    authentication.

    - **Status Check** — poll the consolidated auth status for a `requestId` to
    determine the final, authoritative outcome.


    **Authentication:** All requests require `clientId` and `clientSecret` as
    request headers. Never expose these in client-side code.
  version: 1.0.0
servers:
  - url: https://auth.otpless.app
    description: Production server
security:
  - ApiKeyAuth: []
    ApiSecretAuth: []
paths:
  /auth/v2/status:
    get:
      tags:
        - Server-Initiated Auth
      summary: Status Check
      description: >
        Returns the current status of an authentication request for a given
        `requestId`.


        The response carries the auth factor(s) in `auths[]` along with phone
        and device-fingerprinting detail when available. Read the `PRIMARY`
        factor's `status`.


        Poll until the `PRIMARY` factor reaches a terminal status (`SUCCESS` or
        `FAILED`). The result from this API — not the SDK callback alone — is
        the source of truth for confirming a successful login.
      operationId: checkAuthStatus
      parameters:
        - name: requestId
          in: query
          required: true
          schema:
            type: string
            example: ARID_A1B2C3D4E5F6
          description: The ARID token (`requestId`) returned by POST /auth/v1/create.
      responses:
        '200':
          description: >-
            **HTTP 200** — Current auth status for the `requestId`.
            `auths[].status` is `PENDING`, `SUCCESS`, or `FAILED`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                pending:
                  summary: Pending — authentication still in progress
                  value:
                    auths:
                      - identityType: MOBILE
                        identityValue: '917069914791'
                        status: PENDING
                        type: PRIMARY
                    phoneDetail:
                      countryCode: '91'
                      country: IN
                      type: MOBILE
                      location: India
                      timeZones:
                        - Asia/Calcutta
                    deviceFingerprinting:
                      status: SUCCESS
                      sessionId: a98ead44-f4db-4801-8c3f-041f98140734
                      deviceId: 781b21f7-220b-4f44-9155-6261f8564924
                      newDevice: false
                      riskAssessment:
                        sessionRiskLevel: HIGH
                        deviceRiskLevel: HIGH
                        sessionRiskScore: 95
                        deviceRiskScore: 90
                        ipFraudScore: 0
                        flags:
                          isVpn: false
                          isEmulator: false
                          isAppTampered: true
                      deviceContext:
                        brand: iQOO
                        model: I2410
                        os: Android
                        osVersion: '16'
                      networkContext:
                        ipAddress: 106.205.222.198
                        ipType: v4
                        asn: '45609'
                        isp: Bharti Airtel Limited
                success:
                  summary: Success — authentication completed
                  value:
                    auths:
                      - identityType: MOBILE
                        identityValue: '917069914791'
                        status: SUCCESS
                        verifiedTimestamp: 1781091069000
                        type: PRIMARY
                    phoneDetail:
                      countryCode: '91'
                      country: IN
                      type: MOBILE
                      location: India
                      timeZones:
                        - Asia/Calcutta
                    deviceFingerprinting:
                      status: SUCCESS
                      sessionId: a98ead44-f4db-4801-8c3f-041f98140734
                      deviceId: 781b21f7-220b-4f44-9155-6261f8564924
                      newDevice: false
                      riskAssessment:
                        sessionRiskLevel: HIGH
                        deviceRiskLevel: HIGH
                        sessionRiskScore: 95
                        deviceRiskScore: 90
                        ipFraudScore: 0
                        flags:
                          isVpn: false
                          isEmulator: false
                          isAppTampered: true
                      deviceContext:
                        brand: iQOO
                        model: I2410
                        os: Android
                        osVersion: '16'
                      networkContext:
                        ipAddress: 106.205.222.198
                        ipType: v4
                        asn: '45609'
                        isp: Bharti Airtel Limited
                failed:
                  summary: Failed — authentication could not complete
                  value:
                    auths:
                      - identityType: MOBILE
                        identityValue: '917069914791'
                        status: FAILED
                        type: PRIMARY
                        error:
                          errorCode: SP40003
                          message: Verification failed
                          description: >-
                            Verification could not be completed. Please try
                            again or contact OTPless support if it continues.
                    phoneDetail:
                      countryCode: '91'
                      country: IN
                      type: MOBILE
                      location: India
                      timeZones:
                        - Asia/Calcutta
                    deviceFingerprinting:
                      status: SUCCESS
                      sessionId: a98ead44-f4db-4801-8c3f-041f98140734
                      deviceId: 781b21f7-220b-4f44-9155-6261f8564924
                      newDevice: false
                      riskAssessment:
                        sessionRiskLevel: HIGH
                        deviceRiskLevel: HIGH
                        sessionRiskScore: 95
                        deviceRiskScore: 90
                        ipFraudScore: 0
                        flags:
                          isVpn: false
                          isEmulator: false
                          isAppTampered: true
                      deviceContext:
                        brand: iQOO
                        model: I2410
                        os: Android
                        osVersion: '16'
                      networkContext:
                        ipAddress: 106.205.222.198
                        ipType: v4
                        asn: '45609'
                        isp: Bharti Airtel Limited
        '400':
          description: >
            **HTTP 400.** Request rejected. `7170` is not necessarily terminal —
            if auth has been initiated, keep polling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_not_started:
                  summary: Auth not started yet (7170)
                  value:
                    message: Invalid Request
                    errorCode: '7170'
                    description: >-
                      Auth not started yet. Please initiate authentication
                      first.
                invalid_request_id:
                  summary: Invalid request Id (7119)
                  value:
                    message: Invalid Request
                    errorCode: '7119'
                    description: 'Request error: Invalid request Id'
        '401':
          description: >-
            **HTTP 401.** Unauthorized. `clientId`/`clientSecret` headers are
            missing, invalid, or the merchant is blocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                credentials_empty:
                  summary: Credentials empty (7012)
                  value:
                    message: Access blocked
                    errorCode: '7012'
                    description: 'Authorization error: Merchant credentials are empty'
                invalid_credentials:
                  summary: Invalid credentials (7002)
                  value:
                    message: Access blocked
                    errorCode: '7002'
                    description: 'Authorization error: Invalid credentials'
                merchant_blocked:
                  summary: Merchant blocked (7019)
                  value:
                    message: Merchant Blocked
                    errorCode: '7019'
                    description: >-
                      Your account has been temporarily Blocked. Please contact
                      support for assistance.
components:
  schemas:
    StatusResponse:
      type: object
      properties:
        auths:
          type: array
          description: >-
            Authentication factor(s) for the request. Read the `PRIMARY` factor
            for the final outcome.
          items:
            $ref: '#/components/schemas/AuthFactor'
        phoneDetail:
          $ref: '#/components/schemas/PhoneDetail'
        deviceFingerprinting:
          $ref: '#/components/schemas/DeviceFingerprinting'
    Error:
      type: object
      description: Error response body for HTTP 4xx responses.
      properties:
        message:
          type: string
          example: Invalid Request
        errorCode:
          type: string
          example: '7170'
          description: Machine-readable error code.
        description:
          type: string
          example: Auth not started yet. Please initiate authentication first.
    AuthFactor:
      type: object
      properties:
        identityType:
          type: string
          enum:
            - MOBILE
            - EMAIL
          example: MOBILE
          description: Type of identity being authenticated.
        identityValue:
          type: string
          example: '917069914791'
          description: >-
            The identity being authenticated — a phone number in E.164 format
            (without `+`) or an email.
        status:
          type: string
          enum:
            - SUCCESS
            - FAILED
            - PENDING
          description: Current status of this auth factor.
        type:
          type: string
          enum:
            - PRIMARY
            - MFA
          description: Role of this auth step. `PRIMARY` for the main attempt.
        verifiedTimestamp:
          type: integer
          format: int64
          example: 1781091069000
          description: >-
            Unix timestamp (ms) of successful verification. Present only when
            `status` is `SUCCESS`.
        error:
          $ref: '#/components/schemas/AuthError'
    PhoneDetail:
      type: object
      description: Phone number metadata. Present when the identity is a phone number.
      properties:
        countryCode:
          type: string
          example: '91'
          description: Country calling code (e.g. 91 for India).
        country:
          type: string
          example: IN
          description: ISO 3166-1 alpha-2 country code.
        type:
          type: string
          example: MOBILE
          description: Line type of the phone number.
        location:
          type: string
          example: India
          description: Country name in English.
        timeZones:
          type: array
          items:
            type: string
          example:
            - Asia/Calcutta
          description: IANA timezone identifiers for the phone's country.
    DeviceFingerprinting:
      type: object
      description: >-
        Device risk and context signals. Enriched only if the OTPless Device
        Intelligence SDK is imported and initialized in the client app;
        otherwise this field is omitted.
      properties:
        status:
          type: string
          enum:
            - SUCCESS
            - FAILED
          description: Fingerprinting result.
        sessionId:
          type: string
          format: uuid
          description: Unique identifier for this fingerprinting session.
        deviceId:
          type: string
          format: uuid
          description: Stable identifier for the device across sessions.
        newDevice:
          type: boolean
          description: '`true` if this is the first time this device has been seen.'
        riskAssessment:
          $ref: '#/components/schemas/RiskAssessment'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        networkContext:
          $ref: '#/components/schemas/NetworkContext'
    AuthError:
      type: object
      description: >-
        Error details for a failed auth factor. Present only when `status` is
        `FAILED`. See the full [API Error
        Codes](/server-initiated-auth/api-error-codes) reference.
      properties:
        errorCode:
          type: string
          example: SP40003
          description: Machine-readable `SP`-prefixed error code (e.g. SP40003).
        message:
          type: string
          example: Verification failed
          description: Short, machine-oriented error message.
        description:
          type: string
          example: >-
            Verification could not be completed. Please try again or contact
            OTPless support if it continues.
          description: User-friendly description suitable for showing to end users.
    RiskAssessment:
      type: object
      description: Risk scores and detection flags.
      properties:
        sessionRiskLevel:
          type: string
          enum:
            - LOW
            - MEDIUM
            - HIGH
          description: Risk level for this session.
        deviceRiskLevel:
          type: string
          enum:
            - LOW
            - MEDIUM
            - HIGH
          description: Risk level for this device.
        sessionRiskScore:
          type: integer
          description: Session risk score, 0–100. Higher = riskier.
        deviceRiskScore:
          type: integer
          description: Device risk score, 0–100. Higher = riskier.
        ipFraudScore:
          type: integer
          description: Fraud score for the client IP, 0–100.
        flags:
          $ref: '#/components/schemas/RiskFlags'
    DeviceContext:
      type: object
      description: Hardware and OS context.
      properties:
        brand:
          type: string
          example: iQOO
          description: Device manufacturer brand (e.g. iQOO, Samsung, Apple).
        model:
          type: string
          example: I2410
          description: Device model identifier.
        product:
          type: string
          description: Product/SKU variant name.
        os:
          type: string
          example: Android
          description: 'Operating system: Android or iOS.'
        osVersion:
          type: string
          example: '16'
          description: OS version string.
        cpuType:
          type: string
          description: CPU chipset model.
        screenResolution:
          type: string
          description: Screen resolution in WxH pixels.
        totalRamBytes:
          type: integer
          format: int64
          description: Total physical RAM in bytes.
        storage:
          type: object
          properties:
            totalBytes:
              type: integer
              format: int64
              description: Total internal storage capacity in bytes.
            availableBytes:
              type: integer
              format: int64
              description: Available (free) internal storage in bytes.
        lifecycle:
          type: object
          properties:
            firstSeenAt:
              type: integer
              format: int64
              description: >-
                Unix timestamp (ms) when this device was first observed by
                OTPless.
            firstSeenDays:
              type: integer
              description: Number of days since the device was first seen.
            factoryResetTime:
              type: integer
              format: int64
              description: Unix timestamp (ms) of the last detected factory reset.
        simInfo:
          type: object
          properties:
            totalSimsUsed:
              type: integer
              description: Total number of distinct SIMs ever used in this device.
            activeSims:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    description: Internal SIM record identifier.
                  slotIndex:
                    type: integer
                    description: Physical SIM slot index (0-based).
                  carrierName:
                    type: string
                    description: Carrier name as reported by the SIM.
    NetworkContext:
      type: object
      description: IP and location context from device fingerprinting.
      properties:
        ipAddress:
          type: string
          example: 106.205.222.198
          description: Client IP address at time of fingerprinting.
        ipType:
          type: string
          enum:
            - v4
            - v6
          description: IP version.
        asn:
          type: string
          example: '45609'
          description: Autonomous System Number of the IP.
        isp:
          type: string
          example: Bharti Airtel Limited
          description: Internet Service Provider name.
        location:
          type: object
          properties:
            city:
              type: string
              description: City resolved from the IP address.
            region:
              type: string
              description: State or region resolved from the IP address.
            country:
              type: string
              description: Country resolved from the IP address.
            latitude:
              type: number
              description: Latitude of the IP geolocation.
            longitude:
              type: number
              description: Longitude of the IP geolocation.
    RiskFlags:
      type: object
      description: >-
        Boolean detection flags. Availability of individual flags depends on
        platform and signal coverage.
      properties:
        isVpn:
          type: boolean
          description: Device is connected via a VPN.
        isProxy:
          type: boolean
          description: Device is connected via a proxy.
        isTor:
          type: boolean
          description: Device is connected via the Tor network.
        isEmulator:
          type: boolean
          description: Device is an emulator or virtual device.
        isRooted:
          type: boolean
          description: Device has been rooted (Android) or jailbroken (iOS).
        isCloned:
          type: boolean
          description: App is running in a cloned or parallel space environment.
        isAppTampered:
          type: boolean
          description: App binary has been modified or tampered with.
        isGeoSpoofed:
          type: boolean
          description: Device location appears to be spoofed.
        isMirroredScreen:
          type: boolean
          description: Screen is being mirrored or cast to another device.
        isHooking:
          type: boolean
          description: Runtime hooking framework (e.g. Frida, Xposed) detected.
        adbEnabled:
          type: boolean
          description: Android Debug Bridge (ADB) is enabled on the device.
        debuggingEnabled:
          type: boolean
          description: Debugging mode is active on the device.
        developerOptionsEnabled:
          type: boolean
          description: Developer options are enabled in Android settings.
        usbDebuggingEnabled:
          type: boolean
          description: USB debugging is enabled.
        accessibilityEnabled:
          type: boolean
          description: Accessibility services are active (potential overlay/bot risk).
        identifiersChanged:
          type: boolean
          description: Device identifiers have changed since last seen.
        onCall:
          type: boolean
          description: Device is on an active phone call during auth.
        isOEMUnlockAllowed:
          type: boolean
          description: OEM bootloader unlock is allowed on this device.
        googlePlayStoreInstall:
          type: boolean
          description: App was installed from the Google Play Store.
        debuggerAttached:
          type: boolean
          description: A debugger is currently attached to the app process.
        wirelessDebugging:
          type: boolean
          description: Wireless ADB debugging is enabled.
        usbConnected:
          type: boolean
          description: Device is connected to a computer via USB.
        isIpProxy:
          type: boolean
          description: Client IP is flagged as a known proxy address.
        isIpVpn:
          type: boolean
          description: Client IP is flagged as a known VPN exit node.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: clientId
      description: OTPless API Client ID
    ApiSecretAuth:
      type: apiKey
      in: header
      name: clientSecret
      description: OTPless API Client Secret

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.