Sift Labels API

openapi: 3.0.3
info:
  title: Sift 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: Events
    description: Stream user activity to Sift's machine learning models.
  - name: Score
    description: Retrieve real-time Sift Scores per abuse type.
  - name: Decisions
    description: Apply and retrieve decisions against users, orders, sessions, and content.
  - name: Workflows
    description: Retrieve the status and results of Sift Workflow runs.
  - name: Labels
    description: Legacy API for labeling users to train models.
  - name: Verification
    description: One-time passcode (OTP) step-up verification.
  - name: PSP Merchant Management
    description: Manage sub-merchant profiles for payment service providers.
paths:
  /v205/events:
    post:
      operationId: postEvent
      tags:
        - Events
      summary: Send an event
      description: >-
        Records a user event (reserved types are prefixed with $, e.g.
        $create_account, $login, $create_order, $transaction, $chargeback,
        $content_status, plus custom events) so Sift can update its models. Set
        return_score=true to receive a Sift Score inline, or
        return_workflow_status=true to receive workflow decisions. The API key is
        supplied as $api_key in the body or via HTTP Basic auth.
      parameters:
        - name: return_score
          in: query
          required: false
          description: Return the user's Sift Score inline with the event response.
          schema:
            type: boolean
        - name: return_action
          in: query
          required: false
          description: Return actions triggered by the event.
          schema:
            type: boolean
        - name: return_workflow_status
          in: query
          required: false
          description: Return the status and decisions of any workflow run triggered by the event.
          schema:
            type: boolean
        - name: abuse_types
          in: query
          required: false
          description: Comma-separated abuse types to score against when return_score is true.
          schema:
            type: string
            example: payment_abuse,account_abuse,account_takeover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: The event was accepted. status 0 indicates success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
  /v205/users/{user_id}/labels:
    parameters:
      - $ref: '#/components/parameters/UserId'
    post:
      operationId: applyLabel
      tags:
        - Labels
      summary: Apply a label (legacy)
      description: >-
        Labels a user as good or bad for a given abuse type to train Sift's
        models. Legacy - Sift recommends the Decisions API for new integrations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Label'
      responses:
        '200':
          description: The label was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: removeLabel
      tags:
        - Labels
      summary: Remove a label (legacy)
      description: Removes a previously applied label from a user.
      parameters:
        - name: abuse_type
          in: query
          required: false
          description: The abuse type of the label to remove.
          schema:
            type: string
      responses:
        '200':
          description: The label was removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/decisions:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listDecisions
      tags:
        - Decisions
      summary: List configured decisions
      description: Lists the decisions configured for an account, optionally filtered by entity type and abuse type.
      parameters:
        - name: entity_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - user
              - order
              - session
              - content
        - name: abuse_types
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of configured decisions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/users/{user_id}/decisions:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: getUserDecisions
      tags:
        - Decisions
      summary: Get decision status for a user
      description: Retrieves the latest decisions applied to a user, per abuse type.
      responses:
        '200':
          description: The user's current decision status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: applyUserDecision
      tags:
        - Decisions
      summary: Apply a decision to a user
      description: Applies a decision (accept, watch, block) to a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: The decision was applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionApplyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/users/{user_id}/orders/{order_id}/decisions:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/OrderId'
    post:
      operationId: applyOrderDecision
      tags:
        - Decisions
      summary: Apply a decision to an order
      description: Applies a decision to a specific order belonging to a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: The decision was applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionApplyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/users/{user_id}/sessions/{session_id}/decisions:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/SessionId'
    post:
      operationId: applySessionDecision
      tags:
        - Decisions
      summary: Apply a decision to a session
      description: Applies a decision to a specific session belonging to a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: The decision was applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionApplyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/users/{user_id}/content/{content_id}/decisions:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/ContentId'
    post:
      operationId: applyContentDecision
      tags:
        - Decisions
      summary: Apply a decision to content
      description: Applies a decision to a specific piece of content created by a user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: The decision was applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionApplyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/workflows/runs/{run_id}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: run_id
        in: path
        required: true
        description: The ID of the workflow run.
        schema:
          type: string
    get:
      operationId: getWorkflowRun
      tags:
        - Workflows
      summary: Get a workflow run status
      description: Retrieves the status and applied decisions of a Sift Workflow run.
      responses:
        '200':
          description: The workflow run status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRun'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/accounts/{account_id}/psp_management/merchants:
    parameters:
      - $ref: '#/components/parameters/AccountId'
    get:
      operationId: listPspMerchants
      tags:
        - PSP Merchant Management
      summary: List PSP merchants
      description: Lists sub-merchant profiles for an account, paginated.
      parameters:
        - name: batch_size
          in: query
          required: false
          schema:
            type: integer
        - name: batch_token
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of merchant profiles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPspMerchant
      tags:
        - PSP Merchant Management
      summary: Create a PSP merchant
      description: Creates a new sub-merchant profile under an account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PspMerchant'
      responses:
        '201':
          description: The created merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/accounts/{account_id}/psp_management/merchants/{merchant_id}:
    parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: merchant_id
        in: path
        required: true
        description: The ID of the sub-merchant.
        schema:
          type: string
    get:
      operationId: getPspMerchant
      tags:
        - PSP Merchant Management
      summary: Get a PSP merchant
      description: Retrieves a specific sub-merchant profile.
      responses:
        '200':
          description: The merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePspMerchant
      tags:
        - PSP Merchant Management
      summary: Update a PSP merchant
      description: Updates an existing sub-merchant profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PspMerchant'
      responses:
        '200':
          description: The updated merchant profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PspMerchant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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:
  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.
  parameters:
    UserId:
      name: user_id
      in: path
      required: true
      description: The unique identifier for the user, URL-encoded.
      schema:
        type: string
    AccountId:
      name: account_id
      in: path
      required: true
      description: Your numeric Sift Account ID.
      schema:
        type: string
    OrderId:
      name: order_id
      in: path
      required: true
      description: The unique identifier for the order, URL-encoded.
      schema:
        type: string
    SessionId:
      name: session_id
      in: path
      required: true
      description: The unique identifier for the session, URL-encoded.
      schema:
        type: string
    ContentId:
      name: content_id
      in: path
      required: true
      description: The unique identifier for the content, URL-encoded.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  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
    Event:
      type: object
      description: >-
        A Sift event. Reserved fields are prefixed with $ (for example $type,
        $user_id, $api_key). Reserved event types include $create_account,
        $update_account, $login, $create_order, $update_order, $transaction,
        $chargeback, $content_status, $create_content, and more; custom events use
        an unprefixed type. This schema is modeled from documented examples and
        shows common fields rather than the full field dictionary.
      required:
        - $type
        - $api_key
      properties:
        $type:
          type: string
          description: The event type, e.g. $create_order or a custom type.
          example: $create_order
        $api_key:
          type: string
          description: Your Sift REST API key (may instead be supplied via HTTP Basic auth).
        $user_id:
          type: string
          description: The user this event is associated with.
        $session_id:
          type: string
        $order_id:
          type: string
        $user_email:
          type: string
        $ip:
          type: string
        $amount:
          type: integer
          format: int64
          description: Amount in micros (1/1,000,000 of the base currency unit).
        $currency_code:
          type: string
          example: USD
      additionalProperties: true
    EventResponse:
      type: object
      description: Modeled response envelope for event and label ingestion.
      properties:
        status:
          type: integer
          description: 0 indicates the event was accepted.
        error_message:
          type: string
        time:
          type: integer
          format: int64
        request:
          type: string
        score_response:
          $ref: '#/components/schemas/ScoreResponse'
    Label:
      type: object
      description: Legacy label payload (modeled from documented examples).
      required:
        - $api_key
        - $is_bad
        - $abuse_type
      properties:
        $api_key:
          type: string
        $is_bad:
          type: boolean
          description: true labels the user as bad (fraudulent) for the abuse type.
        $abuse_type:
          type: string
          enum:
            - payment_abuse
            - account_abuse
            - account_takeover
            - content_abuse
            - promotion_abuse
            - legacy
        $description:
          type: string
        $source:
          type: string
        $analyst:
          type: string
    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
    DecisionRequest:
      type: object
      description: Request to apply a decision to an entity (modeled from documented examples).
      required:
        - decision_id
        - source
      properties:
        decision_id:
          type: string
          description: The ID of a decision configured in the Sift console.
          example: block_user_payment_abuse
        source:
          type: string
          enum:
            - MANUAL_REVIEW
            - AUTOMATED_RULE
            - CHARGEBACK
          description: What produced the decision.
        analyst:
          type: string
          description: Identifier (e.g. email) of the analyst, required when source is MANUAL_REVIEW.
        description:
          type: string
        time:
          type: integer
          format: int64
          description: Epoch milliseconds the decision was made.
    DecisionApplyResponse:
      type: object
      properties:
        entity:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
        decision:
          type: object
          properties:
            id:
              type: string
        time:
          type: integer
          format: int64
    DecisionStatus:
      type: object
      description: The latest decisions applied to an entity, keyed by abuse type.
      properties:
        decisions:
          type: object
          additionalProperties:
            type: object
            properties:
              decision:
                type: object
                properties:
                  id:
                    type: string
              time:
                type: integer
                format: int64
              webhook_succeeded:
                type: boolean
    DecisionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Decision'
    Decision:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        entity_type:
          type: string
          enum:
            - user
            - order
            - session
            - content
        abuse_type:
          type: string
        category:
          type: string
          enum:
            - block
            - watch
            - accept
    WorkflowRun:
      type: object
      description: Workflow run status (modeled).
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - running
            - finished
            - failed
        entity:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
        history:
          type: array
          items:
            type: object
            additionalProperties: true
    PspMerchantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PspMerchant'
        has_more:
          type: boolean
        next_ref:
          type: string
        total_results:
          type: integer
    PspMerchant:
      type: object
      description: PSP sub-merchant profile (modeled from documented examples).
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Your unique identifier for the sub-merchant.
        name:
          type: string
        description:
          type: string
        address:
          type: object
          additionalProperties: true
        category:
          type: string
        service_level:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
        risk_profile:
          type: object
          properties:
            level:
              type: string
            score:
              type: number
              format: float
    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
    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