openapi: 3.1.0
info:
  title: Client Actions
  version: ''
  description: >-
    This backend API is used to report client actions, add the user context and
    report action results, allowing Fraud Prevention reporting and user
    profiling.
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:
  /action/trigger-action:
    post:
      summary: Trigger action event
      description: Report a client action event that occurs in an SDK session
      operationId: triggerAnAction
      security:
        - risk_access_token: []
      parameters:
        - name: get_recommendation
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            A flag for getting the recommendation for the triggered action (for
            saving another recommendation backend call)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/triggeraction'
      responses:
        '201':
          $ref: '#/components/responses/trigger_action_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'
  /action/result:
    post:
      summary: Report action result
      description: >-
        Reports the result of an action that a recommendation was issued for.
        This includes whether the user successfully completed the action, and
        what type of challenge was given to the user (if any).
      operationId: reportActionResult
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/actionResult'
      responses:
        '201':
          $ref: '#/components/responses/action_result_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'
  /action/authenticated-user:
    post:
      summary: Set authenticated user
      description: >-
        Sets the user context for a client action reported to the SDK. It should
        be set only after you've fully authenticated the user (including, for
        example, any 2FA that was required). This call is **deprecated**, set
        the user with [Report action result
        API](/openapi/risk/client-actions.openapi/other/reportactionresult).
      operationId: setAuthUser
      deprecated: true
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authuser'
      responses:
        '201':
          $ref: '#/components/responses/userauth_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'
  /action/assignee:
    put:
      summary: Assign actions
      description: Set assignee for a list of actions.
      operationId: updateActionAssignee
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setAssignee'
      responses:
        '200':
          $ref: '#/components/responses/actions_assignee_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
