Counterparties: Bimp API methods
Bimp API methods for the “Counterparties” resource (/org2/counterparty/…): 14 methods. Base URL: https://app.bimpsoft.com. All requests except login pass the company token in the access-token header — see Getting started with the API.
| Method | What it does |
|---|---|
POST /org2/counterparty/api-insert | A request to create a new counterparty |
POST /org2/counterparty/api-update | A request to update an existing counterparty |
POST /org2/counterparty/api-updateAddresses | A request to update the counterparty’s addresses |
POST /org2/counterparty/api-readStatuses | A request to read the counterparty’s addresses |
POST /org2/counterparty/api-readList | A request to view a list of company’s counterparties |
POST /org2/counterparty/api-updateStatus | A request to update the counterparty’s status |
POST /org2/counterparty/api-read | A request to obtain detailed information for a particular counterparty |
POST /org2/counterparty/api-readAdditionalCharacteristics | A request to obtain additional characteristics of counterparties |
POST /org2/counterparty/api-saveExternalId | Creates or updates the mapping between a counterparty and an external system ID (e.g., website user ID). |
POST /org2/counterparty/api-readExternalId | Retrieves the external system ID for a specific counterparty given the source system name. |
POST /org2/counterparty/api-readByExternalId | Identifies a counterparty by their external system ID. Returns null if no mapping exists. |
POST /org2/counterparty/api-readExternalIdsList | Retrieves a paginated list of existing mappings with optional filtering by source or counterparty. |
POST /org2/counterparty/api-readWithoutExternalId | Retrieves a list of counterparties that do not have a mapping for the specified source system. |
POST /org2/counterparty/api-deleteExternalId | Removes the mapping for a specific counterparty. If source is omitted, deletes all external mappings for this counterparty. |
api-insert
POST /org2/counterparty/api-insert
A request to create a new counterparty
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Counterparty name |
managerUuid | string (uuid) | A unique identifier for the Manager, obtainable from the /user/api-readList request | |
AdditionalIdentifier | string | Additional field about counterparty | |
statusUuid | string (uuid) | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request | |
isCustomer | boolean | yes | Is he a customer? By default it is set to true |
isSupplier | boolean | yes | Is he a supplier? |
isSoleProprietor | boolean | yes | Is he a sole proprietor? |
email | string (email) | Counterparty email | |
phoneNumber | string | Counterparty phone number | |
vat | string | The total amount of Value Added Tax (VAT) applied | |
printFormName | string | The name of the counterparty that will be displayed in printed documents. If the field is not filled in, the name field is duplicated | |
edrpou | string | Counterparty edrpou | |
sourceOfAttractionUuid | string (uuid) | ||
contacts | object[] | ||
contacts[].post | string | yes | Counterparty post |
contacts[].name | string | yes | Counterparty name |
contacts[].isMain | boolean | yes | Is it the main contact? |
contacts[].phoneNumber | string | yes | Counterparty phone number |
bankAccounts | object[] | ||
bankAccounts[].iban | string | yes | Bank account iban |
bankAccounts[].isMain | boolean | yes | Is it the main bank account? |
bankAccounts[].currencyUuid | string (uuid) | yes | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
bankAccounts[].bankAccountTypeUuid | string (uuid) | yes | A unique identifier for the Bank account type, obtainable from the /bankAccounts/api-readTypes request |
addresses | object[] | ||
addresses[].value | string | yes | Address name |
addresses[].addressTypeUuid | string (uuid) | yes | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |
additionalCharacteristics | object[] | ||
additionalCharacteristics[].vaule | string | yes | Additional characteristic name |
additionalCharacteristics[].additionalCharacteristicTypeUuid | string (uuid) | yes | Additional characteristic type |
createContract | boolean | Need to automatically create a contract? | |
integration | object | The object is filled if created from integration system | |
integration.system | string (uuid) | yes | The integration system through which the element was created |
integration.externalId | string | yes | Unique element code from the integration system |
Response: data field
| Field | Type | Description |
|---|---|---|
uuid | string (uuid) |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-insert' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"name":"string","isCustomer":true,"isSupplier":false,"isSoleProprietor":false}'api-update
POST /org2/counterparty/api-update
A request to update an existing counterparty
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
uuid | string (uuid) | yes | A unique uuid key of the counterparty to update |
name | string | Counterparty name | |
managerUuid | string (uuid) | A unique identifier for the Manager, obtainable from the /user/api-readList request | |
AdditionalIdentifier | string | Additional field about counterparty | |
statusUuid | string (uuid) | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request | |
isCustomer | boolean | Is he a customer? | |
isSupplier | boolean | Is he a supplier? | |
isSoleProprietor | boolean | Is he a sole proprietor? | |
email | string (email) | Counterparty email | |
phoneNumber | string | Counterparty phone number | |
vat | string | The total amount of Value Added Tax (VAT) applied | |
printFormName | string | The name of the counterparty that will be displayed in printed documents. | |
edrpou | string | Counterparty edrpou | |
sourceOfAttractionUuid | string (uuid) | ||
contacts | object[] | ||
contacts[].post | string | yes | Counterparty post |
contacts[].name | string | yes | Counterparty name |
contacts[].isMain | boolean | yes | Is it the main contact? |
contacts[].phoneNumber | string | yes | Counterparty phone number |
bankAccounts | object[] | ||
bankAccounts[].iban | string | yes | Bank account iban |
bankAccounts[].isMain | boolean | yes | Is it the main bank account? |
bankAccounts[].currencyUuid | string (uuid) | yes | A unique identifier for the Currency, obtainable from the /currency/api-readList request |
bankAccounts[].bankAccountTypeUuid | string (uuid) | yes | A unique identifier for the Bank account type, obtainable from the /bankAccounts/api-readTypes request |
addresses | object[] | ||
addresses[].value | string | yes | Address name |
addresses[].addressTypeUuid | string (uuid) | yes | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |
additionalCharacteristics | object[] | ||
additionalCharacteristics[].vaule | string | yes | Additional characteristic name |
additionalCharacteristics[].additionalCharacteristicTypeUuid | string (uuid) | yes | Additional characteristic type |
createContract | boolean | Need to automatically create a contract? | |
integration | object | The object is filled if created from integration system | |
integration.system | string (uuid) | yes | The integration system through which the element was created |
integration.externalId | string | yes | Unique element code from the integration system |
Response: data field
| Field | Type | Description |
|---|---|---|
uuid | string (uuid) |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-update' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"uuid":"00000000-0000-0000-0000-000000000000"}'api-updateAddresses
POST /org2/counterparty/api-updateAddresses
A request to update the counterparty’s addresses
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
counterpartyUuid | string (uuid) | yes | A unique identifier for a counterparty of type ‘isCustomer’.You can retrieve this UUID using the /counterparty/api-readList request |
addresses | object[] | yes | |
addresses[].value | string | yes | Address name |
addresses[].addressTypeUuid | string (uuid) | yes | A unique identifier for the Address type, obtainable from the /addressType/api-readList request |
Response: data field
| Field | Type | Description |
|---|---|---|
uuid | string (uuid) |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-updateAddresses' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"counterpartyUuid":"00000000-0000-0000-0000-000000000000","addresses":[{}]}'api-readStatuses
POST /org2/counterparty/api-readStatuses
A request to read the counterparty’s addresses
Response: data field
| Field | Type | Description |
|---|---|---|
[].uuid | string (uuid) | |
[].name | string | |
[].color | string | |
[].priority | number |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readStatuses' \
-H 'access-token: <company token>'api-readList
POST /org2/counterparty/api-readList
A request to view a list of company’s counterparties
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
pagination | object | yes | |
pagination.offset | number | yes | Begin from {offset} elements |
pagination.count | number | yes | Limit of paginated elemets |
periodable | object[] | Period range as a tuple of two ISO 8601 date-time strings in UTC (e.g. ‘2012-10-05T14:48:00.000Z’) | |
edrpou | string | Filter by edrpou | |
email | string | Filter by email | |
phoneNumber | string | Filter by phone number | |
individualTaxNumber | string | Filter by individual tax number | |
name | string | Filter by name | |
types | string (“isCustomer”, “isSupplier”, “isSoleProprietor”)[] | ||
integration | object | The object is filled in for integration search | |
integration.system | string (uuid) | yes | The integration system through which the element was created |
integration.externalId | string | yes | Unique element code from the integration system |
Response: data field
| Field | Type | Description |
|---|---|---|
[].uuid | string (uuid) | |
[].name | string | |
[].edrpou | string | |
[].individualTaxNumber | string | |
[].email | string | |
[].phoneNumber | string | |
[].isCustomer | boolean | Чи покупець |
[].isSupplier | boolean | Чи постачальник |
[].isSoleProprietor | boolean | Чи ФОП |
[].code | string | |
[].printName | string | |
[].addresses | object[] | |
[].addresses[].value | string | |
[].addresses[].isMain | boolean | |
[].addresses[].type | object | |
[].addresses[].type.name | string | |
[].addresses[].type.GUID | string (uuid) | |
[].addresses[].type.type | number |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readList' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"pagination":{"offset":0,"count":10}}'api-updateStatus
POST /org2/counterparty/api-updateStatus
A request to update the counterparty’s status
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
counterpartyUuid | string (uuid) | yes | A unique identifier for a counterparty of type ‘isCustomer’.You can retrieve this UUID using the /counterparty/api-readList request |
statusUuid | string (uuid) | yes | A unique identifier for the Status of counterparty, obtainable from the /counterparty/api-readStatuses request |
Response: data field
| Field | Type | Description |
|---|---|---|
uuid | string (uuid) |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-updateStatus' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"counterpartyUuid":"00000000-0000-0000-0000-000000000000","statusUuid":"00000000-0000-0000-0000-000000000000"}'api-read
POST /org2/counterparty/api-read
A request to obtain detailed information for a particular counterparty
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
uuid | string (uuid) | yes | A unique uuid key of the counterparty |
Response: data field
| Field | Type | Description |
|---|---|---|
uuid | string (uuid) | |
name | string | |
edrpou | string | |
individualTaxNumber | string | |
email | string | |
phoneNumber | string | |
isCustomer | boolean | Чи покупець |
isSupplier | boolean | Чи постачальник |
isSoleProprietor | boolean | Чи ФОП |
code | string | |
printName | string | |
addresses | object[] | |
addresses[].value | string | |
addresses[].isMain | boolean | |
addresses[].type | object | |
addresses[].type.name | string | |
addresses[].type.GUID | string (uuid) | |
addresses[].type.type | number |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-read' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"uuid":"00000000-0000-0000-0000-000000000000"}'api-readAdditionalCharacteristics
POST /org2/counterparty/api-readAdditionalCharacteristics
A request to obtain additional characteristics of counterparties
Response: data field
| Field | Type | Description |
|---|---|---|
[].name | string | |
[].uuid | string (uuid) |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readAdditionalCharacteristics' \
-H 'access-token: <company token>'api-saveExternalId
POST /org2/counterparty/api-saveExternalId
Creates or updates the mapping between a counterparty and an external system ID (e.g., website user ID).
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
counterpartyUuid | string (uuid) | yes | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
source | string | yes | Identifier of the external system (e.g., “prom”, “rozetka”). The value is case-insensitive and automatically normalized (trimmed and converted to lowercase). |
externalId | string | yes | Unique identifier of the counterparty in the external system (e.g., user ID on the website, database key, login). |
Response: data field
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates whether the mapping between the BIMP Counterparty and the external system ID was successfully established. |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-saveExternalId' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"counterpartyUuid":"00000000-0000-0000-0000-000000000000","source":"string","externalId":"string"}'api-readExternalId
POST /org2/counterparty/api-readExternalId
Retrieves the external system ID for a specific counterparty given the source system name.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
counterpartyUuid | string (uuid) | yes | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
source | string | yes | Identifier of the external system (e.g. “prom”) to check against. |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readExternalId' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"counterpartyUuid":"00000000-0000-0000-0000-000000000000","source":"string"}'api-readByExternalId
POST /org2/counterparty/api-readByExternalId
Identifies a counterparty by their external system ID. Returns null if no mapping exists.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
source | string | yes | Identifier of the external system (e.g. “prom”) to check against. |
externalId | string | yes | Unique identifier of the counterparty in the external system (e.g., user ID on the website, database key, login). |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readByExternalId' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"source":"string","externalId":"string"}'api-readExternalIdsList
POST /org2/counterparty/api-readExternalIdsList
Retrieves a paginated list of existing mappings with optional filtering by source or counterparty.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
pagination | object | yes | |
pagination.offset | number | yes | Begin from {offset} elements |
pagination.count | number | yes | Limit of paginated elemets |
source | string | Identifier of the external system (e.g. “prom”) to check against. | |
counterpartyUuid | string (uuid) | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
Response: data field
| Field | Type | Description |
|---|---|---|
[].counterpartyUuid | string (uuid) | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
[].name | string | |
[].source | string | |
[].externalId | string |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readExternalIdsList' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"pagination":{"offset":0,"count":10}}'api-readWithoutExternalId
POST /org2/counterparty/api-readWithoutExternalId
Retrieves a list of counterparties that do not have a mapping for the specified source system.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
pagination | object | yes | |
pagination.offset | number | yes | Begin from {offset} elements |
pagination.count | number | yes | Limit of paginated elemets |
source | string | yes | Identifier of the external system (e.g. “prom”) to check against. |
Response: data field
| Field | Type | Description |
|---|---|---|
[].counterpartyUuid | string (uuid) | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
[].name | string |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-readWithoutExternalId' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"pagination":{"offset":0,"count":10},"source":"string"}'api-deleteExternalId
POST /org2/counterparty/api-deleteExternalId
Removes the mapping for a specific counterparty. If source is omitted, deletes all external mappings for this counterparty.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
counterpartyUuid | string (uuid) | yes | A unique identifier for the Counterparty, obtainable from the /counterparty/api-readList request |
source | string | Identifier of the external system (e.g. “prom”) to check against. |
curl -X POST 'https://app.bimpsoft.com/org2/counterparty/api-deleteExternalId' \
-H 'access-token: <company token>' \
-H 'Content-Type: application/json' \
-d '{"counterpartyUuid":"00000000-0000-0000-0000-000000000000"}'Interactive documentation with a test request option: https://app.bimpsoft.com/docs. The OpenAPI specification is updated together with Bimp; this page is generated from it automatically.