openapi: 3.0.2
info:
  title: Labels
  version: ''
  description: >-
    Labels API provided by Fraud Prevention allows you to give feedback about
    the accuracy of recommendations you received from Transmit Security.
servers:
  - url: https://api.sbx.transmitsecurity.io/risk/v1
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/risk/v1
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/risk/v1
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/risk/v1
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/risk/v1
    description: Production environment (AU)
paths:
  /label:
    post:
      summary: Send label
      description: >-
        Sends the label to our servers for analysis to improve our
        recommendation system.
      operationId: sendLabel
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/label'
      responses:
        '201':
          $ref: '#/components/responses/label_received_and_stored'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
components:
  schemas:
    label:
      type: object
      required:
        - label_type
        - subject
      properties:
        label_type:
          type: string
          description: >-
            Type of label to send, which contains additional information that
            helps to classify the subject as fraudulent or legitimate
          enum:
            - KNOWN_MALICIOUS
            - SUSPECTED_MALICIOUS
            - KNOWN_LEGIT
            - UNKNOWN
        subject:
          $ref: '#/components/schemas/subject'
        use_case:
          type: string
          description: The fraud scenario.
          enum:
            - ACCOUNT_TAKEOVER
            - FIRST_PARTY_FRAUD
            - IDENTITY_THEFT
            - MONEY_MULE
            - BOT_ATTACK
            - SYNTHETIC_IDENTITY
            - SOCIAL_ENGINEERING
        source:
          type: string
          description: >-
            Source of the label information, such as a customer complaint about
            friction or additional information from another risk or fraud
            system.
          enum:
            - MANUAL_REVIEW
            - CUSTOMER_COMPLAINTS
            - CHARGEBACKS
            - OTHER_VENDORS
          x-enumDescriptions:
            MANUAL_REVIEW: from self manual analysis
            CUSTOMER_COMPLAINTS: from customer complains or responses
            CHARGEBACKS: from incorrect charges
            OTHER_VENDORS: from information and conclusion done in other systems and tools
    subject:
      description: Subject of the label
      properties:
        type:
          type: string
          description: The subject type.
          enum:
            - ACTION_ID
            - CORRELATION_ID
            - CAMPAIGN_ID
            - USER_ID
            - IP_ADDRESS
            - VERIFICATION_SESSION_ID
            - FRAUD_RING_ID
        value:
          type: string
          description: The subject value
          example: a05f8ae1-718f-4c33-a20c-682df281af7c
        recommendations:
          type: array
          items:
            type: string
            description: ID of the list item.
            enum:
              - allow
              - trust
              - challenge
              - deny
          description: >-
            For `FRAUD_RING_ID` labels only. Allows labeling actions with
            specific recommendation.
          nullable: true
        is_campaign_confirmed:
          type: boolean
          description: >-
            For `CAMPAIGN_ID` labels only. Defines whether or not to label
            actions related to the campaign.
          nullable: true
      required:
        - type
        - value
    label_success_response:
      type: object
      properties:
        message:
          type: string
        label_id:
          type: string
          description: ID of the saved label
        label:
          allOf:
            - type: object
              properties:
                label_id:
                  type: string
                  description: ID of the saved label
            - $ref: '#/components/schemas/label'
            - type: object
              properties:
                label_timestamp:
                  type: number
                  description: Unix time indicating the label creation time
                  example: 1725961384920
        afftectedActionIds:
          type: array
          items:
            type: string
            description: All action IDs which were labeled with current label request.
          example:
            - af819f2b3e2f1b2820077cb09fe92de5769c4e4b24030cf683f4d0b155ac4999
            - 9b83568185c39e4acb3e5d09176f0a70efdf5c414c2d1d90cb803dfb0b93ec53
      required:
        - message
        - label_id
        - label
        - afftectedActionIds
  responses:
    label_received_and_stored:
      description: Label has been received and stored successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/label_success_response'
    unauthorized:
      description: Invalid authentication
    forbidden:
      description: Invalid authorization
    rate_limit_reached:
      description: Rate limit reached
    internal_error:
      description: Internal error
    bad_request:
      description: Bad request
    not_found:
      description: Not found
  securitySchemes:
    risk_access_token:
      type: http
      scheme: bearer
      description: >-
        An access token generated by the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken), which should
        target the following resource: `https://risk.identity.security`
      bearerFormat: JWT
