# Store a new currency

`POST /v1/currencies`

Creates a new currency. 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 currency information. See the model for the exact specifications.

Type: object

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

- `enabled` (optional)
  Type: boolean
  
  Defaults to true
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `primary` (optional)
  Type: boolean
  
  Make this currency the primary currency for the current administration. You can set this value to FALSE, in which case nothing will change to the primary currency. If you set it to TRUE, the current primary currency will no longer be the primary currency.
  
  Example:
  
  ```json
  true
  ```

- `code` (required)
  Type: string, string
  
  Example:
  
  ```json
  "AMS"
  ```

- `name` (required)
  Type: string, string
  
  Example:
  
  ```json
  "Ankh-Morpork dollar"
  ```

- `symbol` (required)
  Type: string, string
  
  Example:
  
  ```json
  "AM$"
  ```

- `decimal_places` (optional)
  Type: integer, int32
  
  Supports 0-16 decimals.
  
  Example:
  
  ```json
  2
  ```

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

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

Type: object

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

- `enabled` (optional)
  Type: boolean
  
  Defaults to true
  
  default: true
  
  Example:
  
  ```json
  true
  ```

- `primary` (optional)
  Type: boolean
  
  Make this currency the primary currency for the current administration. You can set this value to FALSE, in which case nothing will change to the primary currency. If you set it to TRUE, the current primary currency will no longer be the primary currency.
  
  Example:
  
  ```json
  true
  ```

- `code` (required)
  Type: string, string
  
  Example:
  
  ```json
  "AMS"
  ```

- `name` (required)
  Type: string, string
  
  Example:
  
  ```json
  "Ankh-Morpork dollar"
  ```

- `symbol` (required)
  Type: string, string
  
  Example:
  
  ```json
  "AM$"
  ```

- `decimal_places` (optional)
  Type: integer, int32
  
  Supports 0-16 decimals.
  
  Example:
  
  ```json
  2
  ```

Responses:

- 200: New currency stored, result in response.

Content type: application/vnd.api+json

Type: object

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

- `data` (required)
  Reference: [CurrencyRead](https://sourcey-firefly.pages.dev/api/models/currencyread/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/currencies' \
  -H 'X-Trace-Id: 40c71bbb-c676-4f24-83cf-cc725d7d7a00' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}'
```

### JavaScript

```javascript
const body = `{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}`;

const response = await fetch('https://firefly.example.com/api/v1/currencies', {
  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 = '''{
  "enabled": true,
  "primary": true,
  "code": "AMS",
  "name": "Ankh-Morpork dollar",
  "symbol": "AM$",
  "decimal_places": 2
}'''

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