Skip to main content
Import endpoints bring data you hold elsewhere into Let’s Do This: bookings and their line items, add-ons, discount codes, credits, teams, referrals and reserved entry places. They all work the same way. You send a batch, get back a job, and read the job to see what happened to each row.
Imports are restricted. If an import returns 403, ask your Let’s Do This representative to enable it for your organization.

What to import first

Some imports refer to data that an earlier import created, so run them in this order:

How an import runs

  1. Send a batch. A batch holds up to 1,000 rows, or 500 teams. Line item batches are grouped by booking: up to 1,000 bookings, each with up to 100 line items.
  2. The whole batch is checked. If any row has a problem, the request fails with 422, nothing is imported, and the response lists every problem. Fix them and send the batch again.
  3. You get a job. A batch that passes the check returns 202 with a jobId. The rows are imported in the background.
  4. Poll the job. Each import has a status endpoint, such as booking import status. Read it every few seconds until status is completed.
  5. Read the results. results holds one entry per row, saying whether that row was imported. Line items and reserved entry places report results differently; see Imports that work differently.
A row can still fail in the background after the batch passed the check, for example a participant who already holds a place in a different reserved entry group. One row failing doesn’t stop the others.

Reading a job

completed means the job has finished, not that every row was imported. A job whose rows all failed is still completed, so always check results. results fills up while the job runs, so a processing job shows only the rows finished so far. The counts field tracks the job’s internal work, not your rows, so don’t use it to decide whether rows were imported.

When a batch fails the check

A 422 response describes every problem in the batch:
  • summary groups the problems by type, most common first, with a count and example rows for each. It always lists every type of problem.
  • errors lists the problems row by row. A large batch can have more problems than this list holds; truncated is then true.
  • totalRows, rowsWithErrors and errorCount give the totals.
Each problem has a code you can act on in code and a message to read.

Importing a row again

Every row carries your own id for the record, such as externalBookingId for a booking or externalCreditId for a credit. An import creates each record once. Sending a row whose id was already imported changes nothing: its result is alreadyImported and points to the existing record. Teams are the exception: sending a team that was already imported, with the same details, adds any members it’s missing. To change something you’ve already imported:
  • Add-ons and line items: send it to the PUT version of the import, which updates records it created earlier.
  • Bookings: delete the imported booking, then import the corrected row with the same externalBookingId.

Retrying a request

Send an Idempotency-Key header, up to 255 characters, with a new value for each batch. If a request times out or you aren’t sure it arrived, send it again with the same key and body: you get back the original job rather than a second import. Reusing a key with a different body fails with 409. The key is optional for most imports. Line item imports require one.

Limits

  • Batch size: up to 1,000 rows per request, or 500 teams. Line item imports accept up to 1,000 bookings, with up to 100 line items per booking. A batch that is too large in bytes fails with 413; split it into smaller batches.
  • Rate limits: imports are rate limited per API key. Sending batches in parallel is what usually reaches the limit. See rate limiting.

Imports that work differently

  • Add-ons have no whole-batch check. Each product is checked in the background. The job has no rowCounts, and lists up to 50 products per page: pass page.next as page[after] until it comes back empty to read every product, even once the job is completed. A product imported earlier shows alreadyImported in product.outcome, not in its status.
  • Line items are sent grouped by booking, but results and rowCounts count line items: each result names its bookingId. The request itself is checked straight away. Checks that depend on the booking run in the background and show up as failed line items.
  • Reserved entry places report one result per participant, not per row. A row that names a bookingId places every participant on that booking, so it can produce several results with the same rowIndex, each with its own outcome. rowCounts counts those results. Match results to participants by participantId, not by rowIndex alone. A row that couldn’t be matched to any participant shows up as a failed result with no participantId.
  • Marketing opt-ins (POST /v0/opt-ins) take one email address per request and answer straight away, without a job.