# 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](https://docs.api.lensing.ai/?op=createVendor)

## 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:

```json
{
  "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

- `Idempotency-Replayed` — Present and `true` only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as `false`.

## Errors

| Code | Status |
| --- | --- |
| `REFERENCE_NOT_FOUND` | 400 |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 |
| `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 |

## Statuses

- `400` — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `409` — The Idempotency-Key is still being processed by another request.
- `422` — The Idempotency-Key was already used with a different request payload.
- `429` — Too many requests
- `500` — Internal server error