API - Customers

Overview

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

Creating, changing and deleting customers

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 sales on the customer.

Data

Field List

Object Example

An example of one object:

{
    "number": "01121212",
    "systemId": "8ad0189f-dd11-ef11-9f8b-6045bde9cc61",
    "name": "Spotsmeyer's Furnishings",
    "name2": "",
    "addressLine1": "612 South Sunset Drive",
    "addressLine2": "",
    "postalCode": "US-FL 37125",
    "city": "Miami",
    "state": "FL",
    "country": "US",
    "contact": "Mr. Mike Nash",
    "email": "",
    "salespersonCode": "OF",
    "genBusPostingGroup": "EXPORT",
    "customerPostingGroup": "FOREIGN",
    "currencyCode": "USD",
    "billToCustomerId": "9cd0189f-dd11-ef11-9f8b-6045bde9cc61",
    "billToCustomerNo": "01454545",
    "customerPriceGroup": "",
    "blocked": " ",
    "paymentMethodCode": "",
    "paymentTermsCode": "1M(8D)",
    "salesType": " ",
    "placeOfDelivery": "",
    "eulerID": "",
    "addRef": "",
    "paymentBankAccount": "",
    "ediCustomerCode": "",
    "systemRowVersion": 2578841,
    "lastModified": "2025-09-24T10:44:09.453Z"
}

Procedures

Procedures are called on a specific customer: POST customers('<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 customer. 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
.../customers([record-id])/Microsoft.NAV.AddNote

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

Possible errors:

• The customer 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
.../customers([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 customer 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 customers

Read all entries

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

GET
.../customers

Read a specific entry

To read customer number ‘01121212’:

GET
.../customers('01121212')

Read export customers

Reads the customers with sales type Export, and returns only a few fields with $select.

Request:

GET .../customers?$filter=salesType eq 'Export'&$select=number,name,country,currencyCode

Response:

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/customers(number,name,country,currencyCode)",
    "value": [
        {
            "@odata.etag": "W/\"JzE5OzYxMjM0NTk4NzEyMzQ1Njc4OTAxOzAwOyc=\"",
            "number": "01454545",
            "name": "New Concepts Furniture",
            "country": "US",
            "currencyCode": "USD"
        }
    ]
}

Create, change and delete customers

Insert a Customer

Creates customer 007 with the fields needed to post sales on the customer.

Request:

POST
.../customers

Body:
{
    "number": "007",
    "name": "The Double O Seven Agency",
    "contact": "Mr. James Bond",
    "salespersonCode": "OF",
    "genBusPostingGroup": "EXPORT",
    "customerPostingGroup": "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)/customers/$entity",
    "@odata.etag": "W/\"JzE5OzI5ODc2NTQzMjEwOTg3NjU0MzIxOzAwOyc=\"",
    "systemId": "5b2e7c41-1a2b-f011-b01d-f992b2580806",
    "number": "007",
    "name": "The Double O Seven Agency",
    "contact": "Mr. James Bond",
    "salespersonCode": "OF",
    "genBusPostingGroup": "EXPORT",
    "customerPostingGroup": "FOREIGN",
    "currencyCode": "USD",
    "blocked": " ",
    "paymentTermsCode": "1M(8D)",
    "systemRowVersion": 2582101,
    "lastModified": "2025-12-18T15:40:12.527Z"
}

Change a customer

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

Request:

PATCH .../customers('007')
If-Match: *

Body:
{
    "email": "james.bond@example.com"
}

Response (shortened):

{
    "@odata.context": "https://containers.wisefish.com/BC/api/wisefish/base/v1.0/$metadata#companies(cf9f7b85-dd11-ef11-9f8b-6045bde9cc61)/customers/$entity",
    "@odata.etag": "W/\"JzE5OzQ0NTU2Njc3ODg5OTAwMTEyMjMzOzAwOyc=\"",
    "systemId": "5b2e7c41-1a2b-f011-b01d-f992b2580806",
    "number": "007",
    "name": "The Double O Seven Agency",
    "contact": "Mr. James Bond",
    "email": "james.bond@example.com",
    "systemRowVersion": 2582130,
    "lastModified": "2025-12-18T15:52:40.118Z"
}

Delete a customer

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

DELETE .../customers('007')

Add notes

Add a Note to a Customer

Adds the note “Prefers delivery on Mondays” to customer 01121212 with AddNote; the note is registered as from the API user.

Request:

POST .../customers('01121212')/Microsoft.NAV.AddNote

Body:
{
    "noteText": "Prefers delivery on Mondays"
}

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 Customer from a specific User

Adds the same note to customer 01121212 with AddNoteFromUser, registered as from user JOHN.

Request:

POST .../customers('01121212')/Microsoft.NAV.AddNoteFromUser

Body:
{
    "noteText": "Prefers delivery on Mondays",
    "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"
}