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

URL: https://bimpsoft.com/en/help/developers/api-getting-started/
Updated: 2026-11-06

> The Bimp API is a JSON API at https://app.bimpsoft.com. You need a separate user for the API. First, login returns a base token, then selectCompany exchanges it for a company token, which is passed in the access-token header. The access token lives for 1 hour, the refresh token for 1 week.

## 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](https://bimpsoft.com/en/help/access/users/). All articles in this section are listed on the “[For developers](https://bimpsoft.com/en/help/developers/)” page.

> [!WARNING] Do not use your main account for API connections. This causes the user's session in Bimp to end automatically.

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`:

   ```bash
   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:

   ```json
   {
     "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`:

   ```bash
   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:

   ```bash
   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>"}'
   ```

   ```json
   { "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](https://bimpsoft.com/en/help/sales/customer-order/):

   ```bash
   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`:

```bash
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](https://bimpsoft.com/en/help/developers/api-limits/). Mapping Bimp objects to your system is covered in [External IDs](https://bimpsoft.com/en/help/developers/api-external-ids/). All methods are in the [API reference](https://bimpsoft.com/en/help/developers/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`.

## FAQ

**Can I use my main account for the API?**

No. Create a separate user for the API. If the integration signs in with the same account as a person, that user's session in Bimp ends automatically. The subscription for an API user is paid at standard rates.

**How long is an API access token valid?**

The access token (both the base token and the company token) is valid for 1 hour, the refresh token for 1 week. When the access token expires, call /org2/auth/api-refresh; when the refresh token expires too, sign in again via /org2/auth/api-login.

**Which header should I use for the token: access-token or Authorization?**

According to the OpenAPI specification, the access-token header. Old notes mentioned Authorization: Bearer, but the specification describes only an apiKey scheme with the access-token header.

**Where can I find the full description of the methods?**

In the method reference on the resource pages, and in the interactive documentation at https://app.bimpsoft.com/docs.