/vismanetapi section This is a guide for integrators that want to build integrations towards Visma Net. 2025-10-16T16:01:03+02:00 # Visma Net API This is a guide for integrators that want to build integrations towards Visma Net. ## Introduction This guide aims to help you get started within the Visma Net ecosystem and provide you with the information you need to be able to develop integrations towards Visma Net using any of our different services. >[!TIP] > You can learn more about using Visma Net from the documentation. See [Visma Net Documentation](https://help.content.visma.net/Norway/NO_EN/online-help/mini-tocs/online-help-start-mini-toc.htm). ## Quick start - [Sign up with Visma Software Nordic API](https://www.vismasoftware.no/api-en) ## Resources - [Visma Software Nordic - API Community Discord](https://discord.gg/3qupMPPr4K) - [Visma Developer Portal](https://oauth.developers.visma.com/service-registry/) - [Visma Net Courses](https://www.vismalearninguniverse.com/learn/learning-plans/104/vismanet-erp-api-integration-courses%22) - [Customer Portal Knowledgebase](https://kundeportal.vismasoftware.no/s/topic/0TOQx0000007FTqOAM/se-api-visma-net-api) ## Documentation/Swagger - [Visma Net](https://api.finance.visma.net/API-index/index.html) - [neXtGen SalesOrder](https://salesorder.visma.net/swagger/index.html) - [neXtGen JournalTransactions](https://journaltx.visma.net/swagger) - [DataMart API](https://docs.datamart.visma.net/) /vismanetapi/setting-up-your-integration/authentication section Authentication to Visma Net API via Visma Connect involves multi-tenant identity providers. Requires creating an app in Visma Developer Portal. 2025-10-15T10:34:38+02:00 # Authentication Authentication to Visma Net API via Visma Connect involves multi-tenant identity providers. Requires creating an app in Visma Developer Portal. Authentication to Visma Net API is done through Visma Connect. Visma Connect is a multi-tenant identity provider. Tenants are organizations (businesses) that provide an API-context. A given user may have access to multiple tenants and will choose which to connect to your application upon each single sign-on flow. > [!TIP] > You'll need to create an application in the Visma Developer Portal, available at , before getting started. > [!TIP] > To learn more about this process see this document . Please explore Visma Developer Portal documentation. ## Endpoints Visma Connect endpoint details: | Endpoint | URL | | -------- | --- | | Discovery | | | Authorization | | | Token | | | Userinfo | | | Endsession | | ## Visma Connect Token Your application requests specific permission scopes and is granted an access token upon a user's approval. There are two scenarios that are supported by Visma Connect: - Interactive authentication of users, that must provide their credentials in a login form. That requires the authentication flow to use the *Authorization Code* or *Authorization Code with PKCE* grant type. - Authentication of a service, using a client ID and a client secret. That requires the authentication flow to use the *Client credentials* grant type. Once the authentication process has completed successfully, you can make API calls by providing the valid access token with each API request using the `authorization` header. /vismanetapi/setting-up-your-integration/authentication/oauth page Understanding OAuth2 for Visma API integration, including roles, tokens, scopes, grants, and necessary endpoints for secure resource access. 2025-10-15T10:34:38+02:00 # Understanding OAuth Understanding OAuth2 for Visma API integration, including roles, tokens, scopes, grants, and necessary endpoints for secure resource access. Access to resources and APIs in Visma is done through Visma Connect. This is an identity provider. The OAuth2 flow is used to authorize users and services to access the desired resources. You need to know the basics of OAuth in order to understand the authorization process and build your integration with Visma Net. ## What is OAuth2? OAuth is a standard that allows websites or applications to access, on behalf of an user, resources hosted by other apps (servers). The term OAuth stands for "Open Authorization" and the number 2 refers to the 2.0 version of the standard. The standard allows users to grant client applications consented access to what resources they can access without sharing credentials. OAuth is not intended to authenticate users (that is verifying that a user is who he claims to be) but to authorize them. That means granting access to resources such as remove APIs. > [!NOTE] > > You can read more about OAuth2 here: > > - [OAuth 2.0](https://oauth.net/2/) > - [What is OAuth 2.0?](https://auth0.com/intro-to-iam/what-is-oauth-2/) ## Roles The OAuth standard defines a set of roles that represent components of an authorization system. These roles/components are the following: - **Resource owner**: the system/user that owns a resource and that grants access to that resource. - **Client**: the system that requires access to a protected resource. - **Authorization server**: a server that receives requests from the **Client** for access tokens and issues them after authenticating the **Resource owner** and obtaining consent for the requested access. - **Resource server**: a server that protects the resources and receives access requests to them from the **Client**. The interactions between these components are illustrated in the following image:  ## Access tokens In order to grant access to resources, OAuth2 uses *access tokens*. An access token is basically a document that describes the authorization to access resources on behalf of a user. The OAuth2 standard does not define a format. The JSON Web Token (JWT) is the widely used format. Visma Connect uses the JWT format for access tokens. The JWT token is a base64 encoded document. Typically, you should not be concerned with the content of a token. For debugging purposes, however, you can use the [jwt.io](https://jwt.io) website to inspect the content of a JWT access token. Its payload looks as follows: ### Interactive ```json { "iss": "https://connect.visma.com", "nbf": 1755516249, "iat": 1755516249, "exp": 1755519849, "aud": "https://api.finance.visma.net/erp/interactive", "scope": [ "vismanet_erp_interactive_api:create", "vismanet_erp_interactive_api:delete", "vismanet_erp_interactive_api:read", "vismanet_erp_interactive_api:update" ], "amr": [ "pwd", "remember2sv" ], "client_id": "clientId", "tenant_id": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "tenant_external_id": "1234356", "tenant_owner_client_id": "odp", "sub": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "auth_time": 1755501468, "idp": "Visma Connect", "llt": 1754980057, "created_at": 1535971848, "acr": "2", "sid": "ddc3c4d6-db00-32ff-2c6a-514268f56b0f" } ``` ### Service ```json { "iss": "https://connect.visma.com", "nbf": 1755506773, "iat": 1755506773, "exp": 1755510373, "aud": "https://api.finance.visma.net/erp/service", "scope": [ "vismanet_erp_service_api:create", "vismanet_erp_service_api:delete", "vismanet_erp_service_api:read", "vismanet_erp_service_api:update" ], "client_id": "clientId", "tenant_id": "ddc3c4d6-db00-31ff-2c6a-514268f56b0f", "tenant_external_id": "1234356", "tenant_owner_client_id": "odp" } ``` An access token contains information such as: - issuer (`iss`) - the destination of the token (`aud`) - issued time (`iat`) - not valid before(`nbf`) - expiration time (`exp`) - subject - whom the token refers to (`sub`) - scopes - list of granted scopes (`scope`) The one what you need to know about are the scopes. >[!NOTE] > > You can read more about access tokens here: > > - [OpenID Connect specifications](https://openid.net/specs/openid-connect-core-1_0.html) > - [Introduction to JSON Web Tokens](https://jwt.io/introduction) ## ID token vs Access token vs Refresh token When you read about OAuth tokens, there are three terms that come up and can be confusing: - **ID token**: this is a document that proves that a user has been authenticated and can carry information about the user. The ID token was introduced by OpenID Connect (OIDC) which is an open standard for authentication used by many identity providers, including Google, Facebook, and Apple. - **Access token**: this is a document that carries information about the authorization to a resource. - **Refresh token**: this is a special kind of token that is used to obtain additional access tokens. An ID or access token is valid for a specific period of time (like 30 seconds or 60 minutes for instance). A refresh token is used to retrieve new access tokens without the need to re-authenticate the user. A refresh token is requested alongside the initial request for an ID and access token and must be stored (securely) by the application. >[!NOTE] > > You can read more about these kinds of tokens here: > > - [ID Tokens vs Access Tokens](https://oauth.net/id-tokens-vs-access-tokens/) > - [ID Token and Access Token: What's the Difference?](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) > - [What Are Refresh Tokens and How to Use Them Securely](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) ## Scopes Scopes are reasons for which access to a resource is requested. For instance, there can be a scope for reading data, one for inserting and updating, one for deleting. Scopes depend on the resource server. Visma Net defines four scopes per integration type: | Interactive | Service | | ----------- | ------- | | vismanet_erp_interactive_api:create | vismanet_erp_service_api:create | | vismanet_erp_interactive_api:delete | vismanet_erp_service_api:delete | | vismanet_erp_interactive_api:read | vismanet_erp_service_api:read | | vismanet_erp_interactive_api:update | vismanet_erp_service_api:update | >[!TIP] > However, in case of a web application, when you register it with Visma Developer Portal, you need to set the following scopes: `email`, `openid`, and `profile`. Upon reqesting an access token, you need to specify the following scopes: `business-graphql-api:access-group-based` `openid` `email`. These extra scopes are not necessary for services. > > Read more about this here: > > [Web applications registration](./web/setup_web.md) and [GraphQL API Integration](./web/integrations_web.md). > > [Services registration](/businessnxtapi/authentication/service/application_registration/) and [GraphQL API Integration](./service/integrations_service.md). ## Grants Grants are steps a client performs to get authorization for accessing a resource. The authorization framework defines several grant types for different scenarios: - Authorization Code - Implicit - Authorization Code with Proof Key for Code Exchange (PKCE) - Resource Owner Credentials - Client Credentials - Device Authorization Flow - Refresh Token Grant One of the grant types used for Visma Net is **Authorization Code with PKCE**. This flow consists of the following steps: 1. The user clicks a login button/link in the application. 2. The application creates a random `code_verifier` and from it generates a `code_challenge`. 3. The application makes an authorization request to the `/authorize` endpoint of the authorization server with the generated `code_challenge`. 4. The authorization server redirects the user to the login and authorization page. 5. The user authenticates (using a selected option) and may be displayed a consent page that lists the permissions the application is requesting. 6. The authorization server stores the `code_challenge` and redirects the user back to the application, providing a one-time-use `authorization_code`. 7. The application sends the `code_verifier` and the `authorization_code` to the `/token` endpoint of the authorization server. 8. The authorization server verifies the `code_challenge` and the `code_verifier`. 9. The authorization server returns an *ID token*, an *access token*, and optionally, a *refresh token*. 10. The application uses the access token to call an API. 11. The API responds with the requested data.  >[!NOTE] > > You can read more about grants here: > > - [Authentication and Authorization Flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow) > - [OAuth Grant Types: Explained](https://frontegg.com/blog/oauth-grant-types) > - [OpenID Connect & OAuth 2.0 API](https://developer.okta.com/docs/reference/api/oidc/) ## Endpoints and redirect URLs Endpoints and a redirect URL are key parts of the OAuth flow. An authorization server exposes several endpoints that are used at various steps in the authorization flows: | Endpoint | Description | | -------- | ----------- | | `/authorize` | Interact with the resource owner and obtain an authorization grant. | | `/token` | Obtain an access token and/or an ID token by providing an authorization grant or refresh token. | | `/endsession` | End the session associated with the given ID token. | | `/userinfo` | Return claims about the authenticated end user. | >[!TIP] > > To get the URLs of the Visma Connect endpoints check [this page](/businessnxtapi/authentication/). A *redirect URL* is a URL to which the authorization server will redirect the user after the user successfully authorizes an application. A redirect URL contains sensitive information. The authorization server must not redirect the user to arbitrary (unsecure) locations. In order to ensure the user is redirected to an appropriate location, the developers of the application are required to register one or more redirect URL when they create the application. >[!TIP] > > Visma Developer Portal requires you to provide a redirect URL when you register your application in the system. You can read more about that here: [Web Application registration](/businessnxtapi/authentication/web/). /vismanetapi/setting-up-your-integration/developer-portal section Creating an account and application in Developer Portal 2025-10-16T11:16:31+02:00 # Developer Portal Creating an account and application in Developer Portal ## Getting Started with Visma Developer Portal At Visma we want to create a dynamic network of Applications interacting with each other, to co-create and exchange value for the members of the ecosystem. We want to empower our ecosystem to deliver meaningful and easy to use solutions that simplifies and digitizes core business processes. We believe we can empower people greatly through technology. But how technology empowers people depends on how it is being applied. This is where APIs come in. Our products and solutions become better when they connect to an ecosystem of great solutions. Visma Developer Portal is an API-driven solution for professional services firms. It provides functionality for registering applications and managing integrations with Visma APIs and enabling Single Sign-On. It also allows for managing webhook subscriptions for client applications. Let’s create better technology together. ## Creating an Account To begin using the Visma Net API, you must first create an account in the Visma Developer Portal. The steps below outline the registration process: ### Registration Steps 1. **Visit the Visma Developer Portal** - Navigate to the [Visma Developer Portal](https://oauth.developers.visma.com) to access the registration page. 2. **Sign Up for a Developer Account** - Click on the "Create Account" button to start creating a new developer account. - You will be prompted to enter your email address and create a password. Ensure you use a valid email address as it will be used for account verification. 3. **Verify Your Email** - After submitting your registration details, check your email inbox for a verification email from Visma. - Click the verification link provided in the email to activate your account. 4. **Complete Profile Setup** - Once your email is verified, log in to the Visma Developer Portal. - Complete the profile setup by providing additional information such as your organization name, if applicable, and other relevant details to set up your developer profile. 5. **Explore the Developer Dashboard** - After setting up your profile, you will have access to the developer dashboard where you can manage your applications, view API documentation, and track usage analytics. ### Additional Resources For further guidance on getting started with Visma APIs, visit the [Visma Developer Documentation](https://oauth.developers.visma.com/service-registry/documentation/) for comprehensive instructions and support documents. /vismanetapi/setting-up-your-integration/developer-portal/service-integrations section Creating Service Integrations 2025-10-16T11:16:31+02:00 # Service Integrations Creating Service Integrations ## Service Integrations A Service Integration is designed for machine-to-machine integrations where user interaction is not required. These applications strictly make API calls and utilize the `client_credentials` OAuth2 grant type to acquire access tokens from the Authorization Server. This type of application typically runs on a server or on-premise, and it is considered confidential. ## Key Characteristics - **No End-User Authentication**: Service applications do not involve end-users in the authorization process. - **Machine-to-Machine Use**: Ideal for backend integrations where applications communicate directly with each other. - **Confidential**: Ensures that sensitive information, such as client secrets, remains secure on the server. ## Token Request Service applications use the `client_credentials` OAuth2 grant type to obtain access tokens. Below is an example demonstrating how to request an access token: ```bash curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' \ --data 'grant_type=client_credentials&scope=visma_api:read&client_id=demoapp&client_secret=SECRET&tenant_id=af1140c1-52e0-46c7-b684-df894d4b8a5a' ``` ### Request Parameters - **grant_type**: Must be `client_credentials`. - **scope**: Specifies the scope of API access requested by your application. - **client_id**: The unique identifier of the application, obtained during registration. - **client_secret**: The confidential secret provided when registering the application. - **tenant_id** (optional): Used to specify the tenant for API data access. Required for tenant-based APIs, such as `visma_api:read`. Your application requires tenant administrator permission before using `tenant_id` in the token request. ## Token Response Upon a successful request, the authorization server returns a token formatted as follows: ```json { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjVENDc...7MTOBbdd5mgb2CHzxL0RFjs24pqC1pCeUqOjbg", "expires_in": 3600, "token_type": "Bearer", "scope": "visma_api:read" } ``` By following these steps, developers can effectively configure service applications to securely interact with Visma APIs. /vismanetapi/setting-up-your-integration/developer-portal/interactive-integrations section Creating Interactive Integrations 2025-10-16T11:16:31+02:00 # Interactive Integrations Creating Interactive Integrations ## Interactive Integrations Interactive integrations use the authorization code flow for secure authentication and access to Visma APIs. This flow is adaptable to different application types, each with unique characteristics. ### Application Types #### 1. **Single Page Applications (SPAs)** - **Execution Environment**: Runs entirely in the browser. - **Security Approach**: Implements PKCE to secure authorization as client secrets cannot be safely stored. - **Limitation**: SPAs do not receive refresh tokens because they lack the capability for offline access. #### 2. **Server-Side Web Applications** - **Execution Environment**: Operates on a server, managing secure interactions server-side. - **Security Approach**: Can use traditional `authorization_code` flow with client secrets; PKCE is optional but enhances security. - **Capability**: Eligible for refresh tokens when configured with `offline_access`. #### 3. **Native Applications** - **Execution Environment**: Runs on devices like desktops or mobiles. - **Security Approach**: Uses external browsers for authorization requests; relies on PKCE to protect authorization codes. - **Capability**: Like SPAs, does not typically utilize refresh tokens. ### Authorization Code Flow Steps The authorization code flow involves several key steps, ensuring secure token exchange: #### Step 1: Authorization Request For all interactive applications, initiate the authorization request by generating a `code_verifier` and a `code_challenge` (if PKCE is used). Example Request (Common Structure): ```bash GET https://connect.visma.com/connect/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=openid+email+profile&redirect_uri=YOUR_REDIRECT_URI&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256&state=YOUR_STATE_PARAMETER&ui_locales=YOUR_LOCALE_PREFERENCES ``` Common Parameters: - **client_id**: Unique identifier for your application. - **response_type**: Always `code` for authorization code flow. - **redirect_uri**: Specifies where the response is sent; must match registration details. - **code_challenge (PKCE)**: BASE64-URL-encoded SHA256 hash; optional for server-side apps. - **state**: Prevents CSRF and ensures response integrity. - **ui_locales**: Preferred languages for user interface. #### Step 2: User Consent (Optional) Users may be prompted to approve the application access request. This step depends on application settings and user privileges. #### Step 3: Authentication Response Upon user consent, Visma returns an authorization code to the specified redirect URI. Sample Response: ``` YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE_PARAMETER ``` ### Step 4: Exchange Authorization Code for Tokens Use the received authorization code and the `code_verifier` (for PKCE) to request access tokens. Example Token Request: ```bash curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' \ --data 'grant_type=authorization_code&redirect_uri=YOUR_REDIRECT_URI&code=AUTHORIZATION_CODE&client_id=YOUR_CLIENT_ID&code_verifier=YOUR_CODE_VERIFIER&client_secret=YOUR_CLIENT_SECRET' ``` - **grant_type**: `authorization_code` for interactive applications. - **code_verifier**: Necessary for PKCE-enabled flows. - **client_secret**: Required for server-side apps unless PKCE is used. ### Important Notes - **Refresh Tokens**: Only server-side web applications configured with `offline_access` can request refresh tokens to renew expired access tokens. - **Security Best Practices**: Use https and secure state management to prevent CSRF attacks. By effectively implementing this standardized process, developers ensure secure and efficient integration with Visma API resources, tailored to their application type. /vismanetapi/setting-up-your-integration/how-tos section Guides and best practices for integrating with the Visma Net API 2025-11-06T14:11:33+01:00 # How Tos Guides and best practices for integrating with the Visma Net API In this section you will learn more about Visma Net API. It includes important techniques and best practises for secure and effective integration. - [ETag and If-Match Headers](etag.md) - [DateTimeCondition & Operators](date-time-condition-operators.md) - [Background API calls](background.md) - [Pagination](pagination.md) /vismanetapi/setting-up-your-integration/how-tos/etag section Ensuring Data Consistency with ETag and If-Match HTTP Headers 2025-11-06T09:47:29+01:00 # ETag and If-Match Headers Ensuring Data Consistency with ETag and If-Match HTTP Headers ## Overview In modern web applications, ensuring data consistency and preventing conflicts is essential, especially when multiple clients attempt to update the same resource concurrently. The ETag and If-Match HTTP headers offer a solution for these challenges. Here's how they work together to maintain data integrity. ## ETag Response Header An ETag (Entity Tag) is a unique identifier that the server assigns to a specific version of a resource. It is included in the response header when a client requests the resource. This identifier helps clients in managing cache and detecting resource changes. - **Usage in API**: When a client requests a resource, the server responds with the ETag value in the response header and as part of the response DTO (with the field name: "**Timestamp**"). - **Pagination Note**: During paginated responses, the ETag value isn't included in the response header but is available within the response DTO (Field name: "**Timestamp**"). ## If-Match Request Header (Optional) The If-Match HTTP header is used by clients to signal that they wish to update a resource only if its current version matches a specific ETag. This mechanism prevents resource conflicts when multiple clients try to update the same resource simultaneously. Refer to Also: [Lost Update Problem](https://www.w3.org/1999/04/Editing/#3.1), [If-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Match), [HTTP conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Conditional_requests). - **Conflict Prevention**: If the ETag stored on the server doesn't match the client's If-Match header, the server responds with a 412 Precondition Failed status code. - **Usage in API**: Currently, the "If-Match" header is optional and can only be used with certain PUT & POST action endpoints shared in detail in the following section below. ## Example **1. GET**: .../v1/supplier/xxxxx **Response headers**: ETag  **Response body**: timeStamp  **2. PUT**: .../v1/supplier/xxxxx **Request headers**: If-Match  This request will succeed in updating the resource only if the resource's current "ETag" is "AAAAAE0YIiI=". **A. In case of success**, the server returns "204 - No content" together with the new ETag value in the response headers.  **B. In case of failure**, the server returns "412 - Precondition Failed".  ## Advantages of using ETag and If-Match - **Optimistic concurrency control**: By using If-Match headers, clients can ensure that updates to resources are made safely without unwanted overwrites. - **Data Integrity**: Helps maintain data consistency by validating that resource updates are based on the most current data. ## API Endpoints with ETag and If-Match Header Support ### Endpoints & Operations Supporting "ETag" Response Header GET, PUT & POST operations on the following endpoints include an "etag" in the response header: - Account - Budget - CashSale - CashTransaction - Contact - Customer - CustomerCreditWriteOff - CustomerDebitNote - CustomerInvoice - CustomerOverdueCharge - CustomerPayment - Dimension - Employee - ExpenseClaim - JournalTransaction - PurchaseOrder - PurchaseOrderBasic - PurchaseReceipt - PurchaseReceiptBasic - Shipment - Subaccount - Supplier - SupplierInvoice - SupplierLocation - SupplierPayment - Timecard Note: "TimeStamp" field can also be checked via the DTOs where it's exposed. ### Endpoints & Operations Supporting "If-Match" Request Header - PUT Account - PUT Budget - PUT CashTransaction - PUT CashSale - PUT Contact - PUT Customer - PUT CustomerDebitNote - PUT CustomerInvoice - PUT CustomerOverdueCharge - PUT CustomerPayment - PUT Dimension - PUT Employee - PUT ExpenseClaim - PUT JournalTransaction - PUT PurchaseOrder - PUT PurchaseOrderBasic - PUT PurchaseReceipt - PUT PurchaseReceiptBasic - PUT Shipment - PUT Subaccount - PUT Supplier - PUT SupplierInvoice - PUT SupplierLocation - PUT SupplierPayment - PUT Timecard **If the endpoint is asynchronous**, meaning that if it immediately returns a "202-Accepted" HTTP response and starts the actual job in the background, such as "Action"-based operations. (Endpoint URL: …/action/…) If-Match is supported in the following actions only with "**erp-api-background** usage": - POST CustomerDebitNote action/Release - POST CustomerDebitNote action/sendToAutoInvoice - POST CustomerOverdueCharge action/release - POST CustomerPayment action/Release - POST CustomerPayment action/Void - POST SupplierPayment action/Release - POST SupplierInvoice action/Release - POST SupplierInvoice action/Prebook - POST SupplierInvoice action/voidinvoice - POST SupplierInvoice action/sendtoapproval /vismanetapi/setting-up-your-integration/how-tos/date-time-condition-operators section Utilizing DateTime Parameters in Visma Net API Endpoints 2025-11-06T14:11:33+01:00 # DateTimeCondition & Operators Utilizing DateTime Parameters in Visma Net API Endpoints ## Overview In this article, you can find guidelines on utilizing Visma Net API Endpoints using DateTime parameters, as well as their associated condition and operators. For more information regarding the endpoints, query parameters and other endpoints for all areas, please read the documentation found here: [Swagger - Visma Net Documentation](https://finance.visma.net/swaggerui/index.html) ## lastModifiedDateTimeCondition=Operator Supported comparative operators for LastModifiedDateTime Conditions on filtering: | Operator | Description | |-----------|-------------------------| | `>` | Greater than | | `<` | Less than | | `<=` | Less than or equal to | | `>=` | Greater than or equal to| ## Explanation | Query | Description | |----------------------------------------------------------------------|------------------------------------------------| | `?lastModifiedDateTime=2025-05-25&lastModifiedDateTimeCondition=>` | Retrieve records after and on the given DateTime | | `?lastModifiedDateTime=2025-05-25&lastModifiedDateTimeCondition=<=` | Retrieve records before and on the given DateTime| | `?lastModifiedDateTime=2025-05-25&lastModifiedDateTimeCondition=<=` | Retrieve records before and on the given DateTime| | `?lastModifiedDateTime=2025-05-25&lastModifiedDateTimeCondition=>=` | Retrieve records after and on the given DateTime | ## Usage example This query will return customers updated on 2025-05-25 or later. ```plaintext GET https://api.finance.visma.net/v1/customer ?lastModifiedDateTime=2025-05-25 &lastModifiedDateTimeCondition=>= ``` (Lines are separated for readability) ## The operators are used the same for createdDateTimeCondition=**Operator** dunningLetterDateTimeCondition=**Operator** /vismanetapi/setting-up-your-integration/how-tos/background section How to use “background-api” calls in Visma NET 2025-11-06T14:11:33+01:00 # Background API calls How to use “background-api” calls in Visma NET ## Overview A “background-api” request is a regular request, but with an extra header “erp-api-background” with the value “subscription”, “subscription:``” 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 `` part is optional. It supports name/value pairs in the format ``=``,..,``=``. 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.** /vismanetapi/setting-up-your-integration/how-tos/pagination section Visma Net ERP API Pagination Explained 2025-11-06T14:11:33+01:00 # Pagination Visma Net ERP API Pagination Explained ## About Paging When retrieving lists of data from API endpoints, it is most efficient for both the client and server to divide the results into portions rather than retrieving all the data at once. The Visma Net API supports this through a method called paging. Paging means that when you request lists of data, you should also provide two extra query parameters called **pageSize** and **pageNumber**. - **pageSize**: The maximum number of records you want returned on each page (the length of each page). - **pageNumber**: The page you are requesting. ### Example In the database, you have 350 customers. You make a GET request to the Customer endpoint to retrieve all these. To limit the number of customers received, you can divide this into pages that contain up to 100 customers (**pageSize=100**). To get the complete list, you then have to make 4 requests to the Customer endpoint: | Request | Result | |------------------------------------------|--------------------------------------------------| | GET /customer?pageSize=100&pageNumber=1 | Returns the first 100 customers (1-100) | | GET /customer?pageSize=100&pageNumber=2 | Returns the second page of 100 customers (101-200) | | GET /customer?pageSize=100&pageNumber=3 | Returns the third page of 100 customers (201-300) | | GET /customer?pageSize=100&pageNumber=4 | Returns the last page of remaining customers (301-350) | Paging is implemented on all GET endpoints that return lists in the Visma Net API. It is mandatory to use the parameters **pageSize** and **pageNumber** in all requests to endpoints that support this. ## Paging in Visma Net API For all endpoints that return lists paging is implemented by providing two query parameters: **pageSize** and **pageNumber**. For all endpoints these parameters are documented in the [Visma Net Swagger documentation](https://finance.visma.net/swaggerui). For all endpoints that provide these parameters it is important that your integration provide these for all requests. If not provided default-values will be used and you will potentially not receive the complete resultset. In the swagger-documentation you can see the default-value for the specific endpoint. ## Paging in Sales Order Service API Paging is also implemented in the Sales Orders API using the parameters **pageSize** and **pageIndex** (instead of **pageNumber**). More information can be found in the [Sales Order Swagger documentation](https://salesorder.visma.net/swagger/). ## Default Parameter Values | Parameter | Default value (if not provided) | |-----------|--------------------------------------------------------| | pageNumber| 1 | | pageSize | Can vary by endpoint, and can also change over time. | Maximum value for the pageSize parameter is bound to the default-value that will also represent the maximum value allowed. Meaning that if you specify a value in pageSize that is greater than the default value, the endpoint will only return the number of records defined by the default value for pageSize in this endpoint. In addition to swagger-documentation the maximum allowed value for pageSize will also be returned as part of the metadata-property in the returned JSON-data. The value will have the name maxPageSize. ## Metadata As part of every request to an endpoint that supports paging you will get a metadata-property returned as part of the returned JSON-data. This metadata is provided to give your integration information about the available results and restrictions of the current request. The metadata-property will provide the following values: ```c# "metadata": { "totalCount": 450, "maxPageSize": 1000 } ``` ### Metadata: totalCount The total number of results for the current request regardless of pages. Example: `GET /customer?name=Norwegian&pageSize=5&pageNumber=1` This request will return the first page of 5 customers with the name containing “Norwegian”. However, in the database, there are 12 customers with names containing “Norwegian”, so the **totalCount** will have the value 12. ### Metadata: maxPageSize The maximum **pageSize** you can set for this endpoint. If you specify a number higher than this, the result will be restricted to only return the **maxPageSize** number of records. --- You can use the values in the metadata to calculate the number of pages you need in order to receive the whole result set based on the **pageSize** you are using. ## Paging in Combination with Filters Most GET-endpoints in the API contain filter-parameters. These are used to narrow down the resultset to only contain the records that are relevant to the request. It is important to notice that when these filter-parameters are used in combination with the paging-parameters, the resultset is defined as the total resultset for the specified filter-parameters. This means that if the resultset spans across multiple pages, the exact same filter-parameters must be specified for all subsequent requests to get the following pages. The Visma Net API contains no state to store what pages/records have been delivered, so every request will be handled independent of previous requests. The figure below illustrates what results will be included in each page based on three different queries with different values for parameters **lastModifiedDateTime** and **pageSize**. ### Query 1 **?lastModifiedDateTime**=2020-03-01T00:00:00&**lastModifiedDateTimeCondition**=>=&**pageSize**=3 The resultset will be divided into 4 different pages, meaning that you have to make 4 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-4 and the colors yellow, pink, green and blue in the figure. ### Query 2 **?lastModifiedDateTime**=2020-03-01T00:00:00&**lastModifiedDateTimeCondition**=>=&**pageSize**=5 The resultset will be divided into 2 different pages, meaning that you have to make 2 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-2 and the colors green and purple in the figure. ### Query 3 **?lastModifiedDateTime**=2020-03-06T00:00:00&**lastModifiedDateTimeCondition**=>=&**pageSize**=3 The resultset will be divided into 2 different pages, meaning that you have to make 2 requests to the API, with the exact same values for parameter lastModifiedDateTime, lastModifiedDateTimeCondition and pageSize. The pageNumber-parameter will define what results you will get, marked by the numbers 1-2 and the colors blue and gray in the figure.  If you do not keep these parameters constant (the pageSize is changed), and do the following set of requests: - **?lastModifiedDateTime**=2020-03-01T00:00:00&**lastModifiedDateTimeCondition**=>=&**pageSize**=3&**pageNumber**=1 - **?lastModifiedDateTime**=2020-03-01T00:00:00&**lastModifiedDateTimeCondition**=>=&**pageSize**=5&**pageNumber**=2 This will result in you getting the following records: First request: Record 1,2,3 Second request: Record 6,7,8,9,10 As you can see the records 4 and 5 will not be returned to you. ## New records added while getting pages Sometimes new records are added to or removed from the database by other uses while you are getting the records using paging. In that scenario the totalCount metadata-property will always change to reflect the new total number of records available for your query. Because of this it is important to always check the value of totalCount for each GET request to retrieve a new page, to be able to calculate the total number of pages needed to get the complete resultset. ### Example You want to get all the customer with status=”Active”, the results should be divided into pages with 10 customers (pageSize=10). 1 You make the following request to get the first 10 customers. GET/customer?status=Active&pageSize=10&pageNumber=1 2 As part of the response you get the metadata including the totalCount - property that tells you that the total number of results are 30. ```c# "metadata": { "totalCount": 30 } ``` 3 This means that you have to repeat the request two more times to get the full result-set. 4 You make the second request to get the next 10 customers. GET/customer?status=Active&pageSize=10&pageNumber=2 5 As part of the response you again get the metadata including the totalCount - property, but this now tells you that the total number of results are 32. Meaning that two new customers have been added or changed status to Active by another user ```c# "metadata": { "totalCount": 32 } ``` 6 This means that you now have to make a total of 4 requests to get the complete result-set. (10+10+10+2). This shows that your client should always keep track of the total number of results received and the total count of results available to make sure that you always get the complete result-set. The following code-example represents a possible implementation of this: ```python def get_all_active_customers(): page_size = 10 # The pageSize we want to use nest_page_number = 1 # The next page to get, initial value = 1 results_recieved = 0 # The number of results we've recieved total_count = 1 # The total number of results available #If we've revieved less than the total number of resultes, we make a new loop while results_recieved < total_count: response = request.get('https://integration.visma.net/API/controller/api/v1/customer', params={ 'status': 'Active', 'pageSize': page_size, 'pageNum': next_page_number }, headers={ 'Accept': 'application/json', 'Authorization': 'Bearer' + token, 'ipp-company-id': company_id, 'ipp-application-type': 'Visma-net Financials' } | ) if response.status_code == 200: result = json.loads(response.text) # Decodes the recieved JSON # {handle the results} # Increments the number of results recieved by the number of results recieved by this request results_recieved += result.len total_count = result[0]['metadata']['totalCount'] # Updates the total_count variable with the current total count of results next_page_number += 1 # Increments the next page to get by 1 ```