View on GitHub

Wallet API

Description of REST API

Download this project as a .zip file Download this project as a tar.gz file

Basic info

Date&time

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Limits

Requests are limited by count per particular time. Information about those limits can be found in request's header:

X-RateLimit-Remaining: 98
X-RateLimit-Limit: 100

When you reach the requests call limit you will see:

HTTP/1.1 429 Client Error (429)

Http codes

Http code Description
200 Everything is ok
403 Forbidden, authorization failed
400 Bad request, user passed wrong input data
404 Url not found
429 Too many requests
500 Internal error

Obtaining a token

Sign-in to Wallet web app, go to User profile -> Auth token section. Here you can generate your token

Manual token manipulation (have to be signed-in):

Get token at https://www.walletapp.net/auth-token

Create token at https://www.walletapp.net/auth-token/create

Delete token at https://www.walletapp.net/auth-token/delete

Caution! Keep your token in secret. Everyone having your token could possibly change your data!

Authorization

There are two ways how to handle authorization.

Pass auth token as url param auth.

curl https://www.walletapp.net/api/v1/users?auth=TOKEN

By using BASIC authentication (user = auth, pass = TOKEN).

curl -u auth:TOKEN https://www.walletapp.net/api/v1/users

When the authorization fail, you will get following http code

HTTP/1.1 403 Forbidden

Users

Retrieves users

GET /api/v1/users

Response

[{
    "birth_year": 1900,
    "email": "muller10@gmail.com",
    "payment_plan": "INDIVIDUAL",
    "payment_period": "y",
    "licence_type": "paymill",
    "affiliate_id": "none",
    "last_web_access_at": "2014-04-17T09:52:02.939Z",
    "last_sync_at": "2014-02-17T11:22:03.129Z",
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "7e7e7387-fda1-4594-8dd0-9f1726113c45"
}]

Accounts

Retrieves all accounts

Request

GET /api/v1/user/:user_id/accounts

Response

[{
    "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
    "name": "My personal account",
    "gps": true,
    "init_amount": 0,
    "order": 0,
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "a48e9fca-1a21-48ae-8664-54f54db1f8a0"
}]

Save/create new account 

POST api/v1/user/:user_id/account/:account_id

Delete an account 

DELETE api/v1/user/:user_id/account/:account_id

Categories

Retrieves all user's categories

GET /api/v1/user/:user_id/categories

Response

[{
    "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
    "name": "Car",
    "color": "#8601B0",
    "icon_path": "ic_cat_0101_car.png",
    "icon_id": 15,
    "is_system_category": false,
    "default_type": "expense",
    "order": 4,
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "406cfd10-6a3a-4cb3-9c81-6de8e552a681"
}]

Currencies

Retrieves all user's currencies

GET /api/v1/user/:user_id/currencies

Response

[{
    "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
    "rate": 1,
    "is_referential": true,
    "name": "Czech Republic Koruna",
    "code": "CZK",
    "symbol": "CZK",
    "order": 0,
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "c8e54a22-81f9-4034-acd3-59003f004a29"
}]

Hashtags

Retrieve all user's hashtags or single hashtag

GET /api/v1/user/:user_id/hashtags

GET /api/v1/user/:user_id/hashtag/{hashtag_id}

Response

{
    "name": "name of hashtag",
    "id": "867f9c29-7b6e-4b1c-8d39-656cd5befa08"
}

Records

Retrieves all records in particular account

GET /api/v1/user/:user_id/account/:account_id/records

Response

[{
    "account_id": "a48e9fca-1a21-48ae-8664-54f54db1f8a0",
    "category_id": "a43e0592-bb0e-4fb1-b9d4-4899978562bd",
    "currency_id": "c8e54a22-81f9-4034-acd3-59003f004a29",
    "payment_type": "cash",
    "amount": 1,
    "record_type": "expense",
    "record_date": "2014-01-26T19:47:06.203Z",
    "note": "Holiday in US, ~~hid:b42ef64b-8c91-48e8-af0f-a0db85a2e5b1",
    "warranty_in_months": 12,
    "gps_latitude": 40.001312,
    "gps_longitude": 12.355275,
    "gps_accuracy": 20,
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "00ef6be1-2652-43d1-947a-4a8b74460902"
}]

Retrieves particular record by record id

GET /api/v1/record/:record_id

Reponse

