Light APIv1.0.0

API / Reference / Vendors

Create vendor

POST https://api.light.inc/v1/vendors

Creates a new vendor

The resulting status depends on the company's vendor-approval workflow: with one published the vendor is created IN_REVIEW and must be approved in Light before it can be updated (VENDOR_PENDING_APPROVAL_UPDATE_NOT_ALLOWED); otherwise it is ACTIVE. Uniqueness is on name only (DUPLICATE_VENDOR); VAT id, IBAN and identifier may repeat. Bank details are validated by country (IBAN/BIC or domestic formats, errors pathed to the field); French vendors get their VAT number and SIREN cross-checked (VENDOR_INVALID_FRENCH_IDENTIFIERS). Missing contact fields (description, email, phoneNumber, address, ...) are back-filled from a lookup of website when given. type is always EXTERNAL; defaultCompanyEntity.companyEntityId is added to companyEntityIds automatically. Requires the vendor-management role.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Request body

application/json;charset=UTF-8

  • defaultCompanyEntity object

    Default company entity configuration for this vendor, if any.

    • companyEntityId string · uuid

      ID of the company entity.

    • accountId string · uuid

      ID of the ledger account to use for this vendor.

    • taxCodeId string · uuid

      ID of the tax code to use for this vendor.

    • costCenterId string · uuid

      ID of the cost center to use for this vendor.

    • senderBankAccountId string · uuid

      ID of the sender bank account to use for payments to this vendor.

  • companyEntityIds array of string · uuid

    IDs of the company entities this vendor is associated with.

  • vatId string

    Vendor VAT ID.

  • businessRegistrationNumber string

    Vendor business registration number.

  • identifier string

    Vendor identifier (external/system identifier).

  • name string

    Vendor name.

  • description string

    Vendor description or memo.

  • avatarUrl string

    Vendor avatar/logo URL.

  • email string

    Vendor email address.

  • phoneNumber object

    • countryCode string

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

    • localNumber string

      The number without the country code.

  • website string

    Vendor website.

  • country string

    Vendor country.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • city string

    Vendor city.

  • address string

    Vendor street address.

  • zipcode string

    Vendor ZIP/postal code.

  • bankName string

    Vendor bank name.

  • bankCountry string

    Vendor bank country.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • bankCity string

    Vendor bank city.

  • bankAddress string

    Vendor bank address.

  • bankZipcode string

    Vendor bank ZIP/postal code.

  • bankAccountNumber string

    Vendor bank account number (IBAN or local format).

  • bankAccountBic string

    Vendor bank BIC/SWIFT code.

  • domesticBankAccountNumber string

    Vendor domestic bank account number (country-specific format).

  • domesticBankAccountCode string

    Vendor domestic bank account code (e.g. routing/sort code).

  • swedishBankgiroNumber string

    Vendor Swedish Bankgiro number, if applicable.

  • swedishPlusgiroNumber string

    Vendor Swedish Plusgiro number, if applicable.

  • bankRecipientName string

    Name of the bank account holder. When set, this overrides the vendor name on the payment recipient for providers that consult it (currently Airwallex).

  • currency string

  • customProperties array of object

    List of custom properties to set on the vendor.

    • groupId string · uuid

    • valueIds array of string · uuid

      Catalogue value ids for this group. Required; send [] (with an empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

    • inlineValues array of string

      Literal values for TEXT, NUMERIC, BOOLEAN and DATE groups, as strings (yyyy-MM-dd for dates). Rejected on select groups with CUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes.

Response

  • type string

    Type of the vendor.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of EXTERNAL USER

  • vendorId string · uuid

    External ID of the vendor.

  • companyId string · uuid

    ID of the company this vendor belongs to.

  • companyEntityIds array of string · uuid

    IDs of the company entities this vendor is associated with.

  • defaultCompanyEntity object

    Default company entity configuration for this vendor, if any.

    The entity and the defaults (expense account, tax code, cost center, paying bank account) used when a bill from this vendor is created.

    • id string · uuid

      ID of the default company entity configuration.

    • vendorId string · uuid

      ID of the vendor.

    • companyEntityId string · uuid

      ID of the company entity.

    • accountId string · uuid

      ID of the ledger account to use for this vendor.

    • taxCodeId string · uuid

      ID of the tax code to use for this vendor.

    • costCenterId string · uuid

      ID of the cost center to use for this vendor.

    • senderBankAccountId string · uuid

      ID of the sender bank account to use for payments to this vendor.

    • createdAt string · date-time

      Timestamp when the configuration was created.

    • updatedAt string · date-time

      Timestamp when the configuration was last updated.

  • vatId string

    Vendor VAT ID.

  • businessRegistrationNumber string

    Vendor business registration number.

  • identifier string

    Vendor identifier (external/system identifier).

  • name string

    Vendor name.

  • description string

    Vendor description or memo.

  • avatarUrl string

    Vendor avatar/logo URL.

  • email string

    Vendor email address.

  • phoneNumber object

    The vendor's phone number. May be null. PUT /v1/vendors/{vendorId} is a full replacement, so leaving it out clears it.

    • countryCode string

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

    • localNumber string

      The number without the country code.

  • website string

    Vendor website.

  • country string

    Vendor country.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • city string

    Vendor city.

  • address string

    Vendor street address.

  • zipcode string

    Vendor ZIP/postal code.

  • bankName string

    Vendor bank name.

  • bankCountry string

    Vendor bank country.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • bankCity string

    Vendor bank city.

  • bankAddress string

    Vendor bank address.

  • bankZipcode string

    Vendor bank ZIP/postal code.

  • bankAccountNumber string

    Vendor bank account number (IBAN or local format).

  • bankAccountBic string

    Vendor bank BIC/SWIFT code.

  • domesticBankAccountNumber string

    Vendor domestic bank account number (country-specific format).

  • domesticBankAccountCode string

    Vendor domestic bank account code (e.g. routing/sort code).

  • swedishBankgiroNumber string

    Vendor Swedish Bankgiro number, if applicable.

  • swedishPlusgiroNumber string

    Vendor Swedish Plusgiro number, if applicable.

  • bankRecipientName string

    Name of the bank account holder. When set, this overrides the vendor name on the payment recipient for providers that consult it (currently Airwallex).

  • vendorCreatedAt string · date-time

    Timestamp when the vendor was created.

  • approvers array of object

    List of vendor approvers.

    • id string · uuid

      ID of the vendor approver entry.

    • userId string · uuid

      ID of the approver user.

    • vendorId string · uuid

      ID of the vendor.

    • priority integer · int32

      Approval priority (lower means earlier).

    • createdAt string · date-time

      Timestamp when the approver entry was created.

  • notes array of object

    List of vendor notes.

    • id string · uuid

      The note id.

    • vendorId string · uuid

      The vendor the note is on.

    • authorId string · uuid

      The user who wrote the note.

    • companyId string · uuid

      Your company id.

    • channel string

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of WEB_APP SLACK

    • content string

      The note text.

    • createdAt string · date-time

      When the note was written.

    • updatedAt string · date-time

      When it was last edited.

  • currency string

    The vendor's invoicing currency.

  • contractValue integer · int64

    Vendor contract value in cents.

  • createdBy string · uuid

    ID of the user who created the vendor.

  • status string

    Vendor onboarding/status.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    ONBOARDING (vendor portal in progress), IN_REVIEW (awaiting approval in Light; updates rejected), ACTIVE, FAILED (rejected; an update re-submits it). Not settable, and there is no archive endpoint.

    One of ONBOARDING IN_REVIEW ACTIVE FAILED

  • failureContext object

    Failure context when vendor onboarding fails.

    The error of the last failed step, if any.

    • name string

      The error name

    • type string

      The error type

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

    • errors array of object

      List of errors providing details about what went wrong

      • type string

        A string code identifying the error type

      • message string

        A human-readable message providing more details about the error

      • path array of string

        Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object

      • context object

        Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error

  • version integer · int32

    Vendor record version.

  • updatedAt string · date-time

    Timestamp when the vendor was last updated.

  • customProperties array of object

    Custom properties set on the vendor.

    • groupId string · uuid

      ID of the custom property group

    • groupInternalName string

      Internal name of the custom property group

    • values array of object

      List of values. Note that this will be a single value unless the group input type supports multiple values

      • id string · uuid

        Unique identifier for the object

      • groupId string · uuid

        ID of the custom property group

      • groupInternalName string

        Internal name of the custom property group

      • companyId string · uuid

        ID of the company

      • internalName string

        Internal name of the custom property value

      • label string

        Label of the custom property value

      • context string

        Context/description of the custom property value

      • createdAt string · date-time

        Timestamp when the custom property value was created

      • updatedAt string · date-time

        Timestamp when the custom property value was last updated

  • lastMtdSpendInGroupCurrency integer · int64

    Last month-to-date spend in group currency.

  • groupCurrency string

    Your company's group currency, in which the vendor's group-currency figures are expressed.