Transaction links

Update an existing link between transactions.

PUT

https://firefly.example.com/api/v1/transaction-links/{id}

Used to update a single existing link.

curl -X PUT 'https://firefly.example.com/api/v1/transaction-links/123' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "link_type_id": "5",
  "link_type_name": "Is paid by",
  "inward_id": "131",
  "outward_id": "131",
  "notes": "Some example notes"
}'

const body = `{
  "link_type_id": "5",
  "link_type_name": "Is paid by",
  "inward_id": "131",
  "outward_id": "131",
  "notes": "Some example notes"
}`;

const response = await fetch('https://firefly.example.com/api/v1/transaction-links/123', {
  method: 'PUT',
  headers: {
    'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "link_type_id": "5",
  "link_type_name": "Is paid by",
  "inward_id": "131",
  "outward_id": "131",
  "notes": "Some example notes"
}'''

response = requests.put(
    'https://firefly.example.com/api/v1/transaction-links/123',
    data=body.encode('utf-8'),
    headers={
        'X-Trace-Id': '40c71bbb-c676-4f24-83cf-cc725d7d7a00',
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "link_type_id": "5",
  "link_type_name": "Is paid by",
  "inward_id": "131",
  "outward_id": "131",
  "notes": "Some example notes"
}

{
  "link_type_id": "5",
  "link_type_name": "Is paid by",
  "inward_id": "131",
  "outward_id": "131",
  "notes": "Some example notes"
}

{
  "data": {
    "type": "transactionLinks",
    "id": "2",
    "attributes": {
      "created_at": "2026-10-01T00:00:00+00:00",
      "updated_at": "2026-10-01T00:00:00+00:00",
      "inward_id": "131",
      "outward_id": "131",
      "notes": "Some example notes"
    },
    "links": {
      "0": {
        "rel": "self",
        "uri": "/OBJECTS/1"
      },
      "self": "https://demo.firefly-iii.org/api/v1/OBJECTS/1"
    }
  }
}

{
  "message": "Bad Request",
  "exception": "BadRequestHttpException"
}

{
  "message": "Unauthenticated",
  "exception": "AuthenticationException"
}

{
  "message": "Resource not found",
  "exception": "NotFoundHttpException"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "string"
    ],
    "force": [
      "string"
    ],
    "blocked": [
      "string"
    ],
    "field": [
      "string"
    ],
    "role": [
      "string"
    ],
    "blocked_code": [
      "string"
    ],
    "name": [
      "string"
    ],
    "type": [
      "string"
    ],
    "iban": [
      "string"
    ],
    "start": [
      "string"
    ],
    "end": [
      "string"
    ],
    "date": [
      "string"
    ]
  }
}

{
  "message": "Internal Exception",
  "exception": "InternalException"
}

Body

JSON array or form-data with updated link type information. See the model for the exact specifications.

application/json,application/x-www-form-urlencodedTransactionLinkUpdate

link_type_idstringwrite only

The link type ID to use. Use this field OR use the link_type_name field.

Example

link_type_namestringwrite only

The link type name to use. Use this field OR use the link_type_id field.

Example

Is paid by

inward_idstring

The inward transaction transaction_journal_id for the link. This becomes the 'is paid by' transaction of the set.

Example

outward_idstring

The outward transaction transaction_journal_id for the link. This becomes the 'pays for' transaction of the set.

Example

notesstring | null

Optional. Some notes. If you submit an empty string the current notes will be removed

Example

Some example notes

Parameters

idstringrequiredpath

The ID of the transaction link.

Response

200OKTransactionLinkSingle

Updated link type stored, result in response

Response fields application/vnd.api+json

dataTransactionLinkReadrequired

Show child attributes

typestringrequired

Immutable value

Example

transactionLinks

idstringrequired

Example

attributesTransactionLinkrequired

Show child attributes

created_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

updated_atstring<date-time>read only

Example

2026-10-01T00:00:00+00:00

inward_idstringrequired

The inward transaction transaction_journal_id for the link. This becomes the 'is paid by' transaction of the set.

Example

outward_idstringrequired

The outward transaction transaction_journal_id for the link. This becomes the 'pays for' transaction of the set.

Example

notesstring | null

Optional. Some notes.

Example

Some example notes

linksObjectLinkrequired

Show child attributes

0object

Show child attributes

relstring

Example

self

uristring

Example

/OBJECTS/1

selfstring<uri>

Example

https://demo.firefly-iii.org/api/v1/OBJECTS/1

400Bad RequestBadRequestResponse

Bad request

Response fields application/json

messagestring

Example

Bad Request

exceptionstring

Example

BadRequestHttpException

401UnauthorizedUnauthenticatedResponse

Unauthenticated

Response fields application/json

messagestring

Example

Unauthenticated

exceptionstring

Example

AuthenticationException

404Not FoundNotFoundResponse

Page not found

Response fields application/json

messagestring

Example

Resource not found

exceptionstring

Example

NotFoundHttpException

422Unprocessable EntityValidationErrorResponse

Validation error. The body will have the exact details.

Response fields application/json

messagestring

Example

The given data was invalid.

errorsobject

Show child attributes

emailArray<string>

forceArray<string>

blockedArray<string>

fieldArray<string>

roleArray<string>

blocked_codeArray<string>

nameArray<string>

typeArray<string>

ibanArray<string>

startArray<string>

endArray<string>

dateArray<string>

500Internal Server ErrorInternalExceptionResponse

Internal exception

Response fields application/json

messagestring

Example

Internal Exception

exceptionstring

Example

InternalException

Authorization

firefly_iii_authoauth2

OAuth2 authorization code flow. Create a client on your installation's /profile page; it authorizes at /oauth/authorize and issues tokens at /oauth/token there. The URLs below are the demo site's. How to use the API walks through it.

local_bearer_authhttp (bearer)

A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.