components:
  schemas:
    triggeraction:
      type: object
      required:
        - session_token
        - action_type
      properties:
        session_token:
          type: string
          description: >-
            A token returned by the SDK for the device session established upon
            SDK initialization.
        action_type:
          type: string
          description: The action type
          example: transaction
        user_id:
          type: string
          description: Opaque identifier of the authenticated user in your system.
        claimed_user_id_type:
          type: string
          enum:
            - email
            - phone_number
            - account_id
            - ssn
            - national_id
            - passport_number
            - drivers_license_number
            - other
          description: >
            Specifies the type of value provided in the claimed_user_id field.
            This field is especially important when claimed_user_id contains a
            hashed value, as it clarifies the original data type used.
        claimed_user_id:
          type: string
          description: >-
            User identifier of the not yet authenticated user, used to enhance
            risk and trust assessments. This field should not contain sensitive
            data in plain text. Once the user has authenticated, to set the
            user, report the action result via API call or call
            'setAuthenticatedUser' from the client SDK.
        correlation_id:
          type: string
          description: >-
            Any ID that could help relate the action with external context or
            session
        transaction_data:
          type: object
          description: Transaction data-points given in the relevant action
          properties:
            amount:
              type: number
              description: >-
                The monetary amount of the transaction. The backend sanitizes
                this value with parseFloat; it must be strictly positive and ≤
                999,999,999.99
              exclusiveMinimum: 0
              maximum: 999999999.99
            currency:
              type: string
              description: The transaction currency (ISO-4217)
              example: USD
            reason:
              type: string
              description: The reason for the transaction
              minLength: 1
              maxLength: 200
            transactionDate:
              type: integer
              description: >-
                The transaction timestamp (Unix epoch in milliseconds or
                seconds). Must be a non-negative integer.
              minimum: 0
            payer:
              type: object
              description: The provided data points for the transaction payer
              properties:
                name:
                  type: string
                  description: Payer name
                  minLength: 1
                  maxLength: 100
                bankIdentifier:
                  type: string
                  description: Payer bank identifier
                  minLength: 1
                  maxLength: 40
                branchIdentifier:
                  type: string
                  description: Payer branch identifier
                  minLength: 1
                  maxLength: 40
                accountNumber:
                  type: string
                  description: Payer account number
                  minLength: 1
                  maxLength: 50
            payee:
              type: object
              description: The provided data points for the transaction payee
              properties:
                name:
                  type: string
                  description: Payee name
                  minLength: 1
                  maxLength: 100
                bankIdentifier:
                  type: string
                  description: Payee bank identifier
                  minLength: 1
                  maxLength: 40
                branchIdentifier:
                  type: string
                  description: Payee branch identifier
                  minLength: 1
                  maxLength: 40
                accountNumber:
                  type: string
                  description: Payee account number
                  minLength: 1
                  maxLength: 50
        custom_attributes:
          type: object
          description: >-
            Custom attributes add context to an action but must match the schema
            defined in the Portal. Invalid attributes are ignored.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
    actionResult:
      type: object
      required:
        - action_token
        - result
      properties:
        action_token:
          type: string
          description: The token return when the action event was reported
        result:
          type: string
          enum:
            - success
            - failure
            - incomplete
          description: The action result.
        user_id:
          type: string
          description: Opaque identifier of the user in your system.
        private_user_identifier:
          type: string
          description: >-
            Identifier containing sensitive user data. Mosaic will encrypt and
            securely store this data.
        challenge_type:
          type: string
          enum:
            - sms_otp
            - email_otp
            - totp
            - push_otp
            - voice_otp
            - idv
            - captcha
            - password
            - passkey
          description: >-
            Type of challenge used, in case a challenge was recommended for this
            action event
    authuser:
      type: object
      required:
        - action_token
        - user_id
      properties:
        user_id:
          type: string
          description: Opaque identifier of the user in your system.
        action_token:
          type: string
          description: The token return by the SDK when the action was reported.
    setAssignee:
      type: object
      properties:
        action_ids:
          type: array
          items:
            type: string
            description: List of action IDs
            example: ea49707f023f48d64a7a817a2e7a5ff4277281a8f8ac1848ccac407967d9d2ce
        assignee:
          type: string
          description: The email of the user to assign the actions to.
    recommendation_type:
      type: string
      description: Recommendation type
      enum:
        - CHALLENGE
        - DENY
        - ALLOW
        - TRUST
    result_type:
      type: string
      description: The outcome of the action.
      enum:
        - success
        - failure
        - incomplete
    challenge_type:
      type: string
      description: The type of challenge enforced for the reported action.
      enum:
        - email_otp
        - totp
        - push_otp
        - voice_otp
        - idv
        - captcha
        - invisible_captcha
        - password
        - passkey
    recommendation:
      description: Recommended way to handle the reported action
      type: object
      properties:
        type:
          $ref: '#/components/schemas/recommendation_type'
        result:
          $ref: '#/components/schemas/result_type'
        challenge_type:
          $ref: '#/components/schemas/challenge_type'
      required:
        - type
    risk_score:
      type: number
      description: Used to assess the risk level of the client action
      example: 73.2
      minimum: 0
      maximum: 100
    action_type:
      type: string
      example: login
      description: Type of client action this recommendation was issued for
    context:
      type: object
      description: Identifies the context in which the action occurred
      properties:
        action_id:
          type: string
          example: 885cd06b527a97498200560b67123fe221b5a39fd98d8d22cdb7ca8ec16ed62d
          description: Identifier of the client action
        action_type:
          $ref: '#/components/schemas/action_type'
        action_performed_at:
          type: number
          example: 1648028118123
          description: Unix epoch time in milliseconds the action event was reported
        device_timestamp:
          type: number
          example: 1648028107819
          description: >-
            Unix epoch timestamp (ms) from the device clock when the action is
            triggered via `triggerActionEvent()`. For backend-triggered actions,
            uses the server time (`Date.now()`). Used to correlate client and
            server events.
        client_id:
          type: string
          example: d152ddd.ece93f4.c2a3d12.riskid.security
          description: Identifies the client associated with the action
        application_id:
          type: string
          example: ece93f4
          description: Identifies the application associated with the action
        tenant_id:
          type: string
          example: c2a3d12
          description: Identifies your tenant within Transmit
        device_id:
          type: string
          example: >-
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIwZGE4ZmZjYy01NmE1LTRmMjgtYThkZi04NDY5MmYwYThmYTAiLCJ2ZXJzaW9uIjoxLCJpYXQiOjE2NTU3OTYzODQ1MzF9.TeGoqlCe_6eWzl9a3-vAumG4Xap8WjwsgcO2-DzGtLg
          description: >-
            Unique device identifier. On web, stored in the cookie. On mobile,
            uses platform-provided identifiers such as Android ID (hex string)
            or iOS `identifierForVendor` (alphanumeric). Not derived from IMEI
            or other hardware identifiers.
        correlation_id:
          type: string
          example: bcb934d8-89cb-433b-a4c7-b7d94299586b
          description: >-
            Any ID that could help relate the action with external context or
            session (if set via `triggerActionEvent()` SDK calls)
        device_fingerprint:
          type: string
          example: a3c8f5ea75cb65fcdc3d0452b985f957a46e24afdc912e93dac1e115ecf408e5
          description: Hash value on all the device data collected from the browser
        device_public_key:
          type: string
          example: 625ad815e47a1a05318c98185ff8cfb35fd706d836a1ad7459842f381929a8e3
          description: >-
            A unique and persistent identifier derived from cryptographic
            binding
        user_id:
          type: string
          example: 5c4afa75c
          description: >-
            Opaque identifier of the user in your system (if set via
            `setAuthenticatedUser()` or `init()` SDK calls)
        claimed_user_id:
          type: string
          example: 5c4afa75c
          description: >-
            User ID of the not yet authenticated user, used to enhance risk and
            trust assessments. Once the user is authenticated,
            drs.setAuthenticatedUser() should be called.
        location:
          type: string
          example: https://www.amazingapp.com/shops?target=1
          description: >-
            The place in the application in which the action was performed (such
            as the page URL)
        ip:
          type: string
          format: ipv4
          description: IP address
        ip_country:
          type: string
          example: UK
          description: Country code, specified in a two-letter format (ISO 3166-1 alpha-2)
        ip_region:
          type: string
          example: California
          description: Location region identified by IP address
        ip_location_city:
          type: string
          example: Los Angeles
          description: Location city identified by IP address
        ip_location_zip:
          type: string
          example: 92131
          description: Location zip code identified by IP address
        ip_location_longitude:
          type: string
          example: '-117.0903'
          description: Geolocation longitude identified by IP address
        ip_location_latitude:
          type: string
          example: '32.9167'
          description: Geolocation latitude identified by IP address
        ip_asn_name:
          type: string
          example: AS174 Cogent Communications
          description: >-
            Globally unique identifier that defines a group of one or more IP
            prefixes
        ip_asn_id:
          type: string
          example: AS174
          description: >-
            Globally unique identifier that defines a group of one or more IP
            prefixes
        ip_organization_name:
          type: string
          example: Cogent Communications
          description: IP organization name
        ip_organization_type:
          type: string
          example: isp
          description: Type of IP connection
        ip_location_timezone:
          type: string
          example: America/Los_Angeles
          description: Timezone location identified by IP address
        device_timezone:
          type: string
          example: America/Los_Angeles
          description: Timezone on device
        device_languages:
          description: Languages on device
          type: array
          items:
            type: string
          example:
            - en-US
            - en
        device_platform:
          type: string
          example: desktop
          description: Type of device platform
        os_name:
          type: string
          example: macOS
          description: Name of the operating system (e.g., macOS)
        os_version:
          type: string
          example: 14.1.0
          description: Operating system version
        browser_name:
          type: string
          example: Chrome
          description: Name of the browser (e.g., Chrome)
        browser_version:
          type: string
          example: '113'
          description: Browser major version
        user_agent:
          type: string
          example: >-
            Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like
            Gecko) Chrome/77.0.3865.90 Safari/537.36
          description: User agent
      required:
        - action_id
        - action_type
        - action_performed_at
        - device_id
        - device_fingerprint
        - application_id
    risk_signals:
      type: object
      description: Additional informative signals
      properties:
        device:
          type: object
          description: Device relevant signals
          properties:
            ram:
              type: number
              description: Device memory property, a floating point number.
            total_storage:
              type: number
              description: >-
                Device total storage, as received from the mobile native
                platform
            available_storage:
              type: number
              description: >-
                Device available storage, as received from the mobile native
                platform
            battery_level:
              type: number
              description: Device battery level, a floating point number
            device_power_state:
              type: string
              description: >-
                Indicates if the device is currently plugged into a power
                source.
            core_number:
              type: number
              description: Device core number
            graphic_card:
              type: string
              description: Device graphic card, as received from the web platform
            model:
              type: string
              description: Device model
            screen_width:
              type: number
              description: Device screen width in pixels
            screen_height:
              type: number
              description: Device screen height in pixels
            incognito:
              type: boolean
              description: Was the event performed using incognito browsing
            tampered:
              type: boolean
              description: Is the device tampered (root/jailbreak)
            emulated:
              type: boolean
              description: Is the device emulated
            spoofed:
              type: boolean
              description: Is the device spoofed
            tz_mismatch:
              type: boolean
              description: >-
                Was the event performed on a device with a timezone mismatching
                expected
            esim_usage:
              type: boolean
              description: Was the event performed using eSIM
            accept_languages:
              type: string
              description: >-
                Value of header 'accept-language' as it was at the action
                request
            mobile_network_code:
              type: string
              description: >-
                A string representation of the Device Carrier Mcc & Device
                Carrier Mnc
            screen_avail_width:
              type: number
              description: Number represets the available width size of the screen
            screen_avail_height:
              type: number
              description: Number represets the available height size of the screen
            font_count:
              type: number
              description: Number of font used in the website where the action occured
            cpu_arch:
              type: string
              description: A string represents the device cpu architecture
            device_navigator_useragent:
              type: string
              description: >-
                The user agent string from the device's browser navigator,
                providing details about the browser, operating system, and
                device.
            true_useragent:
              type: string
              description: >-
                The user agent string constructed by , providing details about
                the browser, operating system, and device.
            device_timezone_offset:
              type: number
              description: The time zone offset of the device used.
            summer_timezone_offset:
              type: number
              description: >-
                The device’s timezone offset in minutes from UTC during daylight
                saving time.
            winter_timezone_offset:
              type: number
              description: >-
                The device’s timezone offset in minutes from UTC during standard
                (non-daylight saving) time.
            device_name:
              type: string
              description: >-
                The device’s name as recorded on iOS, reflecting the user-set
                name.
        network:
          type: object
          description: Network relevant signals
          properties:
            vpn:
              type: boolean
              description: Was the event performed using VPN connection
            tor:
              type: boolean
              description: Was the event performed using Tor connection
            hosting:
              type: boolean
              description: Was the event performed using hosting connection
            proxy:
              type: boolean
              description: Was the event performed using proxy connection
            anonymizer:
              type: boolean
              description: Was the event performed using anonymized connection
            x_forwarded_for:
              description: >-
                The X-Forwarded-For header value, indicating the originating IP
                address of the client connecting to the web server through an
                HTTP proxy or load balancer.
              type: array
              items:
                type: string
        behavior:
          type: object
          description: User behavior relevant signals
          properties:
            typing_velocity:
              type: number
              example: 0.867
              description: Percentile of user typing speed
            movement_velocity:
              type: number
              example: 10
              description: Number of input event per second
            input_method:
              description: A list of used input methods
              type: array
              items:
                type: string
                description: Possible input methods
              example:
                - is_typing
                - is_paste
            no_user_interaction:
              type: boolean
              description: Was there any user interaction before clicks
            straight_line_ratio:
              type: number
              description: >-
                The ratio of straight-line movements out of all movements in the
                context of the user action. High ratios could suggest automated
                or scripted behavior.
            right_angels_ratio:
              type: number
              description: >-
                The ratio of right-angle movements out of all movements in the
                context of the user action. Unusually high ratios may indicate
                non-human interactions.
            minor_angels_ratio:
              type: number
              description: >-
                The ratio of minor-angle movements out of all movements in the
                context of the user action. High ratios might suggest careful,
                precise movements often seen in automated processes.
            movement_latency:
              type: number
              description: >-
                Measures the median delay of mouse or touchscreen movements,
                calculated as the time between each captured location change in
                milliseconds within the context of the user action
            corner_click:
              type: boolean
              description: >-
                Indicates whether there were multiple clicks on the corner of a
                button in the context of the user action. Corner clicks could
                indicate repetitive, automated clicking patterns.
        history:
          type: object
          description: User history relevant signals
          properties:
            ip_action_rate_60_sec:
              type: integer
              example: 1
              description: >-
                Number of actions originating from the same client IP address
                within 60 seconds prior to the current action
            user_action_rate_60_sec:
              type: integer
              example: 2
              description: >-
                Number of actions with the same userId that occurred within 60
                seconds prior to the current action
            device_action_rate_60_sec:
              type: integer
              example: 1
              description: >-
                Number of actions originating from the same deviceId within 60
                seconds prior to the current action
            ip_user_count_last_hour:
              type: integer
              example: 1
              description: >-
                Number of userId's associated with the IP address within an hour
                prior to the current event
            linking_user_to_device_count:
              type: integer
              example: 1
              description: Number of userId's associated with the current deviceId
            linking_device_to_users_count:
              type: integer
              example: 1
              description: Number of deviceId's associated with the current userId
            ip_device_count_last_hour:
              type: integer
              example: 1
              description: >-
                Number of deviceId's associated with the IP address within an
                hour prior to the current event
    reasons:
      type: array
      description: Explains the reasons for the recommendation
      items:
        type: string
        description: Risk signal identifiers
      example:
        - BEHAVIOR_BOT
        - IP_RISKY_REPUTATION
        - DEVICE_SUSPICIOUS_ATTRIBUTE
        - PROFILE_DEVICE_NEW
    transaction_data:
      type: object
      description: |
        Transaction data-points given in the relevant action, from the SDK
      properties:
        amount:
          type: integer
          description: The amount of the transaction
          example: 120
        currency:
          type: string
          description: The currency used for the transaction
          example: USD
        reason:
          type: string
          description: The reason for the transaction
        transactionDate:
          type: integer
          description: The transaction timestamp date
        payer:
          type: object
          description: The provided data points for the transaction payer
          properties:
            name:
              type: string
              description: Payer name
            bankIdentifier:
              type: string
              description: Payer bank identifier
            branchIdentifier:
              type: string
              description: Payer branch identifier
            accountNumber:
              type: string
              description: Payer account number
        payee:
          type: object
          description: The provided data points for the transaction payee
          properties:
            name:
              type: string
              description: Payee name
            bankIdentifier:
              type: string
              description: Payee bank identifier
            branchIdentifier:
              type: string
              description: Payee branch identifier
            accountNumber:
              type: string
              description: Payee account number
    threats:
      type: array
      description: List of all detected threats
      items:
        type: string
      example:
        - ACCOUNT_TAKEOVER
        - NEW_FRAUD_ACCOUNT
    preview_rule:
      type: object
      description: >
        Rule configured in preview mode that would have determined the result of
        this recommendation if all enabled rules were in production. This is
        returned to allow you to evaluate the impact of preview rules, and did
        not impact the actual outcome.
      properties:
        rule_name:
          type: string
          description: The name of the preview rule
        recommendation:
          type: string
          description: The recommendation of the preview rule
    recommendation_full:
      type: object
      description: Recommendation
      required:
        - id
        - issued_at
        - recommendation
        - risk_score
        - context
        - reasons
      properties:
        id:
          type: string
          example: 385cd06b527a974982e0560b67123fe2b1b5a39fd98d8d32cdbaca8ec16fd62d
          description: Recommendation identifier
        issued_at:
          type: number
          example: 1648028118123
          description: Unix epoch time in milliseconds this recommendation was issued at
        recommendation:
          $ref: '#/components/schemas/recommendation'
        risk_score:
          $ref: '#/components/schemas/risk_score'
        context:
          $ref: '#/components/schemas/context'
        risk_signals:
          $ref: '#/components/schemas/risk_signals'
        reasons:
          $ref: '#/components/schemas/reasons'
        transaction_data:
          $ref: '#/components/schemas/transaction_data'
        threats:
          $ref: '#/components/schemas/threats'
        preview_rule:
          $ref: '#/components/schemas/preview_rule'
  responses:
    trigger_action_received_and_stored:
      description: >-
        Trigger action has been received and stored successfully. The response
        also contains a recommendation, if requested.
      content:
        application/json:
          schema:
            type: object
            required:
              - action_token
            properties:
              action_token:
                type: string
              recommendation:
                $ref: '#/components/schemas/recommendation_full'
    actions_assignee_response:
      description: Assignee was updated for all requested actions.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                description: Defines if the operation was successful.
              affectedActionsCount:
                type: number
                example: 4
                description: The number of assigned actions.
    action_result_received_and_stored:
      description: Action result has been received and stored successfully.
    userauth_received_and_stored:
      description: User Auth has been received and stored successfully.
    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
