Transaction links

Create a new link type

POST

https://firefly.example.com/api/v1/link-types

Creates a new link type. The data required can be submitted as a JSON body or as a list of parameters (in key=value pairs, like a webform).

curl -X POST 'https://firefly.example.com/api/v1/link-types' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "Paid",
  "inward": "is (partially) paid for by",
  "outward": "(partially) pays for"
}'

const body = `{
  "name": "Paid",
  "inward": "is (partially) paid for by",
  "outward": "(partially) pays for"
}`;

const response = await fetch('https://firefly.example.com/api/v1/link-types', {
  method: 'POST',
  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 = '''{
  "name": "Paid",
  "inward": "is (partially) paid for by",
  "outward": "(partially) pays for"
}'''

response = requests.post(
    'https://firefly.example.com/api/v1/link-types',
    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

{
  "name": "Paid",
  "inward": "is (partially) paid for by",
  "outward": "(partially) pays for"
}

{
  "name": "Paid",
  "inward": "is (partially) paid for by",
  "outward": "(partially) pays for"
}

{
  "data": {
    "type": "link_types",
    "id": "2",
    "attributes": {
      "name": "Paid",
      "inward": "is (partially) paid for by",
      "outward": "(partially) pays for",
      "editable": false
    },
    "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 with the necessary link type information or key=value pairs. See the model for the exact specifications.

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

namestringrequired

Example

Paid

inwardstringrequired

Example

is (partially) paid for by

outwardstringrequired

Example

(partially) pays for

Parameters

X-Trace-Idstring<uuid>header

Unique identifier associated with this request.

Response

200OKLinkTypeSingle

New link type stored, result in response.

Response fields application/vnd.api+json

dataLinkTypeReadrequired

Show child attributes

typestringrequired

Immutable value

Example

link_types

idstringrequired

Example

attributesLinkTyperequired

Show child attributes

namestringrequired

Example

Paid

inwardstringrequired

Example

is (partially) paid for by

outwardstringrequired

Example

(partially) pays for

editablebooleanread only

Example

false

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.