Background API calls

Overview

A “background-api” request is a regular request, but with an extra header “erp-api-background” with the value “subscription”, “subscription:<custom-headers>” or “none” (without quotes). The API request will then be saved into a queue and responded with a jobId and status 202. The actual work will be handled in the background by the first server with free capacity.

There will be no notification when the call is done executing. With the value “subscription”, a webhook notification will be sent to the webhook subscriber that is set up in Developer Portal for the “Visma net” application event named “BACKGROUND_API_RESPONSE”. The <custom-headers> part is optional. It supports name/value pairs in the format <headername_1>=<value_1>,..,<headername_n>=<value_n>. When specified, the keys will end up as custom headers in the webhook notification with the corresponding values.

Here you can typically specify your own reference ids to be able to recognize custom state for the operation in your webhook listener. One can at any time the next 24 hours GET /api/v1/background/{id} to poll the status of a background-api operation.

Current usages of the erp-api-background header with a url as a value, will still work for a while, but you are advised to register these as webhook subscriptions in Developer Portal and refactor client code accordingly, since we plan to end the current mechanism.

Recommended for: API requests taking more than 4 minutes. All API requests that spend more than 4 minutes can be refactored into being “background-api” calls.

Note: background-api using this header mechanism, works only for v1 and v2 api endpoints currently.