openapi: 3.0.3
info:
  title: Sift Decisions 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. This definition covers Sift''s public REST APIs: the Events API (stream user activity), the Score API (real-time Sift Scores 0-100 per abuse type), the Decisions API (apply/retrieve accept/watch/block decisions), the Workflow Status API, the legacy Labels API, the Verification API (OTP step-up), and the PSP Merchant Management API.


    MODELED SPECIFICATION - IMPORTANT: Sift does not publish a single machine-readable OpenAPI document. This file was MODELED by API Evangelist from Sift''s public developer documentation (developers.sift.com) and its officially maintained open-source client libraries (sift-python, sift-ruby, sift-java), which encode the exact paths, HTTP methods, and per-API versions. Endpoint paths, methods, versions, and authentication are confirmed against those sources. Request and response bodies are REPRESENTATIVE: Sift documents example payloads and field dictionaries rather than full JSON Schemas for most resources, so the schema shapes here are modeled from documented examples and may not enumerate every optional field. See review.yml for the confirmed-vs-modeled breakdown.


    Versioning is per API family: Events, Score, and Labels are on v205; Decisions, Workflows, and PSP Merchant Management are on v3; Verification is on v1.'
  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:
    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
    VerificationResendRequest:
      type: object
      required:
      - $user_id
      properties:
        $user_id:
          type: string
        verified_event:
          type: string
    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
    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
  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.