---
title: "Create a Transaction label"
method: POST
path: "/transactions/{transaction-id}/label"
tags: ["transactions"]
---

# Create a Transaction label

`POST /transactions/{transaction-id}/label`

## Request

- Base URL: `https://api.withpersona.com/api/v1`
- URL: `https://api.withpersona.com/api/v1/transactions/{transaction-id}/label`
- Auth: HTTP bearer

Create a new label for an existing Transaction.

## Path parameters

- `transaction-id` string, required

## Query parameters

- `include` string
- `fields` object

## Headers

- `Key-Inflection` 'camel' | 'kebab' | 'snake'
- `Idempotency-Key` string
- `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning).

## Request body

- object
  - `meta` TransactionsTransactionIdLabelPostRequestBodyContentApplicationJsonSchemaMeta
    - `label` string
    - `score` string
    - `model-version` string

## Response `200`

This endpoint returns a Transaction object and (optionally) its related objects in `included`.

- TransactionsCreateATransactionLabelResponse200
  - `data` Transaction, required
    - `id` string: Unique identifier for this Transaction. Starts with `txn_`.
    - `attributes` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionAttributes
      - `status` string
      - `reference-id` string, nullable
      - `fields` object: JSON key-value pairs of field name to field value. Exact schema depends on the configuration of the Transaction Type for this Transaction. Keys in `fields` are **not** key inflected.
      - `tags` string[]
      - `signals` object: Risk signals computed for this Transaction, keyed by signal name. Only present for Transactions whose Transaction Type has Sentinel enabled; signals appear once the Sentinel session has been processed. Specific keys are not enumerated in the public spec and may be added or removed over time. Contact your Persona account team for more information.
      - `created-at` string, date-time
      - `updated-at` string, date-time, nullable
    - `relationships` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationships
      - `reviewer` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsReviewer: The entity that reviewed the transaction
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsReviewerData
          - `type` string
          - `id` string
      - `transaction-label` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsTransactionLabel
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsTransactionLabelData
          - `type` 'transaction-label'
          - `id` string: Unique identifier for this Transaction Label. Starts with `txnl_`.
      - `transaction-type` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsTransactionType
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsTransactionTypeData
          - `type` 'transaction-type'
          - `id` string: Unique identifier for this Transaction Type. Starts with `txntp_`.
      - `related-objects` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsRelatedObjects: Objects involved in this Transaction's related Workflow runs. Will include a maximum of 100 related objects.
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsRelatedObjectsDataItems[]
          - `type` string
          - `id` string: Unique identifier for this object.
      - `sentinel-sessions` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsSentinelSessions: The Sentinel sessions that collected device and network data for this Transaction. Present on every Transaction; `data` is empty unless the Transaction has one or more Sentinel sessions.
        - `data` VerificationIncludedObjectsItemsDiscriminatorMappingTransactionRelationshipsSentinelSessionsDataItems[]
          - `type` 'sentinel-session'
          - `id` string: Unique identifier for this Sentinel Session. Starts with `snts_`.
  - `included` TransactionLabel[]
    - `type` 'transaction-label'
    - `id` string: Unique identifier for this Transaction Label. Starts with `txnl_`.
    - `attributes` TransactionLabelAttributes
      - `model-label` string
      - `model-version` string, nullable
      - `created-at` string, date-time
      - `updated-at` string, date-time, nullable

## Other responses

- `400`: The request was unacceptable, often due to invalid parameters.
- `401`: An invalid API key was provided.
- `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded.
- `404`: The requested resource doesn’t exist.
- `409`: The request conflicts with another request, often due to attempting to create a duplicate resource.
- `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter.
- `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests.

---

[API](https://skmtc.dev/withpersona/apis/withpersona-6.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-6/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-6/revisions/b2a170061bd9?raw)