API - Vendors

Overview

The list page that contains the Vendors. Similar API does exist in the standard BC, but since there are some added Wisefish fields in the table, a new API was created.

Creating, changing and deleting vendors

The API allows inserting, modifying and deleting entries. The same error handling applies as when the same is done within Business Central. Note that the fields marked “MANDATORY” in the list above are the fields that must be populated in order to post purchases on the vendor.

Data

Field List

Object Example

An example of one object:

{
    "number": "01254796",
    "systemId": "44e719a5-dd11-ef11-9f8b-6045bde9cc61",
    "name": "Progressive Home Furnishings",
    "name2": "",
    "addressLine1": "222 Reagan Drive",
    "addressLine2": "",
    "postalCode": "US-SC 27136",
    "city": "Colombia",
    "state": "",
    "country": "US",
    "contact": "Mr. Michael Sean Ray",
    "email": "",
    "purchaserCode": "RB",
    "genBusPostingGroup": "EXPORT",
    "vendorPostingGroup": "FOREIGN",
    "currencyCode": "USD",
    "payToVendorId": "00000000-0000-0000-0000-000000000000",
    "payToVendorNo": "",
    "pricesIncludingVat": false,
    "blocked": "_x0020_",
    "paymentMethodCode": "",
    "paymentTermsCode": "CM",
    "vendorType": " ",
    "bcTiInvoicing": false,
    "socialSecurityNumber": "",
    "certificationProcess": "From Vendor's Stock Center",
    "systemRowVersion": 2578902,
    "lastModified": "2024-05-14T10:35:16.083Z"
}

Procedures

Procedures are called on a specific vendor: POST vendors('<number>')/Microsoft.NAV.<procedureName> with a JSON body of parameters. Each procedure returns a text message in the value property of the response on success. On failure it returns an error with a readable message.

Parameter names are case-sensitive, and the procedure name starts with a capital letter (AddNote).

Notes

Add Note

The procedure AddNote adds a note to the vendor. The note is a Business Central Note record link with the description “Sent through API”, and it is registered as from the API user (the user making the call).

POST
.../vendors([record-id])/Microsoft.NAV.AddNote

Body:
{
    "noteText": [the text of the note]
}

Possible errors:

• The vendor does not exist (standard Business Central error, record not found).

• noteText is longer than 250 characters (standard Business Central error, the text exceeds the parameter length).

Behaviour notes:

• The note text is not validated: an empty noteText is not rejected, an empty note is added.

• The note is a Note type record link with the description “Sent through API”, created with the current date and time.

Notes can be read with the Record Notes API, see API - Record Notes in this space.

Add Note from a User

The procedure AddNoteFromUser works the same way as AddNote, but the note is registered as from the given Business Central user instead of the API user.

POST
.../vendors([record-id])/Microsoft.NAV.AddNoteFromUser

Body:
{
    "noteText": [the text of the note],
    "fromUser": [the BC user ID the note is registered from]
}

Possible errors:

• The vendor does not exist (standard Business Central error, record not found).

• A parameter is longer than its maximum length (standard Business Central error, the text exceeds the parameter length).

• User with ID <fromUser> does not exist (when fromUser is not found in User Setup)

Behaviour notes:

• fromUser is a code parameter, so the value is converted to upper case: "john" is registered and returned as JOHN.

• If fromUser is empty, no user check is made and the note is registered as from the API user (same as AddNote), but the response text then ends with an empty user ID: Note successfully added and registered from user .

• The note text is not validated: an empty noteText is not rejected.

Examples

Read vendors

Read all entries

Reads all vendors. The response is a list of vendor objects, as shown in Object Example.

GET
.../vendors

Read a specific entry

To read vendor number ‘01254796’:

GET
.../vendors('01254796')

Read producer vendors

Reads the vendors of type Producer, and returns only a few fields with $select.

Request:

GET .../vendors?$filter=vendorType eq 'Producer'&$select=number,name,vendorType,certificationProcess

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/vendors(number,name,vendorType,certificationProcess)",
    "value": [
        {
            "@odata.etag": "W/\"JzE5OzYxMjM0NTk4NzEyMzQ1Njc4OTAxOzAwOyc=\"",
            "number": "01587796",
            "name": "Nordic Fish Producers",
            "vendorType": "Producer",
            "certificationProcess": "Single Certification"
        }
    ]
}

Create, change and delete vendors

Insert a Vendor

Creates vendor HL with the fields needed to post purchases on the vendor.

Request:

POST
.../vendors

Body:
{
    "number": "HL",
    "name": "Hannibal Lechter",
    "purchaserCode": "OF",
    "genBusPostingGroup": "EXPORT",
    "vendorPostingGroup": "FOREIGN",
    "currencyCode": "USD",
    "paymentTermsCode": "1M(8D)"
}

Response (shortened):

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/vendors/$entity",
    "@odata.etag": "W/\"JzE5OzI5ODc2NTQzMjEwOTg3NjU0MzIxOzAwOyc=\"",
    "systemId": "6c3f8d52-2b3c-f011-b01d-f992b2580806",
    "number": "HL",
    "name": "Hannibal Lechter",
    "purchaserCode": "OF",
    "genBusPostingGroup": "EXPORT",
    "vendorPostingGroup": "FOREIGN",
    "currencyCode": "USD",
    "blocked": "_x0020_",
    "paymentTermsCode": "1M(8D)",
    "systemRowVersion": 2582101,
    "lastModified": "2025-12-18T15:40:12.527Z"
}

Change a vendor

Changes the email address of vendor HL. A PATCH request needs the If-Match header with the @odata.etag of the record (or *).

Request:

PATCH .../vendors('HL')
If-Match: *

Body:
{
    "email": "hannibal@example.com"
}

Response (shortened):

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/vendors/$entity",
    "@odata.etag": "W/\"JzE5OzQ0NTU2Njc3ODg5OTAwMTEyMjMzOzAwOyc=\"",
    "systemId": "6c3f8d52-2b3c-f011-b01d-f992b2580806",
    "number": "HL",
    "name": "Hannibal Lechter",
    "email": "hannibal@example.com",
    "systemRowVersion": 2582130,
    "lastModified": "2025-12-18T15:52:40.118Z"
}

Delete a vendor

Deletes vendor HL. The same checks apply as when a vendor is deleted in Business Central. On success the response is empty (HTTP status 204 No Content).

DELETE .../vendors('HL')

Add notes

Add a Note to a Vendor

Adds the note “New price list received” to vendor 01254796 with AddNote; the note is registered as from the API user.

Request:

POST .../vendors('01254796')/Microsoft.NAV.AddNote

Body:
{
    "noteText": "New price list received"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Note successfully added"
}

Add a Note to a Vendor from a specific User

Adds the same note to vendor 01254796 with AddNoteFromUser, registered as from user JOHN.

Request:

POST .../vendors('01254796')/Microsoft.NAV.AddNoteFromUser

Body:
{
    "noteText": "New price list received",
    "fromUser": "JOHN"
}

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#Edm.String",
    "value": "Note successfully added and registered from user JOHN"
}