This API enables syncing suppliers, orders, contract links, and invoices from external systems to ISPnext via dedicated endpoints. It requires authentication via VL_API to obtain access and renewal tokens. The API supports sending complete data arrays for suppliers, orders with lines, invoice-order-contract links, and invoices with lines, ensuring unique external IDs and ISO-8601 date formats. Responses include JSON error messages for validation.
This API functionality enables sending suppliers, orders, contract links and invoices from external systems to ISPnext. The goal is to make integrations simpler, more consistent and better manageable by using clear, separate connector endpoints instead of one generic API call.
When do you use it?
This API is used when data from an external system needs to be synchronised towards ISPnext, such as:
- creating or updating suppliers;
- sending orders including order lines;
- linking orders to contracts;
- registering invoices and invoice lines.
Examples:
- ERP automatically sends new suppliers to ISPnext;
- Purchase orders are transferred to ISPnext in real time;
- Contract links are automatically applied upon receipt of invoices.
How does it work?
1. Authentication
Before any of the connector endpoints can be used, authentication is mandatory. This uses the VL_API authentication endpoint, which returns an accessToken and renewalToken.
❗
Note:
The examples below show example URLs.
For example: https://XXX.vendorlink.nl/API/
It is important that the XXX is replaced by the actual application server identity.
If you normally log in at: https://app.vendorlink.nl/client, then the application server identity is app.
The URL for API use is then: https://app.vendorlink.nl/API/.......
Login
Endpoint
POST https://XXX.vendorlink.nl/API/auth/login
Body
JSON
{
"u": "username",
"p": "password"
}Possible responses
1. Authentication successful
{
"userId": 9999999,
"displayName": "Demo User",
"accessToken": "string",
"renewalToken": "string",
"hostname": "XXX.vendorlink.nl"
}2. Re-authentication on another server required
{
"hostname": "ZZZ.vendorlink.nl"
}Explanation
- The field accessToken must be used in all subsequent API calls.
- The renewalToken can be used once to request a new accessToken.
- An accessToken expires after 60 minutes.
- A renewalToken expires after 14 days.
ExtendToken
Endpoint
POST https://XXX.vendorlink.nl/API/auth/extendtoken
Headers
Authorization: Bearer <accessToken> Content-Type: application/json; charset=utf8
Body
{
"rToken": "string"
}Response
{
"userId": 9999999,
"displayName": "Demo User",
"accessToken": "string",
"renewalToken": "string"
}1. Supplier Connector
Endpoint
POST https://XXX.vendorlink.nl/api/Connector/Suppliers
Model fields
| Field | Type | Description |
|---|---|---|
| SupplierName | string (100) | Name of the supplier |
| SupplierExternalId | string (50) | Unique reference based on possible source system (can be empty) |
| SupplierAddressStreet | string (250) | Street name |
| SupplierAddressNum | string | House number |
| SupplierAddressNumAdd | string | Addition |
| SupplierAddressZipCode | string (15) | Postal code |
| SupplierAddressTown | string (250) | City |
| SupplierAddressCountry | string | Country code |
| SupplierVatCode | string | VAT number |
| SupplierKvkCode | string | Trade register number |
| SupplierDunsNumber | string | DUNS number |
| SupplierTel | string | Telephone number |
| SupplierFax | string | Fax number |
| SupplierOrderEmail | string | Order email address |
| SupplierBankAccount | string | IBAN |
| SupplierRatingNorm | string | Rating |
| SupplierWebsiteUrl | string | Website URL |
| SupplierTypeExternalId | string | External ID for type |
| SupplierCommodityExternalId | string | External ID for commodity |
| SupplierProductGroupExternalId | string (15) | External product group |
| SupplierClassificationExternalId | string | External classification |
Example request
[
{
"SupplierName": "Supplier BV",
"SupplierExternalId": "SUP-EXT-123",
"SupplierAddressStreet": "Main Street",
"SupplierAddressNum": "100",
"SupplierAddressNumAdd": "A",
"SupplierAddressZipCode": "1234 AB",
"SupplierAddressTown": "Amsterdam",
"SupplierAddressCountry": "NL",
"SupplierVatCode": "NL123456789B01",
"SupplierKvkCode": "12345678",
"SupplierDunsNumber": "123456789",
"SupplierTel": "+31 20 1234567",
"SupplierOrderEmail": "orders@supplier.com",
"SupplierBankAccount": "NL91ABNA0417164300",
"SupplierRatingNorm": "A",
"SupplierWebsiteUrl": "https://www.supplier.com",
"SupplierTypeExternalId": "TYPE-001",
"SupplierCommodityExternalId": "COMM-001",
"SupplierProductGroupExternalId": "PG-001",
"SupplierClassificationExternalId": "CLASS-001"
}
]2. Order Connector
Endpoint
POST https://XXX.vendorlink.nl/api/Connector/Orders
Model fields – Order
| Field | Type |
|---|---|
| OrderId | string (50) |
| OrderReference | string (50) |
| CreationDate | DateTime |
| SupplierReference | string (50) |
| SupplierName | string (100) |
| UserName | string (250) |
| UserMailAddress | string (255) |
| UserId | string (25) |
| AmountExcl | decimal |
| AmountVat | decimal |
| AmountInc | decimal |
| CompanyName | string (100) |
| ContractId | string (numeric cast to long) |
| OrderType | string (50) |
| OrderLines | array |
Order line fields
| Field | Type |
|---|---|
| ProductReference | string (50) |
| ProductName | string (200) |
| CostCentreReference | string (20) |
| CostCentreName | string (100) |
| CostTypeReference | string (20) |
| CostTypeName | string (100) |
| Unit | string (50) |
| Quantity | double |
| AmountExclVat | double |
| AmountInclVat | double |
| DeliveryDate | DateTime |
| ProductGroupReference | string (50) |
Example request
[
{
"OrderId": "ORD-2024001",
"OrderReference": "REF-001",
"CreationDate": "2024-05-01T00:00:00",
"SupplierReference": "SUP-EXT-123",
"SupplierName": "Supplier BV",
"UserName": "John Doe",
"UserMailAddress": "john.doe@example.com",
"UserId": "USER123",
"AmountExcl": 1000.00,
"AmountVat": 210.00,
"AmountInc": 1210.00,
"CompanyName": "Company BV",
"ContractId": "12345",
"OrderType": "Standard",
"OrderLines": [
{
"OrderId": "ORD-2024001",
"OrderLineId": "1",
"ProductReference": "PROD-001",
"ProductName": "Product A",
"SupplierReference": "SUP-EXT-123",
"SupplierName": "Supplier BV",
"ProductGroup": "Group A",
"CostCentreReference": "CC-01",
"CostCentreName": "Cost Centre 1",
"CostTypeReference": "T1",
"CostTypeName": "Type 1",
"Unit": "pieces",
"ProductPrice": 100.00,
"Quantity": 10,
"AmountExclVat": 1000.00,
"AmountInclVat": 1210.00,
"DeliveryDate": "2024-05-15T00:00:00",
"Received": 0,
"ProductGroupReference": "PG-01"
}
]
}
]3. Invoice–Order–Contract Connector
Endpoint
POST https://XXX.vendorlink.nl/api/Connector/InvoiceOrderContracts
Model fields
- SupplierExternalId
- InvoiceOrderNumber
- ContractNumber
- ContractNumber2
- ContractNumber3
Example request
[
{
"SupplierExternalId": "SUP-EXT-123",
"InvoiceOrderNumber": "ORD-001",
"ContractNumber": "CN-001",
"ContractNumber2": "CN-002",
"ContractNumber3": "CN-003"
}
]4. Invoice Connector
Endpoint
POST https://XXX.vendorlink.nl/api/Connector/Invoices
Model fields – Invoice
Contains general invoice data such as invoice number, date, supplier, company and invoice lines.
Model fields – Invoice line
Includes e.g. cost centre information, article numbers, contract references, amounts and currency.
Example request
[
{
"InvoiceNumber": "INV-2024001",
"InvoiceNumberSupplier": "SUP-001",
"InvoiceCreateDate": "2024-05-01T00:00:00",
"InvoiceDate": "2024-05-01T00:00:00",
"InvoicePayDate": "2024-05-15T00:00:00",
"InvoiceWorkFlow": 1,
"InvoiceSupplierExternalId": "SUP-EXT-123",
"InvoiceSupplierName": "Supplier BV",
"InvoiceCompanyReference": "COMP-REF-1",
"InvoiceCompany": "Company BV",
"InvoiceOrderLog": "Order log text",
"InvoiceLines": [
{
"InvoiceLineNumber": "1",
"InvoiceLineDesc": "Product A",
"InvoiceLineSupplierReference": "SUP-EXT-123",
"InvoiceLineSupplierName": "Supplier BV",
"InvoiceDate": "2024-05-01T00:00:00",
"InvoiceOrderNumber": "ORD-001",
"InvoiceCostCentreCode": "CC-01",
"InvoiceCostCentreDesc": "Cost Centre 1",
"InvoiceCostCentreGroupCode": "G1",
"InvoiceCostCentreGroupDesc": "Group 1",
"InvoiceCostTypeCode": "T1",
"InvoiceCostTypeDesc": "Type 1",
"InvoiceCostUnitCode": "U1",
"InvoiceCostUnitDesc": "Unit 1",
"InvoiceCommodityCode": "C1",
"InvoiceCommodityDesc": "Commodity 1",
"InvoiceProjectCode": "P1",
"InvoiceProjectDesc": "Project 1",
"InvoiceProductCode": "PR1",
"InvoiceProductDesc": "Product 1",
"InvoiceContractCode": "CN1",
"InvoiceContractDesc": "Contract 1",
"InvoicePurchaserCode": "PU1",
"InvoicePurchaserDesc": "Purchaser 1",
"InvoiceAmountEx": 100.00,
"InvoiceAmountVat": 21.00,
"InvoiceAmountIn": 121.00,
"InvoiceCurrency": "EUR"
}
]
}
]Practical tips
- Ensure external IDs remain unique and consistent.
- Invoice lines must always have correct cost centre and cost units.
- For orders: ensure that OrderId remains exactly the same everywhere, including in the order lines.
Common mistakes
Mistake 1: missing mandatory fields
Some systems only send changed values. The API requires complete records.
Some systems only send changed values. The API requires complete records.
Mistake 2: incorrect date format
All dates must be ISO‑8601:
All dates must be ISO‑8601:
YYYY-MM-DDTHH:MM:SS.Mistake 3: contract number not numeric
ContractId is cast to long where possible.
ContractId is cast to long where possible.
Frequently asked questions
Should an endpoint receive a single object or an array?
All APIs accept arrays as the root object.
All APIs accept arrays as the root object.
Are records overwritten or updated?
This depends on the logic per environment. Often it is determined via SupplierExternalId or OrderId whether an item is new or an update.
This depends on the logic per environment. Often it is determined via SupplierExternalId or OrderId whether an item is new or an update.
Is validation logging available?
Error messages are returned as JSON response.
Error messages are returned as JSON response.