{
    "account": {
        "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
        "name": "My personal account",
        "gps": true,
        "init_amount": 0,
        "order": 0,
        "created_at": "2014-01-12T13:28:39.279Z",
        "modified_at": "2014-04-25T19:50:18.878Z",
        "id": "a48e9fca-1a21-48ae-8664-54f54db1f8a0"
    },
    "category": {
        "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
        "name": "Food",
        "color": "#FF6B6B",
        "icon_path": "ic_cat_0301_eating_out.png",
        "icon_id": 9,
        "is_system_category": false,
        "default_type": "expense",
        "order": 17,
        "created_at": "2014-01-12T13:28:39.279Z",
        "modified_at": "2014-04-25T19:50:18.878Z",
        "id": "a43e0592-bb0e-4fb1-b9d4-4899978562bd"
    },
    "currency": {
        "user_id": "7e7e7387-fda1-4594-8dd0-9f1726113c45",
        "rate": 1,
        "is_referential": true,
        "name": "Czech Republic Koruna",
        "code": "CZK",
        "symbol": "CZK",
        "order": 0,
        "created_at": "2014-01-12T13:28:39.279Z",
        "modified_at": "2014-04-25T19:50:18.878Z",
        "id": "c8e54a22-81f9-4034-acd3-59003f004a29"
    },
    "payment_type": "cash",
    "amount": 1,
    "record_type": "expense",
    "record_date": "2014-01-26T19:47:06.203Z",
    "note": "My new car",
    "warranty_in_months": 0,
    "gps_latitude": 0,
    "gps_longitude": 0,
    "gps_accuracy": 0,
    "created_at": "2014-01-12T13:28:39.279Z",
    "modified_at": "2014-04-25T19:50:18.878Z",
    "id": "00ef6be1-2652-43d1-947a-4a8b74460902"
}

Search

GET api/v1/search/records?q=query&sort=sorting_attribute&order=[asc|desc]&page=number&per_page=number

Url params table

Keyword Default value Description
q None Query for search
sort date Attribute used for sorting. Possible values are: amount, record_date, payment_type, type, warranty, latitude, longitude
order asc asc=Ascending, desc=Descending
page 1 page number to retrieve
per_page 20 items per page

Query table

Keyword Possible values Operators Description
account account_id none
category category_id none
currency currency_id none
payment_type cash, debit_card, credit_card, transfer, voucher, mobile_payment, web_payment none
amount positive floating number <, >, <=, >=
type income, expense none
record_date unix timestamp in UTC <, >, <=, >=
note %
warranty positive integer <, >, <=, >=
latitude real number <, >, <=, >=
longitude real number <, >, <=, >=

Following example request searches for record with amount between 2000 exclusive and 10000 inclusive, taking only incomes, payment type is credit card and contains note starting by word Cars

http://wallet-test.herokuapp.com/api/v1/search/records?page=1&per_page=10&q=payment_type:credit_card+amount:>2000+amount:<=10000+type:income+note:Cars

Create new record(s)

Create or update one or more records. When record id is specified, record is updated, otherwise is created. Data has to be sent inside POST request in JSON format specified by table below. 

POST /api/v1/user/:user_id/records

Input (json)

Property Mandatory Description
id false Record id (when not specified, new record is created)
account_id or account_name* true the account
category_id or category_name* true the category
currency_id or currency_code* true the currency
amount true must be bigger than 0
record_type true possible values: income, expense
payment_type true possible values: cash, debit_card, credit_card, transfer, voucher, mobile_payment, web_payment
record_date true ex.: 2014-04-21T15:10:23Z
note false record note
warranty_in_month false the warranty in month.
gps_latitude false the gps latitude
gps_longitude false the gps longitude
gps_accuracy false the accuracy in meters

* object of this name must exist, otherwise error will be returned

Example

[{
    "payment_type":"credit_card", 
    "record_type":"income", 
    "record_date":"2014-04-20T20:10:15Z", 
    "amount":100, 
    "currency_code":"CZK", 
    "account_name":"My personal account", 
    "category_name":"Car"
}]

Response

{
    "error_objects":[{
        "record":{
            ...received_record_object...
        },
        "failed_property":"<name_of_property>",
        "description":"<problem_description>"
    }],
    "created_object_ids":[
        "<id_1>",
        "<id_2>",
        "<id_3>"
    ]
}

Example - successful response

{
    "error_objects":[],
    "created_object_ids":[
        "f25538f2-7d49-4e0c-9bfd-dd67c90be434"
    ]
}

Example - failed response (record_type wasn't set)

{
    "error_objects":[{
        "record":{
            "account_name":"My personal account",
            "category_name":"Car",
            "currency_code":"CZK",
            "amount":100.0,
            "record_date":"2014-04-20T20:10:15Z",
            "warranty_in_months":0,
        },
        "failed_property":"record_type"
    }],
    "created_object_ids":[]
}

When everything is ok, you will receive result object with empty error_objects array and non-empty array created_object_ids filled with ids of created objects in the same order, the objects where received.

There is a limit 10.000 objects per minute.