# Store a new transaction

`POST /v1/transactions`

Creates a new transaction. The data required can be submitted as a JSON body or as a list of parameters.

Authentication (security requirement alternatives):

```json
[
  {
    "firefly_iii_auth": []
  },
  {
    "local_bearer_auth": []
  }
]
```

- firefly_iii_auth: oauth2. 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](https://sourcey-firefly.pages.dev/how-to/firefly-iii/features/api/index.md) walks through it.
- local_bearer_auth: http (bearer). A Personal Access Token, sent as a bearer token. Create one on your installation under Options > Profile > OAuth > Personal Access Tokens.

Parameters:

- `X-Trace-Id` (header, string, uuid, optional) - Unique identifier associated with this request.
  Type: string, uuid
  
  Example:
  
  ```json
  "40c71bbb-c676-4f24-83cf-cc725d7d7a00"
  ```

Request body: application/json (required)

JSON array or key=value pairs with the necessary transaction information. See the model for the exact specifications.

Type: object

Schema: [TransactionStore](https://sourcey-firefly.pages.dev/api/models/transactionstore/index.md)

- `error_if_duplicate_hash` (optional)
  Type: boolean
  
  Break if the submitted transaction exists already.
  
  Example:
  
  ```json
  false
  ```

- `apply_rules` (optional)
  Type: boolean
  
  Whether or not to apply rules when submitting transaction.
  
  Example:
  
  ```json
  false
  ```

- `fire_webhooks` (optional)
  Type: boolean
  
  Whether or not to fire the webhooks that are related to this event.
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `group_title` (optional)
  Type: string, string; nullable
  
  Title of the transaction if it has been split in more than one piece. Empty otherwise.
  
  Example:
  
  ```json
  "Split transaction title."
  ```

- `transactions` (required)
  Type: array
  
  Items:
    Reference: [TransactionSplitStore](https://sourcey-firefly.pages.dev/api/models/transactionsplitstore/index.md); Type: object

Request body: application/x-www-form-urlencoded (required)

JSON array or key=value pairs with the necessary transaction information. See the model for the exact specifications.

Type: object

Schema: [TransactionStore](https://sourcey-firefly.pages.dev/api/models/transactionstore/index.md)

- `error_if_duplicate_hash` (optional)
  Type: boolean
  
  Break if the submitted transaction exists already.
  
  Example:
  
  ```json
  false
  ```

- `apply_rules` (optional)
  Type: boolean
  
  Whether or not to apply rules when submitting transaction.
  
  Example:
  
  ```json
  false
  ```

- `fire_webhooks` (optional)
  Type: boolean
  
  Whether or not to fire the webhooks that are related to this event.
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `group_title` (optional)
  Type: string, string; nullable
  
  Title of the transaction if it has been split in more than one piece. Empty otherwise.
  
  Example:
  
  ```json
  "Split transaction title."
  ```

- `transactions` (required)
  Type: array
  
  Items:
    Reference: [TransactionSplitStore](https://sourcey-firefly.pages.dev/api/models/transactionsplitstore/index.md); Type: object

Responses:

- 200: New transaction stored(s), result in response.

Content type: application/vnd.api+json

Type: object

Schema: [TransactionSingle](https://sourcey-firefly.pages.dev/api/models/transactionsingle/index.md)

- `data` (required)
  Reference: [TransactionRead](https://sourcey-firefly.pages.dev/api/models/transactionread/index.md); Type: object

- 400: Bad request

Content type: application/json

Type: object

Schema: [BadRequestResponse](https://sourcey-firefly.pages.dev/api/models/badrequestresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Bad Request"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "BadRequestHttpException"
  ```

- 401: Unauthenticated

Content type: application/json

Type: object

Schema: [UnauthenticatedResponse](https://sourcey-firefly.pages.dev/api/models/unauthenticatedresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Unauthenticated"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "AuthenticationException"
  ```

- 404: Page not found

Content type: application/json

Type: object

Schema: [NotFoundResponse](https://sourcey-firefly.pages.dev/api/models/notfoundresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Resource not found"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "NotFoundHttpException"
  ```

- 422: Validation error. The body will have the exact details.

Content type: application/json

Type: object

Schema: [ValidationErrorResponse](https://sourcey-firefly.pages.dev/api/models/validationerrorresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "The given data was invalid."
  ```

- `errors` (optional)
  Type: object
  
  - `email` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `force` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `blocked` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `field` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `role` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `blocked_code` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `name` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `type` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `iban` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `start` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `end` (optional)
    Type: array
    
    Items:
      Type: string, string
  
  - `date` (optional)
    Type: array
    
    Items:
      Type: string, string

- 500: Internal exception

Content type: application/json

Type: object

Schema: [InternalExceptionResponse](https://sourcey-firefly.pages.dev/api/models/internalexceptionresponse/index.md)

- `message` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "Internal Exception"
  ```

- `exception` (optional)
  Type: string, string
  
  Example:
  
  ```json
  "InternalException"
  ```

## Examples

### cURL

```bash
curl -X POST 'https://firefly.example.com/api/v1/transactions' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "error_if_duplicate_hash": false,
  "apply_rules": false,
  "fire_webhooks": true,
  "group_title": "Split transaction title.",
  "transactions": [
    {
      "type": "withdrawal",
      "date": "2026-10-01T00:00:00+00:00",
      "amount": "123.45",
      "description": "Vegetables",
      "order": 0,
      "currency_id": "12",
      "currency_code": "EUR",
      "foreign_amount": "123.45",
      "foreign_currency_id": "17",
      "foreign_currency_code": "USD",
      "budget_id": "4",
      "budget_name": "Groceries",
      "category_id": "43",
      "category_name": "Groceries",
      "source_id": "2",
      "source_name": "Checking account",
      "destination_id": "2",
      "destination_name": "Buy and Large",
      "reconciled": false,
      "piggy_bank_id": 0,
      "piggy_bank_name": "string",
      "bill_id": "112",
      "bill_name": "Monthly rent",
      "tags": null,
      "notes": "Some example notes",
      "internal_reference": "string",
      "external_id": "string",
      "external_url": "string",
      "sepa_cc": "string",
      "sepa_ct_op": "string",
      "sepa_ct_id": "string",
      "sepa_db": "string",
      "sepa_country": "string",
      "sepa_ep": "string",
      "sepa_ci": "string",
      "sepa_batch_id": "string",
      "interest_date": "2024-01-15T09:30:00Z",
      "book_date": "2024-01-15T09:30:00Z",
      "process_date": "2024-01-15T09:30:00Z",
      "due_date": "2024-01-15T09:30:00Z",
      "payment_date": "2024-01-15T09:30:00Z",
      "invoice_date": "2024-01-15T09:30:00Z"
    }
  ]
}'
```

### JavaScript

```javascript
const body = `{
  "error_if_duplicate_hash": false,
  "apply_rules": false,
  "fire_webhooks": true,
  "group_title": "Split transaction title.",
  "transactions": [
    {
      "type": "withdrawal",
      "date": "2026-10-01T00:00:00+00:00",
      "amount": "123.45",
      "description": "Vegetables",
      "order": 0,
      "currency_id": "12",
      "currency_code": "EUR",
      "foreign_amount": "123.45",
      "foreign_currency_id": "17",
      "foreign_currency_code": "USD",
      "budget_id": "4",
      "budget_name": "Groceries",
      "category_id": "43",
      "category_name": "Groceries",
      "source_id": "2",
      "source_name": "Checking account",
      "destination_id": "2",
      "destination_name": "Buy and Large",
      "reconciled": false,
      "piggy_bank_id": 0,
      "piggy_bank_name": "string",
      "bill_id": "112",
      "bill_name": "Monthly rent",
      "tags": null,
      "notes": "Some example notes",
      "internal_reference": "string",
      "external_id": "string",
      "external_url": "string",
      "sepa_cc": "string",
      "sepa_ct_op": "string",
      "sepa_ct_id": "string",
      "sepa_db": "string",
      "sepa_country": "string",
      "sepa_ep": "string",
      "sepa_ci": "string",
      "sepa_batch_id": "string",
      "interest_date": "2024-01-15T09:30:00Z",
      "book_date": "2024-01-15T09:30:00Z",
      "process_date": "2024-01-15T09:30:00Z",
      "due_date": "2024-01-15T09:30:00Z",
      "payment_date": "2024-01-15T09:30:00Z",
      "invoice_date": "2024-01-15T09:30:00Z"
    }
  ]
}`;

const response = await fetch('https://firefly.example.com/api/v1/transactions', {
  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();
```

### Python

```python
import requests

body = '''{
  "error_if_duplicate_hash": false,
  "apply_rules": false,
  "fire_webhooks": true,
  "group_title": "Split transaction title.",
  "transactions": [
    {
      "type": "withdrawal",
      "date": "2026-10-01T00:00:00+00:00",
      "amount": "123.45",
      "description": "Vegetables",
      "order": 0,
      "currency_id": "12",
      "currency_code": "EUR",
      "foreign_amount": "123.45",
      "foreign_currency_id": "17",
      "foreign_currency_code": "USD",
      "budget_id": "4",
      "budget_name": "Groceries",
      "category_id": "43",
      "category_name": "Groceries",
      "source_id": "2",
      "source_name": "Checking account",
      "destination_id": "2",
      "destination_name": "Buy and Large",
      "reconciled": false,
      "piggy_bank_id": 0,
      "piggy_bank_name": "string",
      "bill_id": "112",
      "bill_name": "Monthly rent",
      "tags": null,
      "notes": "Some example notes",
      "internal_reference": "string",
      "external_id": "string",
      "external_url": "string",
      "sepa_cc": "string",
      "sepa_ct_op": "string",
      "sepa_ct_id": "string",
      "sepa_db": "string",
      "sepa_country": "string",
      "sepa_ep": "string",
      "sepa_ci": "string",
      "sepa_batch_id": "string",
      "interest_date": "2024-01-15T09:30:00Z",
      "book_date": "2024-01-15T09:30:00Z",
      "process_date": "2024-01-15T09:30:00Z",
      "due_date": "2024-01-15T09:30:00Z",
      "payment_date": "2024-01-15T09:30:00Z",
      "invoice_date": "2024-01-15T09:30:00Z"
    }
  ]
}'''

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