Sift Verification API

openapi: 3.2.0
info:
  title: Sift Verification API
  description: Sift is a digital trust and safety platform that uses machine learning to detect and prevent online fraud and abuse - payment fraud, account takeover, account abuse, content abuse, and promotion abuse.
  version: '2026-07-12'
  contact:
    name: Sift Developer Documentation
    url: https://developers.sift.com/docs
  x-modeled: true
  x-modeled-by: API Evangelist
  x-modeled-sources:
  - https://developers.sift.com/docs
  - https://developers.sift.com/docs/curl/apis-overview
  - https://github.com/SiftScience/sift-python
servers:
- url: https://api.sift.com
  description: Sift production API (single public host)
security:
- apiKeyBasic: []
tags:
- name: Verification
  description: One-time passcode (OTP) step-up verification.
paths:
  /v1/verification/send:
    post:
      operationId: verificationSend
      tags:
      - Verification
      summary: Send a verification code
      description: Triggers generation and delivery of a one-time passcode (OTP) to a user via a configured channel (for example email or SMS) as a step-up verification for a risky action.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationSendRequest'
      responses:
        '200':
          description: The verification code was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/verification/resend:
    post:
      operationId: verificationResend
      tags:
      - Verification
      summary: Resend a verification code
      description: Requests a new one-time passcode for a pending verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationResendRequest'
      responses:
        '200':
          description: A new verification code was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/verification/check:
    post:
      operationId: verificationCheck
      tags:
      - Verification
      summary: Check a verification code
      description: Validates the one-time passcode provided by the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationCheckRequest'
      responses:
        '200':
          description: The verification check result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    VerificationCheckRequest:
      type: object
      required:
      - $user_id
      - $code
      properties:
        $user_id:
          type: string
        $code:
          type: integer
          description: The one-time passcode entered by the user.
        verified_event:
          type: string
    VerificationResponse:
      type: object
      properties:
        status:
          type: integer
          description: Sift status code for the verification operation.
        error_message:
          type: string
        sent_at:
          type: integer
          format: int64
        checked_at:
          type: integer
          format: int64
    ApiError:
      type: object
      description: Modeled error envelope. Sift returns a numeric status and error_message.
      properties:
        status:
          type: integer
          description: Sift status code (0 indicates success; non-zero indicates an error).
        error_message:
          type: string
        time:
          type: integer
          format: int64
    VerificationSendRequest:
      type: object
      description: Request to send an OTP (modeled from documented examples).
      required:
      - $user_id
      - event
      properties:
        $user_id:
          type: string
        send_to:
          type: string
          description: Destination address (email or phone) for the OTP.
        verification_type:
          type: string
          enum:
          - $email
          - $sms
          - $phone_call
        brand_name:
          type: string
        language:
          type: string
        event:
          type: object
          description: The Sift event context that triggered the verification.
          additionalProperties: true
    VerificationResendRequest:
      type: object
      required:
      - $user_id
      properties:
        $user_id:
          type: string
        verified_event:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    apiKeyBasic:
      type: http
      scheme: basic
      description: HTTP Basic authentication using your Sift REST API key as the username and an empty password. Ingestion APIs (Events, Score, Labels) also accept the key as $api_key in the JSON request body. Account-scoped APIs (Decisions, Workflows, PSP Merchant Management) require your numeric Account ID in the path in addition to the API key.