Currency

Currency attributes represent quantities of money. They are similar to number attributes, allowing storing numbers with up to four decimal places of precision, but are presented differently in the UI with a currency symbol usually alongside.

Two examples of currency attributes are the funding_raised_usd attribute on the company object, and the value attribute on the deal object.

There is a currency_code property returned from the API on each attribute value, but please note that this is shared among all attribute values of the attribute; it is not possible to override currency for a particular record or entry.

Currency attributes can only be single-select.

Configuration

When creating currency attributes, you can specify two configuration properties:

• default_currency_code - The ISO4217 currency code e.g. USD or EUR. All values for the attribute inherit this value.
• display_type How the currency should be displayed across the app. See MDN for more details.

POST /v2/objects/:object/attributes HTTP/1.1
Authorization: Bearer <<oauth2>>
Content-Type: application/json

{
  "title": "Amount owed",
  "api_slug": "amount_owed",
  "type": "currency",
  "config": {
    "currency": {
      "default_currency_code": "USD",
      "display_type": "symbol"
    }
  }
}

Reading values

Currency attributes have two properties, currency_code (string) and currency_value (number). This attribute does not support null values.

{
  "active_from": "2023-04-03T15:21:06.447000000Z",
  "active_until": null,
  "created_by_actor": {...},
  "attribute_type": "currency",
  "currency_value": "499.00",
  "currency_code": "USD"
}

Writing values

Currency values can be written using floating point numbers. We accept values with up to 4 decimal places of precision. You do not need to pass floating point numbers explicitly; we will automatically convert integers to their floating point equivalents.

Where possible, Attio will convert strings into numbers. For example, the string "4.99" will be parsed as the float 4.99.

As currency attributes may only be single-select, you may always write values without wrapping in an array if preferred.

We also support writing currency values using an object with a single key, currency_value.

{
  "amount_owed": 4.99
}

{
  "amount_owed": "4.99"
}

{
  "amount_owed": [
    {
      "currency_value": "399.00"
    }
  ]
}

It is not possible to specify the currency_code since this is inherited from the attribute.

Filtering

Currency attribute values can be filtered by their value, using either JSON strings or numbers. You can filter for an exact value using the implicit syntax, or use the $eq,$gt,$gte,$lt,$lte operators with the explicit syntax.

{
  "filter": {
    "amount_owed": "399.00"
  }
}

{
  "filter": {
    "amount_owed": {
      "currency_value": {
        "$gte": 500
      }
    }
  }
}