Creates a vendor.

POST /accounting/vendors

Group: Accounting › Vendors · Operation ID: createVendor

Creating a vendor also creates the business partner record that the rest of finance posts against, named after the vendor. There is no business-partner field to set. The response contains only the new vendor's id. Read the record with GET accounting/vendors/:id. vendorNumber comes from a gapless number range and appears only on that follow-up read. Bank details and the remittance address are optional and can also be added later with PATCH accounting/vendors/:id.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createVendorInput.

Field Type Required Description
vendorName string yes The name of the vendor.
vendorType string yes The kind of vendor. Accepted values: 'supplier', 'contractor', 'tax', 'benefits', 'payrollProvider', 'healthInsurance'.
status string yes The lifecycle status. Accepted values: 'active', 'inactive'.
paymentTerms string yes The default payment-terms key, for example 'net30', 'net60' or 'dueOnReceipt'. Stored as supplied.
vendorSubType string no A finer classification, used when vendorType is 'supplier'. Accepted values: 'direct', 'indirect'.
mainContactName string no The full name of the primary contact.
mainContactEmail string no The email address of the primary contact.
mainContactPhone string no The phone number of the primary contact.
billingEmail string no The email address invoices and billing messages are sent to.
preferredCurrency string no The preferred transaction currency. Format ISO 4217, for example 'USD'.
preferredLanguage string no The language the vendor prefers for messages.
independentContractor string no Whether the vendor is an independent contractor. Accepted values: 'yes', 'no', 'unsure'.
externalVendorId string no The identifier this vendor has in an external system. It is not unique.
origin string no The source system this record came from.
defaultAccountId string no The GL account expenses for this vendor default to. See id on GET accounting/accounts/:id.
departmentId string no The department costs for this vendor default to. See id on GET departments/:id.
vendorEntityId string no The legal entity this vendor belongs to. See id on GET base/entities.
bankDetails object no The bank account the vendor is paid into. Optional. You can add it later with PATCH accounting/vendors/:id.
bankDetails.bankAccountNumber string no The vendor's bank account number, or IBAN.
bankDetails.bankAccountType string no The kind of bank account, as your tenant's account-type list spells it.
bankDetails.bankAccountHolderName string no The name the account is held in.
bankDetails.bankAccountNumberType string no How to read bankAccountNumber. One of 'iban', 'achOrWire' or 'other'.
bankDetails.financialInstitutionId string no The bank's identifier, a BIC, SWIFT or routing number.
bankDetails.financialInstitutionIdType string no How to read financialInstitutionId.
remittanceAddress object no The address remittance advice is sent to. Optional. You can add it later with PATCH accounting/vendors/:id.
remittanceAddress.line1 string yes The first address line: street number and name, or PO box.
remittanceAddress.line2 string no The second address line: apartment, suite, unit, building or floor.
remittanceAddress.city string yes The city or locality.
remittanceAddress.stateProvince string no The state, province or region.
remittanceAddress.zipCode string yes The postal or ZIP code.
remittanceAddress.country string yes The country, as a name or ISO 3166-1 code.
remittanceAddress.attention string no The person or department that mail to this address is for.
attachments array of object no The files to attach to the vendor. Each names an already-uploaded file by its id.
attachments[].fileName string yes The display name of the attached file.
attachments[].fileId string yes The identifier of the already-uploaded file.

Example:

{
  "vendorName": "Acme GmbH",
  "vendorType": "supplier",
  "status": "active",
  "paymentTerms": "net30",
  "vendorSubType": "<vendorSubType>",
  "mainContactName": "Dana Fischer",
  "mainContactEmail": "<mainContactEmail>",
  "mainContactPhone": "<mainContactPhone>",
  "billingEmail": "<billingEmail>",
  "preferredCurrency": "EUR",
  "preferredLanguage": "<preferredLanguage>",
  "independentContractor": "<independentContractor>",
  "externalVendorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "origin": "<origin>",
  "defaultAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "departmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vendorEntityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "bankDetails": {
    "bankAccountNumber": "<bankAccountNumber>",
    "bankAccountType": "<bankAccountType>",
    "bankAccountHolderName": "<bankAccountHolderName>",
    "bankAccountNumberType": "<bankAccountNumberType>",
    "financialInstitutionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "financialInstitutionIdType": "<financialInstitutionIdType>"
  },
  "remittanceAddress": {
    "line1": "<line1>",
    "line2": "<line2>",
    "city": "<city>",
    "stateProvince": "<stateProvince>",
    "zipCode": "<zipCode>",
    "country": "<country>",
    "attention": "<attention>"
  },
  "attachments": [
    {
      "fileName": "<fileName>",
      "fileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ]
}

Response

200 Success

Under data (createVendorOutput):

Field Type Required Description
id string yes The unique identifier for the created vendor.

Response headers

Errors

Code Status
REFERENCE_NOT_FOUND 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses