# Create new account.

`POST /v1/accounts`

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

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 with the necessary account information or key=value pairs. See the model for the exact specifications.

Type: object

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

- `name` (required)
  Type: string, string
  
  Example:
  
  ```json
  "My checking account"
  ```

- `type` (required)
  Reference: [ShortAccountTypeProperty](https://sourcey-firefly.pages.dev/api/models/shortaccounttypeproperty/index.md); Type: string, string
  
  Can only be one one these account types. import, initial-balance and reconciliation cannot be set manually.
  
  enum: ["asset","expense","import","revenue","cash","liability","liabilities","initial-balance","reconciliation"]
  
  Example:
  
  ```json
  "asset"
  ```

- `iban` (optional)
  Type: string, iban; nullable
  
  Example:
  
  ```json
  "GB98MIDL07009312345678"
  ```

- `bic` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "BOFAUS3N"
  ```

- `account_number` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "7009312345678"
  ```

- `opening_balance` (optional)
  Type: string, amount
  
  Represents the opening balance, the initial amount this account holds.
  
  Example:
  
  ```json
  "-1012.12"
  ```

- `opening_balance_date` (optional)
  Type: string, date-time; nullable
  
  Represents the date of the opening balance.
  
  Example:
  
  ```json
  "2026-10-01T00:00:00+00:00"
  ```

- `virtual_balance` (optional)
  Type: string, amount
  
  Example:
  
  ```json
  "123.45"
  ```

- `currency_id` (optional)
  Type: string, string
  
  Use either currency_id or currency_code. Defaults to the user's financial administration's currency.
  
  Example:
  
  ```json
  "12"
  ```

- `currency_code` (optional)
  Type: string, string
  
  Use either currency_id or currency_code. Defaults to the user's financial administration's currency.
  
  Example:
  
  ```json
  "EUR"
  ```

- `active` (optional)
  Type: boolean
  
  If omitted, defaults to true.
  
  default: true
  
  Example:
  
  ```json
  false
  ```

- `order` (optional)
  Type: integer, int32
  
  Order of the account
  
  Example:
  
  ```json
  1
  ```

- `include_net_worth` (optional)
  Type: boolean
  
  If omitted, defaults to true.
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `account_role` (optional)
  Reference: [AccountRoleProperty](https://sourcey-firefly.pages.dev/api/models/accountroleproperty/index.md); Type: string, string; nullable
  
  Is only mandatory when the type is asset.
  
  enum: ["defaultAsset","sharedAsset","savingAsset","ccAsset","cashWalletAsset",null]
  
  Example:
  
  ```json
  "defaultAsset"
  ```

- `credit_card_type` (optional)
  Reference: [CreditCardTypeProperty](https://sourcey-firefly.pages.dev/api/models/creditcardtypeproperty/index.md); Type: string, string; nullable
  
  Mandatory when the account_role is ccAsset. Can only be monthlyFull or null.
  
  enum: ["monthlyFull",null]
  
  Example:
  
  ```json
  "monthlyFull"
  ```

- `monthly_payment_date` (optional)
  Type: string, date-time; nullable
  
  Mandatory when the account_role is ccAsset. Moment at which CC payment installments are asked for by the bank.
  
  Example:
  
  ```json
  "2026-10-01T00:00:00+00:00"
  ```

- `liability_type` (optional)
  Reference: [LiabilityTypeProperty](https://sourcey-firefly.pages.dev/api/models/liabilitytypeproperty/index.md); Type: string, string; nullable
  
  Mandatory when type is liability. Specifies the exact type.
  
  enum: ["loan","debt","mortgage",null]
  
  Example:
  
  ```json
  "loan"
  ```

- `liability_direction` (optional)
  Reference: [LiabilityDirectionProperty](https://sourcey-firefly.pages.dev/api/models/liabilitydirectionproperty/index.md); Type: string, string; nullable
  
  'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabilities.
  
  enum: ["credit","debit",null]
  
  Example:
  
  ```json
  "credit"
  ```

- `interest` (optional)
  Type: string, string; nullable
  
  Mandatory when type is liability. Interest percentage.
  
  default: "0"
  
  Example:
  
  ```json
  "5.3"
  ```

- `interest_period` (optional)
  Reference: [InterestPeriodProperty](https://sourcey-firefly.pages.dev/api/models/interestperiodproperty/index.md); Type: string, string; nullable
  
  Mandatory when type is liability. Period over which the interest is calculated.
  
  enum: ["daily","weekly","monthly","quarterly","half-year","yearly",null]
  
  Example:
  
  ```json
  "monthly"
  ```

- `notes` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "Some example notes"
  ```

- `latitude` (optional)
  Type: number, double; nullable
  
  Latitude of the accounts's location, if applicable. Can be used to draw a map.
  
  Example:
  
  ```json
  51.983333
  ```

- `longitude` (optional)
  Type: number, double; nullable
  
  Latitude of the accounts's location, if applicable. Can be used to draw a map.
  
  Example:
  
  ```json
  5.916667
  ```

- `zoom_level` (optional)
  Type: integer, int32; nullable
  
  Zoom level for the map, if drawn. This to set the box right. Unfortunately this is a proprietary value because each map provider has different zoom levels.
  
  Example:
  
  ```json
  6
  ```

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

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

Type: object

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

- `name` (required)
  Type: string, string
  
  Example:
  
  ```json
  "My checking account"
  ```

- `type` (required)
  Reference: [ShortAccountTypeProperty](https://sourcey-firefly.pages.dev/api/models/shortaccounttypeproperty/index.md); Type: string, string
  
  Can only be one one these account types. import, initial-balance and reconciliation cannot be set manually.
  
  enum: ["asset","expense","import","revenue","cash","liability","liabilities","initial-balance","reconciliation"]
  
  Example:
  
  ```json
  "asset"
  ```

- `iban` (optional)
  Type: string, iban; nullable
  
  Example:
  
  ```json
  "GB98MIDL07009312345678"
  ```

- `bic` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "BOFAUS3N"
  ```

- `account_number` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "7009312345678"
  ```

- `opening_balance` (optional)
  Type: string, amount
  
  Represents the opening balance, the initial amount this account holds.
  
  Example:
  
  ```json
  "-1012.12"
  ```

- `opening_balance_date` (optional)
  Type: string, date-time; nullable
  
  Represents the date of the opening balance.
  
  Example:
  
  ```json
  "2026-10-01T00:00:00+00:00"
  ```

- `virtual_balance` (optional)
  Type: string, amount
  
  Example:
  
  ```json
  "123.45"
  ```

- `currency_id` (optional)
  Type: string, string
  
  Use either currency_id or currency_code. Defaults to the user's financial administration's currency.
  
  Example:
  
  ```json
  "12"
  ```

- `currency_code` (optional)
  Type: string, string
  
  Use either currency_id or currency_code. Defaults to the user's financial administration's currency.
  
  Example:
  
  ```json
  "EUR"
  ```

- `active` (optional)
  Type: boolean
  
  If omitted, defaults to true.
  
  default: true
  
  Example:
  
  ```json
  false
  ```

- `order` (optional)
  Type: integer, int32
  
  Order of the account
  
  Example:
  
  ```json
  1
  ```

- `include_net_worth` (optional)
  Type: boolean
  
  If omitted, defaults to true.
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `account_role` (optional)
  Reference: [AccountRoleProperty](https://sourcey-firefly.pages.dev/api/models/accountroleproperty/index.md); Type: string, string; nullable
  
  Is only mandatory when the type is asset.
  
  enum: ["defaultAsset","sharedAsset","savingAsset","ccAsset","cashWalletAsset",null]
  
  Example:
  
  ```json
  "defaultAsset"
  ```

- `credit_card_type` (optional)
  Reference: [CreditCardTypeProperty](https://sourcey-firefly.pages.dev/api/models/creditcardtypeproperty/index.md); Type: string, string; nullable
  
  Mandatory when the account_role is ccAsset. Can only be monthlyFull or null.
  
  enum: ["monthlyFull",null]
  
  Example:
  
  ```json
  "monthlyFull"
  ```

- `monthly_payment_date` (optional)
  Type: string, date-time; nullable
  
  Mandatory when the account_role is ccAsset. Moment at which CC payment installments are asked for by the bank.
  
  Example:
  
  ```json
  "2026-10-01T00:00:00+00:00"
  ```

- `liability_type` (optional)
  Reference: [LiabilityTypeProperty](https://sourcey-firefly.pages.dev/api/models/liabilitytypeproperty/index.md); Type: string, string; nullable
  
  Mandatory when type is liability. Specifies the exact type.
  
  enum: ["loan","debt","mortgage",null]
  
  Example:
  
  ```json
  "loan"
  ```

- `liability_direction` (optional)
  Reference: [LiabilityDirectionProperty](https://sourcey-firefly.pages.dev/api/models/liabilitydirectionproperty/index.md); Type: string, string; nullable
  
  'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabilities.
  
  enum: ["credit","debit",null]
  
  Example:
  
  ```json
  "credit"
  ```

- `interest` (optional)
  Type: string, string; nullable
  
  Mandatory when type is liability. Interest percentage.
  
  default: "0"
  
  Example:
  
  ```json
  "5.3"
  ```

- `interest_period` (optional)
  Reference: [InterestPeriodProperty](https://sourcey-firefly.pages.dev/api/models/interestperiodproperty/index.md); Type: string, string; nullable
  
  Mandatory when type is liability. Period over which the interest is calculated.
  
  enum: ["daily","weekly","monthly","quarterly","half-year","yearly",null]
  
  Example:
  
  ```json
  "monthly"
  ```

- `notes` (optional)
  Type: string, string; nullable
  
  Example:
  
  ```json
  "Some example notes"
  ```

- `latitude` (optional)
  Type: number, double; nullable
  
  Latitude of the accounts's location, if applicable. Can be used to draw a map.
  
  Example:
  
  ```json
  51.983333
  ```

- `longitude` (optional)
  Type: number, double; nullable
  
  Latitude of the accounts's location, if applicable. Can be used to draw a map.
  
  Example:
  
  ```json
  5.916667
  ```

- `zoom_level` (optional)
  Type: integer, int32; nullable
  
  Zoom level for the map, if drawn. This to set the box right. Unfortunately this is a proprietary value because each map provider has different zoom levels.
  
  Example:
  
  ```json
  6
  ```

Responses:

- 200: New account stored, result in response.

Content type: application/vnd.api+json

Type: object

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

- `data` (required)
  Reference: [AccountRead](https://sourcey-firefly.pages.dev/api/models/accountread/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/accounts' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "My checking account",
  "type": "asset",
  "iban": "GB98MIDL07009312345678",
  "bic": "BOFAUS3N",
  "account_number": "7009312345678",
  "opening_balance": "-1012.12",
  "opening_balance_date": "2026-10-01T00:00:00+00:00",
  "virtual_balance": "123.45",
  "currency_id": "12",
  "currency_code": "EUR",
  "active": false,
  "order": 1,
  "include_net_worth": true,
  "account_role": "defaultAsset",
  "credit_card_type": "monthlyFull",
  "monthly_payment_date": "2026-10-01T00:00:00+00:00",
  "liability_type": "loan",
  "liability_direction": "credit",
  "interest": "5.3",
  "interest_period": "monthly",
  "notes": "Some example notes",
  "latitude": 51.983333,
  "longitude": 5.916667,
  "zoom_level": 6
}'
```

### JavaScript

```javascript
const body = `{
  "name": "My checking account",
  "type": "asset",
  "iban": "GB98MIDL07009312345678",
  "bic": "BOFAUS3N",
  "account_number": "7009312345678",
  "opening_balance": "-1012.12",
  "opening_balance_date": "2026-10-01T00:00:00+00:00",
  "virtual_balance": "123.45",
  "currency_id": "12",
  "currency_code": "EUR",
  "active": false,
  "order": 1,
  "include_net_worth": true,
  "account_role": "defaultAsset",
  "credit_card_type": "monthlyFull",
  "monthly_payment_date": "2026-10-01T00:00:00+00:00",
  "liability_type": "loan",
  "liability_direction": "credit",
  "interest": "5.3",
  "interest_period": "monthly",
  "notes": "Some example notes",
  "latitude": 51.983333,
  "longitude": 5.916667,
  "zoom_level": 6
}`;

const response = await fetch('https://firefly.example.com/api/v1/accounts', {
  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 = '''{
  "name": "My checking account",
  "type": "asset",
  "iban": "GB98MIDL07009312345678",
  "bic": "BOFAUS3N",
  "account_number": "7009312345678",
  "opening_balance": "-1012.12",
  "opening_balance_date": "2026-10-01T00:00:00+00:00",
  "virtual_balance": "123.45",
  "currency_id": "12",
  "currency_code": "EUR",
  "active": false,
  "order": 1,
  "include_net_worth": true,
  "account_role": "defaultAsset",
  "credit_card_type": "monthlyFull",
  "monthly_payment_date": "2026-10-01T00:00:00+00:00",
  "liability_type": "loan",
  "liability_direction": "credit",
  "interest": "5.3",
  "interest_period": "monthly",
  "notes": "Some example notes",
  "latitude": 51.983333,
  "longitude": 5.916667,
  "zoom_level": 6
}'''

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