Create customers in bulk
https://api.light.inc/v1/customers/batch-create
Accepts up to 1,000 customers and creates them independently. Read the batch operation until its status is no longer IN_PROGRESS, then read its items for each record's idempotency key, customer ID or failure. To create a customer group, create the parent first and use its returned ID in a later call for its children. A company can have up to 20,000 records waiting. On 429, wait the number of seconds in the Retry-After header.
Permission: customers:create (AR_CLERK, COMPANY_ADMIN, CONTROLLER)
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 · required
-
recordsarray of objectrequiredThe customers to create
-
idempotencyKeystringrequiredA key you choose for this record, unique within the call. On retry, send the same record and key. Light returns the original record ID if it processes the retry while the successful create is still cached (24 hours after creation).
-
recordobjectrequired-
namestring -
emailstring -
addressobject-
countrystring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
ACADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBUBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCPCRCSCUCVCWCXCYCZDEDGDJDKDMDODZEAECEEEGEHERESETEUEZFIFJFKFMFOFRFXGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUICIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNTNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESFSGSHSISJSKSLSMSNSOSRSSSTSUSVSXSYSZTATCTDTFTGTHTJTKTLTMTNTOTPTRTTTVTWTZUAUGUKUMUSUYUZVAVCVEVGVIVNVUWFWSXIXUXKYEYTYUZAZMZRZW -
citystringNote
City.
-
statestringNote
State or region, where the country uses one.
-
zipcodestringNote
Postal code.
-
streetstringNote
First address line.
-
street2stringNote
Second address line.
-
-
billingAddressobject-
countrystring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
ACADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBUBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCPCRCSCUCVCWCXCYCZDEDGDJDKDMDODZEAECEEEGEHERESETEUEZFIFJFKFMFOFRFXGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUICIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNTNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESFSGSHSISJSKSLSMSNSOSRSSSTSUSVSXSYSZTATCTDTFTGTHTJTKTLTMTNTOTPTRTTTVTWTZUAUGUKUMUSUYUZVAVCVEVGVIVNVUWFWSXIXUXKYEYTYUZAZMZRZW -
citystringNote
City.
-
statestringNote
State or region, where the country uses one.
-
zipcodestringNote
Postal code.
-
streetstringNote
First address line.
-
street2stringNote
Second address line.
-
-
shippingAddressobject-
countrystring⚠️ This enum is not exhaustive; new values may be added in the future.
One of
ACADAEAFAGAIALAMANAOAQARASATAUAWAXAZBABBBDBEBFBGBHBIBJBLBMBNBOBQBRBSBTBUBVBWBYBZCACCCDCFCGCHCICKCLCMCNCOCPCRCSCUCVCWCXCYCZDEDGDJDKDMDODZEAECEEEGEHERESETEUEZFIFJFKFMFOFRFXGAGBGDGEGFGGGHGIGLGMGNGPGQGRGSGTGUGWGYHKHMHNHRHTHUICIDIEILIMINIOIQIRISITJEJMJOJPKEKGKHKIKMKNKPKRKWKYKZLALBLCLILKLRLSLTLULVLYMAMCMDMEMFMGMHMKMLMMMNMOMPMQMRMSMTMUMVMWMXMYMZNANCNENFNGNINLNONPNRNTNUNZOMPAPEPFPGPHPKPLPMPNPRPSPTPWPYQARERORSRURWSASBSCSDSESFSGSHSISJSKSLSMSNSOSRSSSTSUSVSXSYSZTATCTDTFTGTHTJTKTLTMTNTOTPTRTTTVTWTZUAUGUKUMUSUYUZVAVCVEVGVIVNVUWFWSXIXUXKYEYTYUZAZMZRZW -
citystringNote
City.
-
statestringNote
State or region, where the country uses one.
-
zipcodestringNote
Postal code.
-
streetstringNote
First address line.
-
street2stringNote
Second address line.
-
-
domainstring -
descriptionstring -
vatNumberstring -
businessRegistrationNumberstring -
easCodestring -
einvoiceAddressstring -
einvoiceNetworkstringDE_EMAIL- Germany e-invoice delivered by email (XRechnung). Only for customers with a billing address in GermanyFINVOICE- Finland Finvoice e-invoice networkFR_PA- France Plateforme Agréée (Chorus Pro / Annuaire) e-invoice networkMYDATA- Greece myDATA e-invoice networkNEMHANDEL- NemHandel e-invoice networkPEPPOL- Peppol e-invoice networkPORTUGUESE_TAX_REPORTING- Portuguese tax reporting (ATCUD) e-invoice networkSDI- SDI (Sistema di Interscambio) e-invoice networkVERIFACTU- Spain VERI*FACTU tax reporting e-invoice network
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
DE_EMAILFINVOICEFR_PAMYDATANEMHANDELPEPPOLPORTUGUESE_TAX_REPORTINGSDIVERIFACTU -
typestringBUSINESS- Business customerCONSUMER- Consumer customerGOVERNMENT- Government customer
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
BUSINESSCONSUMERGOVERNMENT -
defaultTaxIdstring · uuidID of an active sales tax code to store as the customer's default. Saving this preference does not change existing invoice or contract lines.
-
parentCustomerIdstring · uuidID of the parent customer. It must be an active customer of the same company with no parent, because a customer group has two levels.
-
logoUrlstring -
customPropertiesarray of object-
groupIdstring · uuidID of the custom property group.
-
valueIdsarray of string · uuidIDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.
Note
Catalog value ids for this group. Required; send
[](with an emptyinlineValues) to clear the group.SINGLE_SELECTandMULTI_SELECTgroups accept nothing else. See Custom properties on writes. -
inlineValuesarray of stringInline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.
Note
Literal values for
TEXT,NUMERIC,BOOLEANandDATEgroups, as strings (yyyy-MM-ddfor dates). Rejected on select groups withCUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes. -
attachmentIdsarray of string · uuidIDs of attachments to assign to an ATTACHMENT property on an existing vendor. Send valueIds as an empty list. Only one active attachment belonging to the vendor can be assigned per group. Clear the current file before assigning another. Create the vendor first, request POST /v1/attachments/upload-url with its resourceId, upload the file to the returned URL, then POST /v1/attachments with documentKey set to the returned key. Use the created attachment's id here in PUT or PATCH /v1/vendors/{vendorId}. A PATCH that sends only customProperties and changes only their files works in every vendor status. customProperties replaces the whole set, so send the vendor's other properties as they are, by valueIds. A PUT, or a PATCH that changes anything else, returns 400 while the vendor is IN_REVIEW, ONBOARDING or INACTIVE. An empty list clears the assignment without archiving the file.
-
-
recipientEmailsarray of stringBilling email recipients ("Send to") used when sending invoices to this customer
-
ccEmailsarray of stringBilling email CC recipients used when sending invoices to this customer
-
externalSourceobjectThe customer's ID in an external system and the system it comes from. Rejected when another customer already has the same ID from the same system.
-
namestringThe system the ID comes from
HUBSPOT- Customer from HubSpotSALESFORCE- Customer from SalesforceSTRIPE- Customer from Stripe
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
HUBSPOTSALESFORCESTRIPE -
externalIdstringThe ID of the customer in the external system
-
-
-
Response
The customers were accepted for processing.
-
idstring · uuidUnique identifier of the batch operation
-
companyIdstring · uuidID of the company the batch operation belongs to
-
namestringWhat the batch operation does
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
BATCH_CREATE_CREDIT_NOTESBATCH_CREATE_CUSTOMERSBATCH_CREATE_CUSTOMER_CREDITSBATCH_CREATE_INVOICE_PAYABLESBATCH_CREATE_INVOICE_RECEIVABLESBATCH_UPDATE_CARD_TRANSACTIONS -
statusstringIN_PROGRESSuntil no record is pending. ThenCOMPLETED, orFAILEDwhen at least one record failedCOMPLETED- Every record was processedFAILED- No record is pending and at least one failedIN_PROGRESS- At least one record is pending
⚠️ This enum is not exhaustive; new values may be added in the future.
One of
COMPLETEDFAILEDIN_PROGRESS -
initiatedBystring · uuidID of the user or API key that started the batch operation
-
createdAtstring · date-timeWhen the batch operation was created
-
pendingItemCountinteger · int64Number of records waiting to be processed
-
completedItemCountinteger · int64Number of records that were processed
-
failedItemCountinteger · int64Number of records that failed