> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Fraud Labels for an event

> Submits labels for a single event, no more than 30 days old. The submission is processed synchronously — a `200`
response means the labels were stored (`status: applied`), or that the event already had them (`status:
unchanged`). A `422` with `status: rejected` means the labels were not stored; see `errors`.




## OpenAPI

````yaml post /labels
openapi: 3.1.1
info:
  title: Server API
  description: >
    Fingerprint Server API allows you to get, search, and update Events in a
    server environment. It can be used for data exports, decision-making, and
    data analysis scenarios.

    Server API is intended for server-side usage, it's not intended to be used
    from the client side, whether it's a browser or a mobile device.

    The API also supports collection of Automation Intelligence for requests to
    your server in edge, pre-origin, or middleware contexts.
  version: '4'
  contact:
    name: Fingerprint Support
    email: support@fingerprint.com
  license:
    name: MIT
    url: https://github.com/fingerprintjs/openapi/blob/main/LICENSE
servers:
  - url: https://api.fpjs.io/v4
    description: Global
  - url: https://eu.api.fpjs.io/v4
    description: EU
  - url: https://ap.api.fpjs.io/v4
    description: Asia (Mumbai)
security:
  - bearerAuth: []
tags:
  - name: Events
    description: |
      Get, update, or search for information about events.
  - name: Visitors
    description: |
      Delete visitor data.
  - name: Edge
    description: |
      Create events with the Automation Intelligence API.
  - name: Labels
    description: >
      Submit confirmed fraud and non-fraud outcomes for events to train your
      Fraud Score models.
paths:
  /labels:
    post:
      tags:
        - Labels
      summary: Submit Fraud Labels for an event
      description: >
        Submits labels for a single event, no more than 30 days old. The
        submission is processed synchronously — a `200`

        response means the labels were stored (`status: applied`), or that the
        event already had them (`status:

        unchanged`). A `422` with `status: rejected` means the labels were not
        stored; see `errors`.
      operationId: submitFraudLabels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelsRequest'
            examples:
              valid:
                summary: Example request
                value:
                  event_id: 1735401600000.AbCdEf
                  labels:
                    - label: non_fraud
                      state: false
                    - label: fake_account
                      state: true
      responses:
        '200':
          description: OK. The labels were stored, or the event already had them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
              examples:
                200-applied:
                  summary: Example response
                  value:
                    source_id: 1786370416667.4gsLK5
                    source_type: server_api
                    event_id: 1735401600000.AbCdEf
                    status: applied
        '400':
          description: >
            Bad request. The request payload is not valid: a required field is
            missing or mistyped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                400-bad-request:
                  summary: Error response when the request body is invalid.
                  value:
                    error:
                      code: request_cannot_be_parsed
                      message: request body is not valid
        '403':
          description: Forbidden. Access to this API is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                403-secret-api-key-required:
                  summary: Error response when the secret API key was not provided.
                  value:
                    error:
                      code: secret_api_key_required
                      message: secret API key in header is missing or empty
                403-secret-api-key-not-found:
                  summary: >-
                    Error response when the provided secret API key does not
                    exist.
                  value:
                    error:
                      code: secret_api_key_not_found
                      message: >-
                        no fingerprint workspace found for specified secret API
                        key
                403-feature-not-enabled:
                  summary: >-
                    Error response when Fraud Labels submission is not enabled
                    for the workspace.
                  value:
                    error:
                      code: feature_not_enabled
                      message: feature not enabled
        '413':
          description: Bad request. The request payload is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                '413':
                  summary: Payload too large error
                  value:
                    error:
                      code: payload_too_large
                      message: payload too large
        '422':
          description: >
            Unprocessable. The payload is well-formed, but the event can't be
            labelled (e.g. its `event_id` is too old or

            doesn't exist, a label appears more than once, or the requested
            labels conflict with the event's current

            ones). Nothing was stored: `status` is `rejected`, and `errors`
            describes why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
              examples:
                422-rejected:
                  summary: Response when the labels were rejected.
                  value:
                    source_id: 1786370416667.4gsLK5
                    source_type: server_api
                    event_id: 1735401600000.AbCdEf
                    status: rejected
                    errors:
                      - code: event_too_old
                        message: event is older than 30 days
        '429':
          description: Too Many Requests. The request is throttled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                429-too-many-requests-error:
                  summary: Too many requests error
                  value:
                    error:
                      code: too_many_requests
                      message: too many requests
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                500-error:
                  summary: Request failed
                  value:
                    error:
                      code: failed
                      message: internal server error
        '503':
          description: >
            Service Temporarily Unavailable. Nothing was stored; the request can
            be retried as is.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                503-service-temporarily-unavailable:
                  summary: Error response when the service is temporarily unavailable.
                  value:
                    error:
                      code: service_unavailable
                      message: service temporarily unavailable
