API v3 Beta
API v3 is currently in beta, please test it and let us know at firstname.lastname@example.org if you encounter an error or have any feedback for us. Thank you!
Given that we are currently at beta phase, we may introduce breaking changes to the API. Please take it into an account when implementing the API. Current stable version is API v2.
Once we announce the production version of API v3, we will mark the current API v2 as deprecated. We will continue to support the API v2 for at least 9 months after the announcement.
For the exhaustive list of changes against the API v2 please refer to the Changelog.
- All requests must be made via HTTPS.
- All endpoint URLs begin with
Most endpoints require Fakturoid account name as part of the request URL as a
For example if the account name is
applecorp, the URL will look like this:
List of all accounts for the current user can be obtained via current user endpoint.
All requests must have the
User-Agent header with the information about the name of your application and a technical contact email so we can contact you in case something goes rogue with your API integration.
User-Agent: YourAppName (email@example.com)
Requests without this header will receive
400 Bad Request error.
Unless stated otherwise, data (payload) is sent inside the request/response body as an UTF-8 encoded JSON string. Requests that send JSON payload need to have a header
Requests requesting a different type of response will receive
415 Unsupported Media Type error.
Fakturoid supports OAuth 2 protocol for authorization.
- Pagination is used on all endpoints that return a collection of records.
- There are 40 records per page.
- Next page can be requested by using the
2xx success HTTP status codes, the API may also return
4xx client and
5xx server error responses. In case of an error response body always contains a JSON with the description of the error.
Error response body can have two formats. The first one is always used for
422 Unprocessable Entity responses for invalid data and occasionally for other errors as well:
"name": ["can't be blank"]
errors key with a map of fields an their errors. The second format is used for all other errors and always contains
error key with a string code of the error and
error_description with a human readable description of the error:
"error_description": "Required header \"User-Agent\" is missing"
In case of maintenance, Fakturoid API will respond with status code
503 Temporarily Unavailable. Certain search endpoints may return the same status code when they are busy.
Defensive implementation of the API
Your application should always handle errors returned by the API. In cases of a maintenance or a
5xx server error, your application should retry the request later as Fakturoid does not store the requests for the later processing.
In case of
4xx client error, your application should display the error message to the user or your integration should be updated in a way to fix the error.
In case your IP address exceeds 200 requests per minute, the server will respond with the status code
429 Too Many Requests. Please wait a few seconds and retry the request.
If the Fakturoid account is blocked due to an overdue invoice from Fakturoid, the server will respond with status code
402 Payment Required and the response body will contain the list of unpaid invoices.