SecondFactor API

openapi: 3.1.0
info:
  title: SecondFactor API
  version: '2026-11-10'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-10: 7 operation(s) read from 6 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; SecondFactor has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 4
    documentation: 3
    pages-with-code: 6
    pages-read: 6
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-10'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.secondfactor.ai/sdk-android
  - https://docs.secondfactor.ai/hosted-verification
  - https://docs.secondfactor.ai/authentication
  - https://docs.secondfactor.ai/send-otp
  - https://docs.secondfactor.ai/check-otp
  - https://docs.secondfactor.ai/get-verification
servers:
- url: https://api.secondfactor.ai
paths:
  /secondfactor/secondfactor-kotlin/main/secondfactor/SecondFactor.kt:
    get:
      operationId: get_secondfactor_secondfactor_kotlin_main_secondfactor_SecondFactor_kt
      tags:
      - Secondfactor
      summary: GET /secondfactor/secondfactor-kotlin/main/secondfactor/SecondFactor.kt
      x-source: https://docs.secondfactor.ai/sdk-android
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl --create-dirs -o app/src/main/java/ai/secondfactor/SecondFactor.kt  https://raw.githubusercontent.com/secondfactor/secondfactor-kotlin/main/secondfactor/SecondFactor.kt
          Make sure your app has the INTERNET permission. The version is in the file's header. To update, download the file again and read the
          repository's CHANGELOG.md . Set up the return URL ​ The return URL must be an https://App Lin
  /v2/Services:
    get:
      operationId: get_v2_Services
      tags:
      - Services
      summary: GET /v2/Services
      x-source: https://docs.secondfactor.ai/authentication
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl Python Node.js Java Rust Go bash curl \"https://api.secondfactor.ai/v2/Services\"  -H \"X-API-Key: $SF_API_KEY \" python\
          \ import os \n import requests \n res = requests.get( \n \"https://api.secondfactor.ai/v2/Services\" , \n headers = { \"X-API-Key\"\
          \ : os.environ[ \"SF_API_KEY\" ]}, \n ) js const res = await fetch ( \"https://api.secondfactor.ai/v2/Services\" , { \n headers: { \"\
          X-API-Key\" : process.env. SF_API"
    post:
      operationId: post_v2_Services
      tags:
      - Services
      summary: POST /v2/Services
      x-source: https://docs.secondfactor.ai/hosted-verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV2ServicesRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV2ServicesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST \"https://api.secondfactor.ai/v2/Services/ $SERVICE_SID /VerificationSessions\"  -H \"X-API-Key: $SF_API_KEY \"\
          \  -H \"Content-Type: application/json\"  -d '{\"To\": \"+9779841000000\", \"ReturnUrl\": \"https://app.example.com/verified\", \"ClientReferenceId\"\
          : \"signup-8812\"}' json { \n \"sid\" : \"VSN26H7K3MQ2XWZ8RT4\" , \n \"status\" : \"OPEN\" , \n \"to\" : \"+9779841000000\" , \n \"\
          client_reference_id\" : \"signup-8"
  /v2/Services/{servicesid}/VerificationCheck:
    post:
      operationId: post_v2_Services_servicesid_VerificationCheck
      tags:
      - Services
      summary: Verifies the OTP your user typed.
      description: 200 means the code is correct, and no other status does.
      x-source: https://docs.secondfactor.ai/check-otp
      parameters:
      - name: servicesid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV2ServicesServicesidVerificationcheckRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV2ServicesServicesidVerificationcheckResponse'
      x-evidence:
        kind: documentation
  /v2/Services/{servicesid}/VerificationSessions/{sid}:
    get:
      operationId: get_v2_Services_servicesid_VerificationSessions_sid
      tags:
      - Services
      summary: Hosted verification
      description: Retrieve a session at any time with GET /v2/Services/{ServiceSid}/VerificationSessions/{sid}. Reading a session is not proof
        of anything; only Confirm is.
      x-source: https://docs.secondfactor.ai/hosted-verification
      parameters:
      - name: servicesid
        in: path
        required: true
        schema:
          type: string
      - name: sid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v2/Services/{servicesid}/Verifications:
    post:
      operationId: post_v2_Services_servicesid_Verifications
      tags:
      - Services
      summary: Send OTP
      x-source: https://docs.secondfactor.ai/send-otp
      parameters:
      - name: servicesid
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: A random string up to 191 characters, new for each code you send.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV2ServicesServicesidVerificationsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV2ServicesServicesidVerificationsResponse'
      x-evidence:
        kind: documentation
  /v2/Services/{servicesid}/Verifications/{verificationsid}:
    get:
      operationId: get_v2_Services_servicesid_Verifications_verificationsid
      tags:
      - Services
      summary: Get OTP status
      description: Returns the current state of a verification, in any state. Free, and it does not use up a check attempt. Use it to show delivery
        progress, or to catch up on events your webhook missed.
      x-source: https://docs.secondfactor.ai/get-verification
      parameters:
      - name: servicesid
        in: path
        required: true
        schema:
          type: string
      - name: verificationsid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV2ServicesServicesidVerificationsVerificationsidResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV2ServicesRequest:
      type: object
      properties:
        To:
          type: string
        ReturnUrl:
          type: string
        ClientReferenceId:
          type: string
    PostV2ServicesResponse:
      type: object
      properties:
        sid:
          type: string
        status:
          type: string
        to:
          type: string
        client_reference_id:
          type: string
        return_url:
          type: string
        url:
          type: string
        expires_at:
          type: string
          format: date-time
    PostV2ServicesServicesidVerificationcheckRequest:
      type: object
      properties:
        VerificationSid:
          type: string
          description: The sid returned when you sent the OTP.
        Code:
          type: string
          description: The code your user typed, up to 10 characters. It is compared exactly, so strip spaces and dashes first.
      required:
      - VerificationSid
      - Code
    PostV2ServicesServicesidVerificationcheckResponse:
      type: object
      properties:
        '200':
          type: string
          description: 'verification, status: VERIFIED – The code is correct.'
        '422':
          type: string
          description: 'verification, status: PENDING – Wrong code, with tries left.'
        '409':
          type: string
          description: 'verification, status: LOCKED / EXPIRED / VERIFIED – Wrong code and no tries left, or already verified, or code expired.'
        '400':
          type: string
          description: invalid_parameter – VerificationSid or Code is missing, or Code is longer than 10 characters.
        '404':
          type: string
          description: not_found – No verification with this SID belongs to you.
    PostV2ServicesServicesidVerificationsRequest:
      type: object
      properties:
        To:
          type: string
          description: The phone number in E.164 format, for example +9779841000000. Up to 20 characters.
        TemplateSid:
          type: string
          description: The ID of one of your message templates, from the Templates page. Omit it to use your default template.
        Code:
          type: string
          description: 'Usually omitted. Only if you generate codes yourself: 4 to 10 letters or digits that we deliver as-is, and that you check
            yourself.'
      required:
      - To
    PostV2ServicesServicesidVerificationsResponse:
      type: object
      properties:
        sid:
          type: string
          description: The verification SID ( VE… ). Store it server-side for the check.
        to:
          type: string
          description: The phone number, normalized to E.164.
        status:
          type: string
          description: 'The state of the code : PENDING , VERIFIED , EXPIRED or LOCKED.'
        delivery_status:
          type: string
          description: 'The state of the message : PENDING, SENT, DELIVERED or FAILED.'
        channel:
          type: string
          description: sms , whatsapp , viber , rcs or sna . Null if no channel is known yet.
        price:
          type: string
          description: What this send cost, as a decimal string.
        price_unit:
          type: string
          description: Always USD.
        attempts_remaining:
          type: integer
          description: How many more checks the code accepts.
        expires_at:
          type: string
          description: When the code stops working.
        date_created:
          type: string
          description: When the send was accepted.
    GetV2ServicesServicesidVerificationsVerificationsidResponse:
      type: object
      properties:
        sid:
          type: string
        to:
          type: string
        status:
          type: string
        delivery_status:
          type: string
        channel:
          type: string
        price:
          type: string
        price_unit:
          type: string
        attempts_remaining:
          type: integer
        expires_at:
          type: string
        date_created:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
security:
- apiKey: []
tags:
- name: Secondfactor
- name: Services