Toshl Developer

Entries

Entries endpoint can be used to interact with users expenses and incomes.

Expenses have a negative prefix, incomes don’t have a prefix. Every entry is part of an account, is in one category, can have tags, can be part of a repeat, can be part of a transaction and can include images.

An entry is repeating if it includes the repeat object. Repeat parameters start, end, frequency, interval, count and byday are used according to RFC 5545 RRULE.

A transaction is a transfer of funds from one account to the other. An entry is part of transaction if it includes the transation object.

If you try edit an entry that is part of a transaction, the server will automatically update the companion entry.

Note: Be advised that only pro accounts can upload entry images. If a user with a free account tries to add an image, a 403 (Forbidden) error will be returned and the image will be discarded.

Resource representation

{
  "id": "42",
  "amount": -13.37,
  "currency": {
    "code": "USD",
    "rate": 1,
    "fixed": false
  },
  "date": "2012-09-04",
  "desc": "Entry description",
  "account": "45",
  "category": "42",
  "tags": ["42", "43"],
  "location": {
    "id": "44",
    "latitude": 46.051426,
    "longitude": 14.505966
  },
  "modified": "2012-09-04T13:55:15Z",
  "repeat": {
    "id": "41",
    "frequency": "monthly",
    "interval": 1,
    "start": "2012-09-04",
    "count": 10,
    "iteration": 1,
    "template": true
  },
  "transaction": {
    "id": "43",
    "account": "43",
    "currency": {
      "code": "USD",
      "rate": 1,
      "fixed": false
    }
  },
  "images": [{
    "id": "43",
    "path": "https://img.toshl.com/12/1404134603-ab820800-954f-46a7-95ff-fee7d961b31f/",
    "status": "uploaded"
  }],
  "reminders": [{
    "period": "week",
    "number": 2,
    "at": "11:25"
  }],
  "completed": false
}

Properties

id
readonly
string

Entry id.

amount
read, write
number

Entry amount.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
currency
read, write
object

Currency object

code
read, write
string

Entry currency code.

Regex: [A-Z0-9_]{2,10}
rate
read, write
number

Entry exchange rate calculated according to entry account currency.

Minimum: > 0
main_rate
readonly
number

Entry exchange rate main currency calculated according to entry main currency.

fixed
read, write
boolean

If set to true, the exchange rate is fixed.

Default value: false
date
read, write
string

Entry purchase date in YYYY-MM-DD format.

Format: date
desc
read, write
string

Entry description.

Max length: 3072
account
read, write
string

Entry account id.

category
read, write
string

Entry category id.

tags
read, write
array

An array of tag ids.

location
read, write
object

Entry location object.

id
read, write
string

Location id. This is the internal Toshl id, not the Foursquare venue id. Not set if user did not select a location.

venue_id
read, write
string

Foursquare venue id. Not set if user did not select a location.

latitude *
read, write
number

Location latitude.

longitude *
read, write
number

Location longitude.

created
readonly
string

Specifies when the entry was created.

Format: date-time
modified
readonly
string

Specifies when the entry was last modified.

repeat
read, write
object

A repeat object.

id
readonly
string

Repeat id.

start *
read, write
string

Repeat start date.

Format: date
end
read, write
string

Repeat end date. If end date is not specified the end parameter is omitted. count can be specified instead of end.

Format: date
template_start
readonly
string

Template start date. Only present if entry is a repeat template.

Format: date
template_end
readonly
string

Template end date. Only present if entry is a repeat template.

Format: date
frequency *
read, write
string

Repeat frequency.

Possible values: daily, weekly, monthly, yearly
interval *
read, write
integer

Repeat interval. For example: repeating every two months -> frequency: monthly, interval: 2.

Minimum: >= 1
Maximum: =< 255
count
read, write
integer

How many times to repeat entry.

Minimum: >= 1
byday
read, write
string

A comma separated list of weekdays (MO,TU..). Each weekday can have be preceded by a positive or negative number (1MO - 1st monday of the month/year, -1MO - last monday of the month/year).

bymonthday
read, write
string

A comma separated list of month days (1-31). Each month day can have a plus(+) or minus(-) prefix.

bysetpos
read, write
string

A comma separater list of the nth occurance within bymonthday. If you wish to set a repeat to occur on the last day of the month, set frequency to monthly, bymonthday to 28,29,30,31 and bysetpos to -1.

iteration
readonly
integer

Repeat iteration number. First entry in the repeat has iteration=0.

Minimum: >= 0
template
readonly
boolean

Set to true if this entry is a template for all future repeating entries in this repeat.

entries
read, write
array

List of entry ids that were used to create the repeat (used only for confirming detected repeats).

type
read, write
string

Repeat type.

Possible values: automatic, confirm, confirmed
status
read, write
string

Repeat status.

Possible values: ok, missing_entries
transaction
read, write
object

A transaction object.

id
read, write
string

Companion entry id.

amount
read, write
number

Transaction amount.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
account *
read, write
string

Companion entry account.

currency *
read, write
object

Companion entry currency object

code
read, write
string

Entry currency code.

Regex: [A-Z0-9_]{2,10}
rate
read, write
number

Entry exchange rate calculated according to entry account currency.

Minimum: > 0
main_rate
readonly
number

Entry exchange rate main currency calculated according to entry main currency.

fixed
read, write
boolean

If set to true, the exchange rate is fixed.

Default value: false
images
read, write
array

List of entry images. Each entry can have up to 4 images.

Maximum items: 4
id
read, write
string

Image id.

path
readonly
string

Path to image. Append thumb.jpg (width 640px) or full.jpg to path to get different variants of the image.

filename
readonly
string

Name of the attachment file. Use it together with path to retrieve the attachment.

type
readonly
string

Attachment type can be either image or pdf.

status
readonly
string

Image status.

Possible values: new, uploaded, error, deleting
reminders
read, write
array

List of entry reminders. Each entry can have up to 5 reminder. List is returned sorted by period and number.

Maximum items: 5
period
read, write
string

Reminder period

Possible values: day, week, month, year
number
read, write
integer

The number of periods before entry date -> 2 weeks before date: period = week, number = 2

Minimum: >= 0
Maximum: =< 255
at
read, write
string

Time of day for the reminder to fire in HH:mm:ss format.

Format: time
import
read, write
object

If entry was imported via a bank import (file or bank sync) this object is returned.

id
read, write
string

File import id

connection
read, write
string

Bank connection id which is responsible for the entry import.

memo
read, write
string

Memo provided by import

payee
read, write
string

Payee provided by import

pending
read, write
boolean

true if transaction is pending.

review
read, write
object

If entry is linked to a review (subject, match or resulting entry), this object is returned

id
read, write
string

Review id

type
read, write
string
Possible values: expense, income, transfer, repeat
completed
read, write
boolean

If review has already been completed.

settle
read, write
object

If this entry is part of the settle made automatically, then settle object is returned.

id
read, write
string

Account id with settle

split
read, write
object

If entry was created by splitting up another, this object is returned.

parent
read, write
string

Link to parent that was used to create this split entry.

children
read, write
array

Array of entry ids that have the same parent.

completed
read, write
boolean

If an entry has a reminder, this field indicates if the bill has been paid or not. Once it has reminders for this entry no longer fire.

deleted
readonly
boolean

Is object deleted.

extra
read, write
object

A custom JSON object that you can use to extend Toshl API. Whatever you save into this field you will get back whenever you fetch it later.

* denotes required field/parameter.