openapi: 3.0.3
info:
  title: Sift Decisions Score 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: Score
  description: Retrieve real-time Sift Scores per abuse type.
paths:
  /v205/score/{user_id}:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: getScore
      tags:
      - Score
      summary: Get a user's Sift Score
      description: Retrieves the current Sift Score(s) for a user. Scores range 0-100 (higher is riskier) and are returned per abuse type with reason codes.
      parameters:
      - name: abuse_types
        in: query
        required: false
        description: Comma-separated abuse types to return scores for.
        schema:
          type: string
          example: payment_abuse,account_takeover
      - name: api_key
        in: query
        required: false
        description: API key, if not supplied via HTTP Basic auth.
        schema:
          type: string
      responses:
        '200':
          description: The user's Sift Score response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v205/users/{user_id}/score:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserScore
      tags:
      - Score
      summary: Get latest score (no recompute)
      description: Fetches the latest previously computed Sift Score for a user without recomputing it.
      parameters:
      - name: abuse_types
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The user's latest Sift Score response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: rescoreUser
      tags:
      - Score
      summary: Rescore a user
      description: Recomputes and returns the Sift Score for a user for the specified abuse types.
      parameters:
      - name: abuse_types
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The recomputed Sift Score response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      description: The unique identifier for the user, URL-encoded.
      schema:
        type: string
  schemas:
    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
    ScoreResponse:
      type: object
      description: Sift Score response (modeled). Scores range 0-100; higher is riskier. The scores object is keyed by abuse type, each carrying a score and reason codes.
      properties:
        status:
          type: integer
        error_message:
          type: string
        user_id:
          type: string
        scores:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AbuseScore'
          description: Keyed by abuse type - payment_abuse, account_abuse, account_takeover, content_abuse, promotion_abuse.
        latest_labels:
          type: object
          additionalProperties: true
    AbuseScore:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Score expressed 0-1 in the API payload; presented as 0-100 in the console.
        reasons:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              details:
                type: object
                additionalProperties: true
  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.