New Light partners with Amesto GlobalLight partners with Amesto Global Read the announcement

Create customers in bulk

POST
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

  • records array of objectrequired

    The customers to create

    • idempotencyKey stringrequired

      A 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).

    • record objectrequired

      • name string

      • email string

      • address object

        • country string

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

          One of 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

          Note

          City.

        • state string

          Note

          State or region, where the country uses one.

        • zipcode string

          Note

          Postal code.

        • street string

          Note

          First address line.

        • street2 string

          Note

          Second address line.

      • billingAddress object

        • country string

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

          One of 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

          Note

          City.

        • state string

          Note

          State or region, where the country uses one.

        • zipcode string

          Note

          Postal code.

        • street string

          Note

          First address line.

        • street2 string

          Note

          Second address line.

      • shippingAddress object

        • country string

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

          One of 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

          Note

          City.

        • state string

          Note

          State or region, where the country uses one.

        • zipcode string

          Note

          Postal code.

        • street string

          Note

          First address line.

        • street2 string

          Note

          Second address line.

      • domain string

      • description string

      • vatNumber string

      • businessRegistrationNumber string

      • easCode string

      • einvoiceAddress string

      • einvoiceNetwork string

        • DE_EMAIL - Germany e-invoice delivered by email (XRechnung). Only for customers with a billing address in Germany
        • FINVOICE - Finland Finvoice e-invoice network
        • FR_PA - France Plateforme Agréée (Chorus Pro / Annuaire) e-invoice network
        • MYDATA - Greece myDATA e-invoice network
        • NEMHANDEL - NemHandel e-invoice network
        • PEPPOL - Peppol e-invoice network
        • PORTUGUESE_TAX_REPORTING - Portuguese tax reporting (ATCUD) e-invoice network
        • SDI - SDI (Sistema di Interscambio) e-invoice network
        • VERIFACTU - Spain VERI*FACTU tax reporting e-invoice network

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

        One of DE_EMAIL FINVOICE FR_PA MYDATA NEMHANDEL PEPPOL PORTUGUESE_TAX_REPORTING SDI VERIFACTU

      • type string

        • BUSINESS - Business customer
        • CONSUMER - Consumer customer
        • GOVERNMENT - Government customer

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

        One of BUSINESS CONSUMER GOVERNMENT

      • defaultTaxId string · uuid

        ID of an active sales tax code to store as the customer's default. Saving this preference does not change existing invoice or contract lines.

      • parentCustomerId string · uuid

        ID of the parent customer. It must be an active customer of the same company with no parent, because a customer group has two levels.

      • logoUrl string

      • customProperties array of object

        • groupId string · uuid

          ID of the custom property group.

        • valueIds array of string · uuid

          IDs 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 empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

        • inlineValues array of string

          Inline 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, 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.

        • attachmentIds array of string · uuid

          IDs 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.

      • recipientEmails array of string

        Billing email recipients ("Send to") used when sending invoices to this customer

      • ccEmails array of string

        Billing email CC recipients used when sending invoices to this customer

      • externalSource object

        The 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.

        • name string

          The system the ID comes from

          • HUBSPOT - Customer from HubSpot
          • SALESFORCE - Customer from Salesforce
          • STRIPE - Customer from Stripe

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

          One of HUBSPOT SALESFORCE STRIPE

        • externalId string

          The ID of the customer in the external system

Response

The customers were accepted for processing.

  • id string · uuid

    Unique identifier of the batch operation

  • companyId string · uuid

    ID of the company the batch operation belongs to

  • name string

    What the batch operation does

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

    One of BATCH_CREATE_CREDIT_NOTES BATCH_CREATE_CUSTOMERS BATCH_CREATE_CUSTOMER_CREDITS BATCH_CREATE_INVOICE_PAYABLES BATCH_CREATE_INVOICE_RECEIVABLES BATCH_UPDATE_CARD_TRANSACTIONS

  • status string

    IN_PROGRESS until no record is pending. Then COMPLETED, or FAILED when at least one record failed

    • COMPLETED - Every record was processed
    • FAILED - No record is pending and at least one failed
    • IN_PROGRESS - At least one record is pending

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

    One of COMPLETED FAILED IN_PROGRESS

  • initiatedBy string · uuid

    ID of the user or API key that started the batch operation

  • createdAt string · date-time

    When the batch operation was created

  • pendingItemCount integer · int64

    Number of records waiting to be processed

  • completedItemCount integer · int64

    Number of records that were processed

  • failedItemCount integer · int64

    Number of records that failed