components:
  schemas:
    LabelsRequest:
      type: object
      description: Submits labels for a single event, processed synchronously.
      additionalProperties: false
      required:
        - event_id
        - labels
      properties:
        event_id:
          type: string
          description: The event ID being labelled. Must be no more than 30 days old.
          examples:
            - 1735401600000.AbCdEf
        labels:
          type: array
          description: The list of labels to submit. A label may appear only once.
          minItems: 1
          items:
            $ref: '#/components/schemas/LabelsEventLabel'
    LabelsResponse:
      type: object
      description: The result of a synchronous label submission.
      additionalProperties: false
      required:
        - source_id
        - source_type
        - event_id
        - status
      properties:
        source_id:
          type: string
          description: The ID of this submission.
          examples:
            - 1786370416667.4gsLK5
        source_type:
          type: string
          description: The type of this submission.
          examples:
            - server_api
        event_id:
          type: string
          description: The event ID that was labelled.
          examples:
            - 1735401600000.AbCdEf
        status:
          $ref: '#/components/schemas/LabelsStatus'
        errors:
          type: array
          description: >-
            The reasons the labels were rejected. Omitted unless `status` is
            `rejected`.
          items:
            $ref: '#/components/schemas/LabelsEventError'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    LabelsEventLabel:
      type: object
      description: A single label to apply (or unset) on an event.
      additionalProperties: false
      required:
        - label
        - state
      properties:
        label:
          type: string
          description: The user-defined label slug.
          pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$
          maxLength: 64
          examples:
            - fake_account
        state:
          type: boolean
          description: >-
            The desired state of the label, `true` for the label is applied,
            `false` to unset it.
          examples:
            - true
    LabelsStatus:
      type: string
      enum:
        - applied
        - unchanged
        - rejected
      description: >
        The result of labelling the event:

        * `applied` - The labels were stored, changing the event's labelled
        state.

        * `unchanged` - The event's labelled state already matched every
        submitted label, nothing was changed.

        * `rejected` - The labels could not be stored, and the event's labelled
        state is unchanged. See `errors`.
      examples:
        - applied
    LabelsEventError:
      type: object
      description: >-
        A stable error code and message describing why a label submission was
        rejected.
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          examples:
            - invalid_event_id
        message:
          type: string
          examples:
            - event id is invalid
    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          examples:
            - Forbidden
    ErrorCode:
      type: string
      enum:
        - request_cannot_be_parsed
        - request_read_timeout
        - secret_api_key_required
        - secret_api_key_not_found
        - public_api_key_required
        - public_api_key_not_found
        - subscription_not_active
        - wrong_region
        - feature_not_enabled
        - visitor_not_found
        - too_many_requests
        - state_not_ready
        - failed
        - event_not_found
        - missing_module
        - payload_too_large
        - service_unavailable
        - ruleset_not_found
      description: >
        Error code:

        * `request_cannot_be_parsed` - The query parameters or JSON payload
        contains some errors
          that prevented us from parsing it (wrong type/surpassed limits).
        * `request_read_timeout` - The request body could not be read before the
        connection timed out.

        * `secret_api_key_required` - secret API key in header is missing or
        empty.

        * `secret_api_key_not_found` - No Fingerprint workspace found for
        specified secret API key.

        * `public_api_key_required` - public API key in header is missing or
        empty.

        * `public_api_key_not_found` - No Fingerprint workspace found for
        specified public API key.

        * `subscription_not_active` - Fingerprint workspace is not active.

        * `wrong_region` - Server and workspace region differ.

        * `feature_not_enabled` - This feature (for example, Delete API) is not
        enabled for your workspace.

        * `visitor_not_found` - The specified visitor ID was not found. It never
        existed or it may have already been deleted.

        * `too_many_requests` - The limit on secret API key requests per second
        has been exceeded.

        * `state_not_ready` - The event specified with event ID is
          not ready for updates yet. Try again.
          This error happens in rare cases when update API is called immediately
          after receiving the event ID on the client. In case you need to send
          information right away, we recommend using the JavaScript agent API instead.
        * `failed` - Internal server error.

        * `event_not_found` - The specified event ID was not found. It never
        existed, expired, or it has been deleted.

        * `missing_module` - The request is invalid because it is missing a
        required module.

        * `payload_too_large` - The request payload is too large and cannot be
        processed.

        * `service_unavailable` - The service was unable to process the request.

        * `ruleset_not_found` - The specified ruleset was not found. It never
        existed or it has been deleted.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: >-
        Add your Secret API Key to the Authorization header using the standard
        Bearer format: `Authorization: Bearer <secret_api_key>`

````