Introduction
The roublez API and all its components are based on the REST standard. All resources have the same names that you will find in our application, so you can easily find your way around our API.
Fetching requests will always return a JSON-encoded response with a standard HTTP response code and updating requests will expect the data posted in an x-www-form-urlencoded format.
API under construction!
As of right now the API is not versioned and the endpoints are subject to change. You should avoid using the API in a production environment or anywhere a schema change would be undesired.
Any endpoint of the API uses the same base URL. In future versions of the API the base URL may change and incorporate an api version. For the time being make sure you use the following URL:
Authentication
Our API uses so called Bearer tokens to authenticate an incoming request. You can have multiple such API keys for different purposes and they can be managed in your account settings.
Keep the generated API keys safe and do not share them publicly. We will not be able to recover lost keys as we do not store them.
Authenticate your requests using the Authorization header setting the Bearer token, for instance Authorization: Bearer za67db89ansmdb67s89....
Every request should be performed as an HTTPS request as simple HTTP requests will be automatically redirected to their HTTPS counterpart. This redirection can be avoided when requesting over a secure connection.
Response errors
roublez uses normal HTTP status codes for all responses.
This means that you will receive a 2xx status code if everything went according to plan.
Client errors – such as missing or malformed parameters – will be responded to with a 4xx status code.
In case of an error on our side we will respond with a status code in the 5xx range.
Client errors in no way mean that something has gone wrong. For example, you will get a 404 Not Found error if you request a transaction that no longer exists because you deleted it.
A successful request with a status code in the 2xx range will always return the requested, updated or created data.
For 4xx and 5xx status codes you will receive a response error with the following attributes:
Attributes
type
string
The error type categorizes different errors into an error group for better comprehension.
message
string
The message attribute will contain a more human-readable description of the occurred error.
context
object
Every error response can come with a helpful context. The context is an object that can contain any kind of key-value pairs to help understand the error.
context.errors
validation errors
When the validation of the request fails, you will get this key inside the context object. You can find the detailed structure of the errors object below.
context.path
string
Very often, however not always, you will find this attribute in the context containing the requested path. This way you can easily detect malformed request URLs.
docs
string, url
If there is a specific documentation section or help article for the occurred error you will find the URL in this attribute.
Whenever request fails due to a validation error, the error response will contain a context.errors array.
This is an array of objects, each representing an input which failed the validation:
Validation Error
field
string
The name of the field.
messages
array
The list of all error messages for the field. In most cases this list will contain only one item. However, in some cases the api may return multiple different errors.
messages.*
string
A single error message
Rate limiting
roublez utilizes a very straightforward rate limiting method: Every user is allowed to make 60 requests per minute.
When reaching this limit you will receive a 429 Too Many Requests error on succeeding requests.
You can use the following response headers to inspect the current state of your rate limit:
Headers
X-RateLimit-Limit
integer
The amount of allowed requests per minute.
X-RateLimit-Remaining
integer
The amount of remaining requests before reaching the limit.
Those headers will be in the response for every API request. When reaching the limit and receiving the rate limit error you will find two additional headers in the response:
Headers
Retry-After
integer
The time in seconds to wait before retrying the request. After this amount of seconds the limit will be reset.
X-RateLimit-Reset
timestamp
The unix epoch timestamp of when the limit will be reset.
Expanding responses
Expanding responses is quite useful when you need more information about relationships of an object, but don't want to send multiple requests. If an attribute of a resource is marked as expandable, you can expand this attribute and load the information behind it.
You will have to add a query parameter called expand with the name of the attribute to expand.
You can expand multiple attributes in a request when passing multiple attributes as an array to the expand query parameter.
Query parameters
expand
string or array
This attribute must either be a string or an array of strings. Invalid values for the expand parameter will be ignored.
Pagination
Pagination is an essential part of requesting large amounts of objects.
Whenever you request from an endpoint that returns multiple objects of a resource the response will be paginated.
This means you receive only a "chunk" of the total amount.
If you want the next chunk you will have to request the next page of objects.
Don't worry, all metadata required for which URL to hit next is contained in the response.
The responses always contain meta and links fields with information about the paginator's state.
Every request that returns a paginated response will accept the following query parameters to modify the results:
Query parameters
limit
integer
This integer value specifies the size of a page. By default – when this parameter is omitted – the page size is set to 25. The limit parameter can have a value between 1 and 100. Larger page sizes are not allowed.
page
integer
This integer value specifies the page that should be fetched. If this field is ommited the first page will be requested.
Every request that returns a paginated response will have the following structure:
Attributes
data
array
The list of objects of the requested type. When you want to list all accounts the data attribute will contain a list of Account objects.
links
object
The links object contains all URLs required to navigate the pages.
links.first
string, url
The URL to the first page of the collection.
links.last
string, url
The URL to the last page of the collection.
links.prev
string, url
The URL to the previous page of the collection. This attribute will be null if the requested page is already the first page.
links.next
string, url
The URL to the next page of the collection. This attribute will be null if the requested page is already the last page.
meta
object
The meta object contains information to the paginator's state and collection size.
meta.current_page
integer
The requested page number.
meta.from
integer
The total-iterated number of the first item of the page. This value can be null if an invalid page has been specified.
meta.last_page
integer
The last page number.
meta.path
integer
The base path of the collection.
meta.per_page
integer
The amount of objects per page.
meta.to
integer
The total-iterated number of the last item of the page. This value can be null if an invalid page has been specified.
meta.total
integer
The total amount of objects in the collection.
User
The user resource represents the currently authenticated users – and that's you. Whenever you need information about your roublez account such as your name, email or the URL to your avatar image this resource got you covered.
The user object
Attributes
id
uid
Unique identifier of the user object.
name
string
Name of the user.
email
string
The email address of the user.
email_verified_at
iso8601
The datetime string of when the email was verified.
avatar
string, url
The URL to the profile image used. If the user has not uploaded a profile image a URL with a fallback placeholder image is being used.
two_factor_enabled
boolean
When the user has an active two factor authentication protection enabled this attribute will be true
theme
string, enum
The selected application theme. Possible values: automatic, light and dark.
locale
string, enum
The selected application language. Possible values: en and de.
currency
string, enum
The selected default currency. Possible values: eur and usd.
subscribed
boolean
Is set to true if the user has an active subscription.
created_at
iso8601
The datetime string of when the user was created.
updated_at
iso8601
The datetime string of when the user was last updated.
Retrieve the user
Retrieves the user information of the authenticated user.
Request body
Returns
Returns the authenticated User object. Since you are always authenticated when making a request this endpoint will always return the user information.
Update the user
Updates the user information.
Request body
name
string
The new name of the user.
theme
enum
The application theme to use. Possible values: automatic, light and dark.
locale
enum
The application language to use. Possible values: en and de.
currency
enum
The default currency to use. Possible values: eur and usd.
Returns
Returns the updated User object.
Accounts
The account resource represents an account that was created inside of roublez–not your roublez account. If you want to retrieve information such as your name you should use the endpoint to retrieve the authenticated user.
The account object
Attributes
id
uid
Unique identifier of the account object.
name
string
Name of the account.
bank
object
Contains information about the bank the account belongs to.
bank.bic
string
When set, you will find the bank identification code (BIC) of the account in this field.
bank.name
string
The name of the bank. This value can be null if the bank.bic value is not set, invalid or we simply don't know the institution.
currency
string, enum
The account's currency. Possible values: eur and usd.
archived
boolean
This field is true when the account has been archived.
created_at
iso8601
The datetime string of when the account was created.
updated_at
iso8601
The datetime string of when the account was last updated.
Retrieve an account
Retrieves the account details for a given account id.
Request body
Returns
Returns an Account object for a valid account id. Returns a 404 Not Found error if the account id is invalid or the account has been deleted.
List all accounts paginated
Retrieves a collection of your accounts. The accounts are sorted ascending by the account's created_at attribute.
Request body
Returns
Returns a paginated collection of the requested accounts.
Transactions
The transaction resource represents a transaction of an account.
The transaction object
Attributes
id
uid
Unique identifier of the transaction object.
name
string
The display name of the transaction.
description
string
The description of the budget.
amount
integer
Contains the booked amount of the transaction. The number is an integer with a decimal precision of 2 digits, so the value 640 represents $6.40 if the default currency is set to usd.
booking_date
date
The date string of when the transaction was booked. The date may be different from what the user entered when a custom timezone was used. The date is being stored in UTC.
booking_time
time
The time string of when the transaction was booked. The time may be different from what the user entered when a custom timezone was used. The time is being stored in UTC and can be null if no time was given.
ignore_in_analytics
boolean
Whether or not the transaction is being ignored in analytics.
category
uid
The category the transaction is assigned to.
account
uid or object
The account the transaction belongs to. This attribute can be expanded into an Account object.
transfer_account
uid or object
If the transaction is a transfer to another account this attribute will contain the UID of the target account – otherwise the attribute will be null. This attribute can be expanded into an Account object.
created_at
iso8601
The datetime string of when the transaction was created.
updated_at
iso8601
The datetime string of when the transaction was last updated.
Retrieve a transaction
Retrieves the transaction details for a given transaction id.
Request body
Returns
Returns a Transaction object for a valid transaction id. Returns a 404 Not Found error if the transaction id is invalid or the transaction has been deleted.
List all transactions paginated
Retrieves a collection of your transactions. The transactions are sorted ascending by the transaction's created_at attribute.
Request body
Returns
Returns a paginated collection of the requested transactions.
Budgets
The budget resource represents a created budget.
The budget object
Attributes
id
uid
Unique identifier of the budget object.
name
string
Name of the budget.
amount
integer
Contains the budget limit. The number is an integer with a decimal precision of 2 digits, so the value 35000 represents $350 if the default currency is set to usd.
interval
string, enum
The interval of the budget. Possible values: weekly, monthly, bimonthly, quarterly, semiannually and annually.
interval_condition
integer
The interval condition specifies at what point of time exactly the interval starts. For weekly it is the day of the week, for monthly and bimonthly the day of the month and for quarterly, semiannually and annually the starting month.
categories
array
The IDs of the categories the budget is associated with.
created_at
iso8601
The datetime string of when the budget was created.
updated_at
iso8601
The datetime string of when the budget was last updated.
Retrieve a budget
Retrieves the budget details for a given budget id.
Request body
Returns
Returns a Budget object for a valid budget id. Returns a 404 Not Found error if the budget id is invalid or the budget has been deleted.
List all budgets paginated
Retrieves a collection of your budgets. The budgets are sorted ascending by the budgets's created_at attribute.
Request body
Returns
Returns a paginated collection of the requested budgets.
Banks
roublez allows you to add your bank's bank identifier code (BIC) to an account. With this information we can add bank names and logos to your account and this ensures that we can provide you a better experience when using the application.
We try to keep our dataset of banks as current as possible, however it may be that your bank is not on our radar yet. But no worries, once we register a new BIC we do not know we will get notified and it should not take long until your bank is also available.
The bank object
Attributes
bic
string
The bank identifier code (BIC) that uniquely identifies a bank.
name
string
The name of the bank.
Retrieve a bank
Retrieves the bank details for a given bank identifier code (BIC).
Request body
Returns
Returns a Bank object for a valid and existing bank identifier code (BIC). Returns a 404 Not Found error if the BIC is invalid or the bank is not in our system yet.