Visma e-conomic OpenAPI Journals (16.0.1)
Click to see changelog.
| Version | Description | Date |
|---|---|---|
| 16.0.1 | draft-entries Added error code JournalEntryVoucherNumberCannotBeGenerated (400), returned when no unused voucher number can be generated for the journal. This case previously returned 500. A POST without voucherNumber on a journal whose next voucher number is above its maximum still returns JournalEntryVoucherNumberNotWithinBoundaries, but no longer advances the journal's next voucher number. | October, 2026 |
| 16.0.0 | draft-entries Documentation correction: entryNumber is no longer marked read-only, so it is shown in the PUT request documentation. The number is assigned when the entry is created and must be supplied when updating an entry. No behavioural change. | September, 2026 |
| 15.0.1 | Documentation only: the deprecated booking endpoints are now listed in their own DraftEntriesDeprecated section under Under deprecation, instead of linking to the live draft-entries section. No behavioural change. | September, 2026 |
| 15.0.0 | draft-entries voucherNumber is now optional on POST — when omitted, the server generates a unique voucher number for the journal. PUT requests still require voucherNumber. | May, 2026 |
| 14.0.1 | journals Added name length validation (max 50 characters) for journal Name on POST and PUT. Requests with a longer name will receive a validation error instead of a database error. | February, 2026 |
| 14.0.0 | journals Added entryTypeRestrictedTo option. Journals can now be restricted to only accept specific entry types or all entry types. | December, 2025 |
| 13.0.1 | draft-entries Removed validation of accountNumber for customerPayments. The accountNumber is now automatically derived from the customer's group and is not validated when provided in the request. | October, 2025 |
| 12.0.2 | draft-entries and accruals now references their own set of error codes | August, 2025 |
| 12.0.1 | journals Updated description of Data | August, 2025 |
| 12.0.0 | journals Removed Type field from Journal | June, 2025 |
| 11.1.1 | draft-entries Removed SupplierPaymentType 14 (EntryOnly) from accpeted types as it's not supported. | May, 2025 |
| 11.1.0 | 1. JournalBooking Added new endpoint to book specific journal entries. | Marts, 2025 |
| 11.0.6 | draft-entries Fixed an issue where ProjectNumber and CostTypeNumber was ignored on some POST requests. | Marts, 2025 |
| 11.0.5 | 1. draft-entries Updated voucher number validation to allow voucher number = 0 2. draft-entries Fixed issue with POST /bulk where it would incorrectly return a 404 error | Marts, 2025 |
| 11.0.4 | draft-entries Updated voucher number validation to ensure values are always below 999999999 | February, 2025 |
| 11.0.3 | 1. journals Fixed sorting on number property 2. journals Fixed issue on /paged where pagesize query parameter was ignored 3. journals Fixed issue where cursor query property was ignored. 4. draft-entries Fixed default sorting on /paged to be ascending. 5. draft-entries DraftEntry Bulk POST and PUT will now run revert all changes if one entry fails. 6. draft-entries Fixed issue where creating new draft entry with invalid journal number returned the wrong error 7. draft-entries Supplier payment details will only be included if entryTypeNumber is 3 | January, 2025 |
| 11.0.2 | draft-entries Fixed an issue with SupplierPaymentType validation | December, 2024 |
| 11.0.1 | draft-entries Fixed an issue where editing an entry with SupplierPaymentType -1 (None) was not possible. Updated documentation to show available options for SupplierPaymentType | November, 2024 |
| 11.0.0 | 1. draft-entries Fixed an issue where projectId was not persisted when part of a draft entry with entryTypeNumber 5.2. draft-entries Fixed issue with wrongly validating supplierPayment properties. 3. Deprecating isCredit property for DraftEntry model, so this prperty is no longer availabe for CRUD operations | November, 2024 |
| 10.0.0 | draft-entries Added Payment details properties to Supplier invoices, for GET, PUT and POST | October, 2024 |
| 9.0.0 | Dimensions deprecated. Please use Dimensions API instead. | October, 2024 |
| 8.0.0 | Updated PUT endpoint for journals to no longer use journalNumber in path. draft-entries Exchange rate can now be left out (or null) when creating and updating draft entries. A default exchange rate will be set based on entry date and currency | October, 2024 |
| 7.0.0 | draft-entries Filtering by AccountNumber has been fixed. Additionally EntryNumber, JournalNumber, AccountNumber, StartDate, EndDate are now required | October, 2024 |
| 6.0.0 | draft-entries Added correct error code for trying to change journal number through an update. Updated PUT endpoint for draft-entries to no longer use draftEntryNumber in path. Added list of possible error codes for journals | July, 2024 |
| 5.2.0 | draft-entries endpoints added for managing accruals on draft entries | July, 2024 |
| 5.1.1 | draft-entries Added extra error handling | July, 2024 |
| 5.1.0 | Added /delete/[journalNumber] endpoint on draft-entries to delete all draft entries within a journal | July, 2024 |
| 5.0.0 | 1. The Name property is now required on journals. 2. JournalNumber and VoucherNumber is now required on draft-entries. 3. Sorting disabled on draft-entries for the following properties: Date, AccountNumber, VatCode, Amount, Currency, ContraAccountNumber, ContraVatCode, Text, ProjectNumber, CostTypeNumber, SupplierNumber. 4. Filtering disabled on draft-entries for the following properties: VatCode, Amount, ContraVatCode, Text CostTypeNumber. 5. Sorting disabled on journals for the following properties: BalancingBehavior, AutoApprove, Type, IsStandingJournal, RequireAdminApproval, LockVatCodes, NextVoucherNumber, MinimumVoucherNumber, MaximumVoucherNumber, CustomerContraAccount, SupplierContraAccount, CustomerPaymentText, SupplierPaymentText, Name, Priority, AllowPartialBooking, RequireBalancePerVoucherId, RepeatText, PaymentMessageText, DefaultDepartment. 6. Filtering disabled on journals for the following properties: AutoApprove, RequireAdminApproval, LockVatCodes, NextVoucherNumber, MinimumVoucherNumber MaximumVoucherNumber, SupplierContraAccount, CustomerContraAccount, CustomerPaumentText, SupplierPaymentText, Name, Priority, AllowPartialBooking, RequireBalancePerVoucherId, RepeatText, PaymentMessageText, DefaultDepartment. | July, 2024 |
| 4.0.0 | Added the ObjectVersion property to draft-entries and draft-entries/dimensions. OperationId updated for POST, Bulk POST, PUT and Bulk PUT in draft-entries. OperationId updated for PUT, GET Count in draft-entries/dimensions. OperationId updated for POST, PUT, DELETE, GET All Cursor, GET All Paged in journals | June, 2024 |
| 3.2.0 | draft-entries /count endpoint added | 07/05/2024 |
| 3.1.1 | Description updated. | 07/05/2024 |
| 3.1.0 | journals Added GET, POST, PUT and DELETE endpoints for managing journals | 01/05/2024 |
| 3.0.0 | entries/booked Moved to /booked-entries/.\ Booking of journals has moved to journals/[id]/book.\ draft-entries endpoint added | 01/04/2024 |
| 2.0.0 | entries/booked CustomerNumber added. | 13/02/2024 |
| 1.1.2 | Description updated. | 06/02/2024 |
| 1.1.1 | Fixed response type in documentation for entries/draft/book and entries/draft/bookwithdateinterval endpoints. | 05/02/2024 |
| 1.1.0 | entries/draft/book and entries/draft/bookwithdateinterval endpoints added. | 31/01/2024 |
| 1.0.0 | entries/booked endpoints added. | 02/10/2023 |
Create tokens as instructed here and then add these three headers to your requests:
| Header | Value | What is this? |
|---|---|---|
| X-AppSecretToken | YOUR_PRIVATE_TOKEN | This identifies your app. This is your secret token. Try using the value demo. |
| X-AgreementGrantToken | YOUR_AGREEMENT_GRANT_TOKEN | This identifies the grant issued by an agreement, to allow your app to access the agreements data. Try using the value demo. |
| Content-Type | application/json | We’re a JSON based API. This tells us that you agree with us on using JSON. |
Optional headers:
| Header | Value | What is this? |
|---|---|---|
| Idempotency-Key | YOUR_IDEMPOTENCY_KEY | This represents your own unique idempotency key. Enables you to make use of our Idempotency Tokens feature. You can't use this feature with GET requests. |
Welcome to the Visma e-conomic OpenAPI documentation!
The e-conomic API is a document-based JSON REST API.
For more in-depth information about e-conomic itself, please have a look at the e-copedia http://wiki.e-conomic.dk.
- Generating a client can easily be done using tools like swagger-codegen or others that work with OpenAPI Specification specs.
API releases are versioned using a three-part versioning scheme: {major version}.{minor version}.{patch version}.
We broadly follow Semantic Versioning principles when versioning the API. The major version number is incremented when a breaking change occurs.
The format is:
/{resource-api}/v{major version}.{minor version}.{patch version}/{resource-name}
Each value of the above are integers and you should configure the specific version in each API call.
An example could be: /subscriptionsapi/v1.0.0/subscriptions
To track the changes of versions, please see our changelog.
We reserve the right to deprecate versions at intervals since this allows for moving into a friendly environment for you faster.
If you wish to try out the API before registering a developer agreement, you can do this by using the demo agreement, which mimics the authentication flow you will have to use when you create your app. All you have to do is specify HTTP header tokens X-AgreementGrantToken: demo and X-AppSecretToken: demo. Note however that you can only do GET requests with the demo agreement. If you want full access to our API's, you will need to register.
Our data is exposed as collections of items. Each item has many properties, with one property as a unique identifier, usually called number or id. You can always get a single item if you already know the unique identifier. In case the unique identifier is not known, you can always search the collection and retrieve an array of items that satisfy the search criteria, or retrieve only the count of items that satisfy the search criteria. When you search for items in a collection, you can always use filtering, sorting and pagination. When it comes to pagination, we offer two distinct approaches available on separate endpoints. You can read more about filtering, sorting and pagination in the following sections.
Filtering is enabled on all collection endpoints but not on all properties.
Filtering on collections can be done using the query string parameter filter. A filter is made up of a set of predicates and follows a syntax inspired by mongoDB. A predicate is made up of a property name, an operator, and a value.
Example: ?filter=name$eq:Joe
This matches all resources with the value Joe in the property name.
Predicates can be chained using either of the logical operators AND and OR.
Example: ?filter=name$eq:Joe$and:city$like:*port
Filtering on strings is case insensitive.
Information about what properties allow filtering and on what operators can be found in the property in the schema for the collection. Each property that allows filtering has the property "x-filterable" in combination with operators set. If you try to filter on something that isn’t allowed the server will respond with a status code 400.
The $like: operator supports both using wildcards (*) and not using wildcards. If no wildcards are used, the expression is considered a contains expression and effectively becomes a filter with a wildcard at the start of the string and one at the end of the string. This operator is only allowed on some properties.
To not interfere with the parsing of the filter expression, certain escape sequences are necessary.
- “$” is escaped with “$$”
- “(” is escaped with “$(”
- “)” is escaped with “$)”
- “” is escaped with “$”
- “,” is escaped with “$,”
- “[” is escaped with “$[”
- “]” is escaped with “$]”
To determine whether a specified value matches any value in (or not in) a list you filter using the $in: or $nin: operator. The list to filter by has to be enclosed in brackets and values separated by commas.
customerNumber$in:[2,5,7,22,45]
It is possible to also use the $null: keyword if you wish to include that in the filter. The max supported length of an array using the $in: or $nin: operator is 200.
When it comes to retrieving a collection of items, you can use two distinct approaches:
Cursor-based pagination (continued loading of items using a
cursoras a query parameter to get the next page of items)- This is the recommended approach, and the one you should use by default.
- The endpoint naming scheme is "Retrieve all
Items". (Usage:/{ITEM}?cursor={CURSOR_VALUE}) - The maximum number of items returned in a single call is defined in the
x-cursor-page-sizeextension of the response type. Usually, the size is 1000, but in some cases, where we explicitly state so, it can be smaller.
Classic pagination (limited functionality*. Specify
skippagesandpagesizeas query parameters to get a specific page of items)- You should only consider using classic pagination, if you rely on loading pages (i.e. for list views or table/grid-based UI's).
- The endpoint naming scheme is "Retrieve a page of
Items". (Usage:/{ITEM}/paged?skippages=0&pagesize=20)
* It's important to note that there is a limit of 10.000 items using this approach. Any items outside of the first 10.000 items will not be loaded.
Please bear in mind that the two approaches are supported by separate endpoints. To use classic pagination, add /paged to your request URL.
If you need to know the total count of items that you can expect to get from your search, you can use a separate endpoint called "Retrieve the number of Items".
You can also use the result of this endpoint to calculate the pagination navigation buttons for a table/grid-based UI.
We highly recommend that you use cursor-based pagination because:
- It is more performant and offers much faster retrieval of items;
- It can be used for very large collections of many thousands or millions of items, whereas classic pagination is limited to only returning 10.000 results, everything else is ignored;
Classic pagination is only appropriate when you have an app with a table/grid-based UI.
When you search for items in a large collection, the response will contain a first set of items and a cursor that you can use in a subsequent request to get the next series of items. This way you can retrieve the next set of items only when needed (if the first set suffices, you don't need to send a second request).
The first set of items usually consists of 1000 results. If the cursor is not present in the response, it means that there are no more items in the results.
Please note that the cursor represents the identifier of the first item on the next set and it should not be mistaken for the number of items which are yet to be displayed.
I want to retrieve all subscriptions.
I send a request to https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions and get back an array of 1.000 subscriptions, and a cursor with value 34781
I send a request for the next items in the resulting collection: https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions?cursor=34781 and get back an array of 1.000 subscriptions and a cursor with value 87695
I send a request for the next items in the result: https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions?cursor=87695 and get back an array of 56 items and no cursor. No cursor means I have retrieved all the subscriptions, i.e. I have reached the end of the list.
I want to show a grid with page size of 50 and pagination navigation buttons.
I send a request to see how many subscriptions there are in the collection:
https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/count
I get the number of subscriptions in the collection,2056, and I can calculate the number of pages to be 2056 divided by 50 = 40 with 6 as remainder, meaning I have 41 pages total. I can then use this to present the user the navigation buttons.I send a request to retrieve the first page of subscriptions that my user will see:
https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/paged?pagesize=50&sort=-number
with this I get back an array of 50 subscriptions, sorted by number in descending order.Now if the user wants to see page number 6, I'll send a new request, skipping the first 5 pages to get the subscriptions from page number 6:
https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/paged?pagesize=50&skippages=5&sort=-number
I get back an array of 50 subscriptions that belong to page number 6 when sorting by number in descending order.
The Open API returns these HTTP status codes.
| Code | Text | Description |
|---|---|---|
| 200 | OK | Everything is OK |
| 201 | Created | When you create resources, this is what you get. This will be accompanied by the created resource in the body and a location header with a link to the created resource. |
| 204 | No Content | In certain cases there is nothing to return. So we will let you know by returning a 204. |
| 400 | Bad Request | The request you made was somehow malformed. A malformed request could be failed validation on creation or updating. If you try to filter on something that isn’t filterable this is also what you’ll see. Whenever possible we will also try to include a developer hint to help you get around this issue. |
| 401 | Unauthorized | The credentials you supplied us with weren’t correct, or perhaps you forgot them altogether. If an agreement has revoked the grant they gave your app, this is what you will see. |
| 403 | Forbidden | You won’t necessarily have access to everything. So even though you were authorized we might still deny access to certain resources. This depends on the roles asked for when the grant was issued. |
| 404 | Not Found | This is returned when you try to request something that doesn’t exist. This could be a resource that has been deleted or just a URL you tried to hack. If you see a lot of these, it could be an indication that you aren’t using the links provided by the API. You should never need to concatenate any URLs. The API should provide you with the links needed. |
| 405 | Method Not Allowed | Not all endpoints support all HTTP methods. If you try issue a PUT request to a collection resource this is what you get. |
| 409 | Conflict | The request cannot be completed due to a conflict with the current state of the target resource. Retrieve the resource/object and try the update again. This is needed in order to prevent you from rolling back another user's update. |
| 415 | Unsupported Media Type | Our API is a JSON api. If you ask us to give you anything else, we give you this, and tell you why in the JSON body of the response. |
| 500 | Internal Server Error | We don’t like to see these, and they are flagged in our logs. When you see this, something went wrong on our end. Either try again, or contact our support. |
Since OpenAPI allows client generation based on the specification, we decided to use the same model/schema in our for both read and write endpoints where possible.
This led us to chose not to have the Id/Number in the URL parameter for PUT requests, but to use the one from the body, so there is no confusion.
When a property is marked as required it means you need to provide a value on each POST and PUT requests.
When a property is marked as readonly it means you should provide the same value you get in the GET requests, or do not send the property in the JSON at all (skip it).
ObjectVersion is the mechanism that enforces updates only on latest state of an object. ObjectVersion property is mandatory in Put Requests. ObjectVersion property is retrieved on Get Request and needs to be included in Put Request. If object was modified between Get and Put requests, Put request will fail with error code 409 Conflict
{
"message": "Update conflict. Version does not match.",
"developerHint": "The resource has been updated by another user. Retrieve the resource/object and try the update again. This is needed in order to prevent you from rolling back another user's update.",
"logId": "09580053-1141-4e7f-85e1-bed8600e0278",
"logTimeUtc": "2021-11-04T09:07:56",
"property": "version"
}
Idempotency tokens are unique keys that help maintain the integrity of operations on the API’s. These tokens prevent accidental duplication of requests, ensuring that the same operation is not performed multiple times, even if the same request is sent repeatedly.
When making a request, you can set Idempotency-Key header with your own unique value for that specific request. In case of a network failure, if you don't get the response, you can retry the request with the same value for the header. Our system will prevent duplicate requests, instead you will get the original response from our cache.
Keep in mind that this is cached for only one hour window.
When we return a response from the cache, we set a response header X-ResultFromCache to true.
It’s important to note that you will be responsible for generating and keeping track of these keys.
The Idempotency Tokens feature is not available for GET requests.
The LastUpdated property shows the date when a resource was last updated. A resource is considered updated when any property in the model has been changed. If there aren’t any changes, LastUpdated will equal the creation date.
Please bear in mind that not all resources have a LastUpdated property. Also, sometimes the LastUpdated property is modified by changes to a different model, as is the case with sales documents. For example, when an invoice line is created, the LastUpdated field on the invoice is modified.
The main usage for this property is to help retrieve only data that has been changed within a certain interval. This will save processing and network time spent on the client side.
Usage example: https://apis.e-conomic.com/journalsapi/v16.0.1/the_resource?filter=lastUpdated$gt:2024-02-24 This will return all resources which have been updated since 24.02.2024.
In the specification file, there are some custom extensions that developers can make use of when consuming endpoints. Those extensions are always prefixed by x-.
x-required-roles: The list of roles that are required for each group of endpoints.x-error-codes: The list of error codes that are potentially returned from each group of endpoints.x-cursor-page-size: The maximum number of items inCursorResultsthat can be returned in a single call.
Create tokens as instructed here and then add these two authentication headers to your requests: