Vendors

Download schema

deprecated

List vendors

GET

https://api.ledgerbee.com/api

/v1/vendors

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all vendors for your company, sorted by vendor number. Each vendor carries its full metadata map.

Pass metadata[key]=value query parameters to return only the vendors whose metadata carries every given key with exactly the given value (AND semantics, exact match, at most 10 pairs). A request with more than 10 pairs returns 400 with error code METADATA_TOO_MANY_FILTERS.

The unfiltered list is cached for 5 seconds; creating a vendor through this API invalidates the cache, so a just-created vendor is immediately visible. A filtered list is never cached, so a metadata change is visible on the next filtered read.

Pagination

The list is returned in full, as an array, unless you send cursor, page or limit. Sending any of them switches the response to a paginated object (data, total, page, limit, totalPages, nextCursor, hasMore); page and limit take their defaults when omitted. A paginated read is never cached.

To walk the whole list, send limit and then pass each response's nextCursor back as cursor, with the same filters, until hasMore is false. Paging by page is deprecated, and page cannot be sent with cursor (400 PAGINATION_CURSOR_WITH_PAGE). A cursor replayed with other filters is refused with 400 PAGINATION_INVALID_CURSOR. From 2026-12-31, a page past the first of a list with more than 10,000 items is refused with 400 PAGINATION_OFFSET_TOO_DEEP.

DEPRECATED — sunset on 2026-12-31 (RFC 8594; every response carries Deprecation/Sunset/Link headers). Migrate to the supplier endpoints under /api/v1/suppliers — identical shapes with supplier-named fields and SUPPLIER_* error codes.

Required Scope

suppliers-read

List vendors › query Parameters

object · style: deepObject · explode: true

Exact-match metadata filters in the form metadata[key]=value. Multiple pairs combine with AND semantics — a record matches only if it carries every given key with exactly the given value. At most 10 pairs per request.

cursor

string · maxLength: 4096

Opaque cursor from the previous response's nextCursor. Returns the items after it, in the same order. Send the same filters as the request that produced it, and do not send page. The preferred way to page through the list. Sending cursor, page or limit switches the response from the full array to a paginated object.

page

integer · min: 1 · max: 100000 · deprecated

Deprecated: page with cursor instead. Page number (1-indexed). Sending cursor, page or limit switches the response from the full array to a paginated object. When only limit or cursor is sent, page is 1.

limit

integer · min: 1 · max: 100

Number of items per page. Sending cursor, page or limit switches the response from the full array to a paginated object. When limit is omitted from a paginated request, it is 25.

List vendors › Responses

The full list of vendors matching the given filters, or one page of it when cursor, page or limit is sent

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = array
	type = object · requires: data, total, page +4 more

Properties for Variant 1:

VendorResponse[]

VendorResponse

id

string · required

The unique identifier of the vendor

Example: 550e8400-e29b-41d4-a716-446655440000

vendorNumber

string · required

Vendor number

Example: V001

name

string · required

Name of the vendor

Example: Acme Supplies

vendorGroupId

string · required

Vendor group ID

Example: 550e8400-e29b-41d4-a716-446655440001

currency

string · required

Currency code

Example: DKK

status

string · enum · required

Vendor status

Enum values:

active

inactive

archived

Example: active

vendorGroupName

string

Vendor group name

Example: Domestic Vendors

email

string

Email address

Example: contact@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

address

string

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

countryCode

string

Two-letter country code (ISO 3166-1 alpha-2)

Example: DK

vatNumber

string

VAT registration number

Example: DK12345678

attention

string

Attention field

Example: Accounts Payable

paymentTerms

number

Payment terms in days

Example: 30

openingBalance

number

Opening balance in the company base currency (signed: positive = we owe the vendor)

Example: 1000

object

Key-value metadata attached to the vendor

Example: {"erpVendorId":"V-10042","tier":"preferred"}

GET/v1/vendors

curl https://api.ledgerbee.com/api/v1/vendors \
  --header 'x-api-key: <api-key>'

Example Responses

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "vendorNumber": "V001",
    "name": "Acme Supplies",
    "vendorGroupId": "550e8400-e29b-41d4-a716-446655440001",
    "vendorGroupName": "Domestic Vendors",
    "email": "contact@acme-supplies.com",
    "phone": "+45 12345678",
    "address": "123 Main Street",
    "city": "Copenhagen",
    "postalCode": "2100",
    "countryCode": "DK",
    "vatNumber": "DK12345678",
    "currency": "DKK",
    "attention": "Accounts Payable",
    "paymentTerms": 30,
    "openingBalance": 1000,
    "status": "active",
    "metadata": {
      "erpVendorId": "V-10042",
      "tier": "preferred"
    }
  }
]

json

application/json

deprecated

Create a vendor

POST

https://api.ledgerbee.com/api

/v1/vendors

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Creates a vendor together with its contacts.

vendorNumber is trimmed and must be unique within your company — a duplicate returns 400 with error code VENDOR_NUMBER_ALREADY_EXISTS.

Exactly one contact must be marked as default. When you provide a single contact it is made the default automatically; otherwise a missing or duplicated default returns 400 with error code CONTACT_DEFAULT_REQUIRED or CONTACT_MULTIPLE_DEFAULTS.

vendorGroupId must reference an existing vendor group in your company (404 VENDOR_GROUP_NOT_FOUND), and defaultAccountId, when provided, must reference an existing ledger account (404 LEDGER_NOT_FOUND).

An optional metadata map (string keys to string values, at most 50 entries, keys up to 128 characters, values up to 500 characters) is stored with the vendor. An invalid map is rejected before the vendor is created, with error code METADATA_KEY_REQUIRED, METADATA_KEY_TOO_LONG, METADATA_VALUE_TOO_LONG, METADATA_DUPLICATE_KEY or METADATA_TOO_MANY_ENTRIES.

The response contains only the new vendor's id and vendorNumber; fetch the full record, including its metadata, via the list endpoint.

Required Scope

suppliers-write

Create a vendor › Headers

x-api-idempotency-key

string · maxLength: 255

Optional idempotency key for safely retrying mutating requests.

Create a vendor › Request Body

CreateVendorRequest

vendorNumber

string · required

Unique vendor number

Example: V001

name

string · required

Vendor name

Example: Acme Supplies

vendorGroupId

string · required

Vendor group ID

Example: 550e8400-e29b-41d4-a716-446655440001

currency

string · pattern: ^[A-Za-z]{3}$ · required

The currency this vendor bills us in, ISO 4217 alpha-3.

Example: DKK

countryCode

string · required

Two-letter country code

Example: DK

CreateVendorContactRequest[] · minItems: 1 · maxItems: 50 · required

Contacts for the vendor. At least one contact with isDefault: true is required.

email

string

Email address

Example: contact@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

address

string · maxLength: 255

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

vatNumber

string

VAT registration number

Example: DK12345678

attention

string

Attention field

Example: Accounts Payable

paymentTerms

number · min: 0

Payment terms in days

Example: 30

openingBalance

number

Opening balance in the company base currency, seeding payables that predate LedgerBee. Signed: positive = we owe the vendor, negative = a credit position.

Example: 1000

defaultAccountId

string

Default ledger account ID

Example: 550e8400-e29b-41d4-a716-446655440002

object

Key-value metadata to attach to the vendor. At most 50 entries; keys up to 128 characters, string values up to 500 characters. Read it back, or filter on it, through the list endpoint.

Example: {"erpVendorId":"V-10042"}

Create a vendor › Responses

Vendor created successfully

CreateVendorResponse

id

string · required

The unique identifier of the created vendor

Example: 550e8400-e29b-41d4-a716-446655440000

vendorNumber

string · required

Vendor number

Example: V001

POST/v1/vendors

curl https://api.ledgerbee.com/api/v1/vendors \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "vendorNumber": "V001",
  "name": "Acme Supplies",
  "vendorGroupId": "550e8400-e29b-41d4-a716-446655440001",
  "currency": "DKK",
  "countryCode": "DK",
  "email": "contact@acme-supplies.com",
  "phone": "+45 12345678",
  "address": "123 Main Street",
  "city": "Copenhagen",
  "postalCode": "2100",
  "vatNumber": "DK12345678",
  "attention": "Accounts Payable",
  "paymentTerms": 30,
  "openingBalance": 1000,
  "defaultAccountId": "550e8400-e29b-41d4-a716-446655440002",
  "contacts": [
    {
      "name": "John Doe",
      "email": "john.doe@acme-supplies.com",
      "phone": "+45 12345678",
      "isDefault": true
    }
  ],
  "metadata": {
    "erpVendorId": "V-10042"
  }
}'

Example Request Body

{
  "vendorNumber": "V001",
  "name": "Acme Supplies",
  "vendorGroupId": "550e8400-e29b-41d4-a716-446655440001",
  "currency": "DKK",
  "countryCode": "DK",
  "email": "contact@acme-supplies.com",
  "phone": "+45 12345678",
  "address": "123 Main Street",
  "city": "Copenhagen",
  "postalCode": "2100",
  "vatNumber": "DK12345678",
  "attention": "Accounts Payable",
  "paymentTerms": 30,
  "openingBalance": 1000,
  "defaultAccountId": "550e8400-e29b-41d4-a716-446655440002",
  "contacts": [
    {
      "name": "John Doe",
      "email": "john.doe@acme-supplies.com",
      "phone": "+45 12345678",
      "isDefault": true
    }
  ],
  "metadata": {
    "erpVendorId": "V-10042"
  }
}

json

application/json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "vendorNumber": "V001"
}

json

application/json

deprecated

List vendor contacts

GET

https://api.ledgerbee.com/api

/v1/vendors/{vendorId}/contacts

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all contacts for a vendor, with the default contact first and the rest sorted alphabetically by name.

Returns 404 with error code VENDOR_NOT_FOUND when the vendor does not exist in your company.

Required Scope

suppliers-read

List vendor contacts › path Parameters

vendorId

string · required

Vendor ID

List vendor contacts › Responses

List of contacts for a vendor

VendorContactResponse[]

VendorContactResponse

id

string · required

The unique identifier of the contact

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the contact

Example: John Doe

isDefaultForVendor

boolean · required

Whether this is the default contact for the vendor

Example: true

email

string

Email address

Example: john.doe@acme-supplies.com

phone

string

Phone number

Example: +45 12345678

deprecated

List vendor departments

GET

https://api.ledgerbee.com/api

/v1/vendors/{vendorId}/departments

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all departments for a vendor, with the default department first and the rest sorted alphabetically by name.

Returns 404 with error code VENDOR_NOT_FOUND when the vendor does not exist in your company.

Required Scope

suppliers-read

List vendor departments › path Parameters

vendorId

string · required

Vendor ID

List vendor departments › Responses

List of departments for a vendor

VendorDepartmentResponse[]

VendorDepartmentResponse

id

string · required

The unique identifier of the department

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the department

Example: Headquarters

isDefault

boolean · required

Whether this is the default department for the vendor

Example: true

isActive

boolean · required

Whether the department is active

Example: true

poNumber

string

Purchase order number

Example: PO-12345

eanNumber

string

EAN number for e-invoicing

Example: 5790000000000

address

string

Street address

Example: 123 Main Street

city

string

City

Example: Copenhagen

postalCode

string

Postal code

Example: 2100

countryCode

string

Two-letter country code (ISO 3166-1 alpha-2)

Example: DK

deprecated

List vendor groups

GET

https://api.ledgerbee.com/api

/v1/vendors/groups

x-api-key (header)

OAuth 2.0

Credential: a company's API key or OAuth token.

Retrieves all vendor groups for your company, sorted alphabetically by name.

The list is cached for 5 seconds.

Required Scope

suppliers-read

List vendor groups › Responses

List of vendor groups for the company

VendorGroupResponse[]

VendorGroupResponse

id

string · required

The unique identifier of the vendor group

Example: 550e8400-e29b-41d4-a716-446655440000

name

string · required

Name of the vendor group

Example: Domestic Vendors

description

string

Description of the vendor group

Example: All domestic vendor accounts

defaultAccountId

string

Default ledger account ID

Example: 550e8400-e29b-41d4-a716-446655440001

VAT periods Webhook Endpoints