---
title: "Add relation to Transaction"
method: POST
path: "/transactions/{transaction-id}/add-relation"
tags: ["transactions"]
---

# Add relation to Transaction

`POST /transactions/{transaction-id}/add-relation`

## Request

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

Adds a relation between this Transaction and a target Account or Transaction using a relation schema key. No effect if the relation already exists.

## 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` TransactionsTransactionIdAddRelationPostRequestBodyContentApplicationJsonSchemaMeta, required
    - `relation-schema-key` string, required: Key of the relation schema to add. Valid keys are **defined by the relation schemas configured for your organization**, not by this API, so the accepted set varies per organization and per object type. A key outside that set is rejected with `No relation schema found for '<key>'`.
    - `target-object-id` string, required: ID of the target Account or Transaction to relate to.

## Response `200`

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

- TransactionsAddRelationResponse200
  - `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.
      - `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.
        - `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_`.

## 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-3.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-3/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-3/revisions/0a3310d5046f?raw)