Getting started with the Bimp API: user, tokens, first request

What you need to work with the API

To work with the API you need a separate Bimp user created specifically for the integration. The subscription for it is paid at standard rates. Create it as described in Users. All articles in this section are listed on the “For developers” page.

The API base address is https://app.bimpsoft.com. All method paths start with /org2/, for example /org2/auth/api-login. Most methods are POST with a JSON body; some (for example, stock balances at /org2/inventory/api-readList) are GET with parameters in the query string. The OpenAPI specification and interactive documentation are available at https://app.bimpsoft.com/docs, and the issue tracking repository is https://github.com/Bimpsoft/public-api.

What types of tokens there are

The API uses two types of JWT tokens, passed in the access-token header:

Token	What it is for	How to get it
Base access token (accessToken)	Requests not tied to a company, for example the list of companies	/org2/auth/api-login
Company access token (companyAccessToken)	All requests to the data of a specific company	/org2/auth/api-selectCompany

How to get a token and make your first request

To make your first request, sign in, find the company, select it and call the method you need.

1. Get the base token. Send the email and password of the API user to /org2/auth/api-login:

   curl -X POST https://app.bimpsoft.com/org2/auth/api-login \
     -H "Content-Type: application/json" \
     -d '{"email": "api-user@example.com", "password": "<PASSWORD>"}'

   The response contains a pair of tokens:

   {
     "success": true,
     "data": {
       "accessToken": "<ACCESS_TOKEN>",
       "refreshToken": "<REFRESH_TOKEN>"
     }
   }

2. Find the company. Call /org2/company/api-readDetailedList with the base token (POST method). In the response each company has the fields name, uuid, code, createdAt:

   curl -X POST https://app.bimpsoft.com/org2/company/api-readDetailedList \
     -H "access-token: <ACCESS_TOKEN>"

3. Get the company token. Pass the company uuid or code to /org2/auth/api-selectCompany with the base token:

   curl -X POST https://app.bimpsoft.com/org2/auth/api-selectCompany \
     -H "access-token: <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"code": "<COMPANY_CODE>"}'

   { "success": true, "data": { "companyAccessToken": "<COMPANY_ACCESS_TOKEN>" } }

4. Make a request to company data, passing companyAccessToken in the access-token header. For example, the first 10 customer orders:

   curl -X POST https://app.bimpsoft.com/org2/invoiceForCustomerPayment/api-readList \
     -H "access-token: <COMPANY_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"pagination": {"offset": 0, "count": 10}}'

How to refresh a token

The access token (base or company) is valid for 1 hour, the refresh token for 1 week. When the access token expires, send the refreshToken to /org2/auth/api-refresh:

curl -X POST https://app.bimpsoft.com/org2/auth/api-refresh \
  -H "access-token: <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "<REFRESH_TOKEN>"}'

The response has the same shape as api-login: data.accessToken and data.refreshToken. If the refresh token expires too, sign in again via /org2/auth/api-login. After refreshing the base token, repeat api-selectCompany to get a fresh company token.

To check the company token there is a service method /org2/auth/api-verifyCompanyAccess: it returns the authorization data tied to the token.

General rules for requests and responses

These rules apply to most methods:

Topic	Rule
Format	Request and response bodies are JSON; header Content-Type: application/json
Message language	Accept-Language header, uk-UA by default
Dates	ISO 8601 in UTC with a trailing Z, for example 2025-05-16T09:17:49.000Z; the document date field is 2025-05-16T09:17:49
Identifiers	All IDs are UUIDs in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Successful response	{"success": true, "data": ...}
Optional fields	Fields marked ? in the reference can be omitted
Filters	Most readList methods accept optional filters (period, status, organization, number)

Pagination, request limits and the error format are described in Limits, pagination and errors. Mapping Bimp objects to your system is covered in External IDs. All methods are in the API reference.

Common problems

The API user’s session in Bimp suddenly ends. Cause: the integration uses the same account as a person. Solution: create a separate user for the API only.

A request returns an authorization error after an hour of work. Cause: the access token is valid for 1 hour. Solution: refresh it via /org2/auth/api-refresh, and when the refresh token expires, sign in again.

A request to company data does not work with the base token. Cause: the base token is not tied to a company. Solution: get a companyAccessToken via /org2/auth/api-selectCompany.