> ## Documentation Index
> Fetch the complete documentation index at: https://partner-help.letsdothis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How imports work

> Bring bookings and related data from another platform into Let's Do This in batches, then check what landed.

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.

> [!NOTE]
>
> 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:

| Import | Needs first |
| - | - |
| [Bookings](https://partner-help.letsdothis.com/api-reference/endpoints/bookings/import-bookings.md) | The events, tickets and booking forms, set up in Let's Do This |
| [Add-ons](https://partner-help.letsdothis.com/api-reference/endpoints/addons/import-add-ons.md) | The events, races or tickets they're sold with |
| [Discount codes](https://partner-help.letsdothis.com/api-reference/endpoints/discountcodes/import-discount-codes.md) | Nothing |
| [Credits](https://partner-help.letsdothis.com/api-reference/endpoints/credits/import-credits.md) | Nothing |
| [Line items](https://partner-help.letsdothis.com/api-reference/endpoints/bookings/import-line-items.md) | The bookings, plus any add-ons and discount codes the line items refer to |
| [Teams](https://partner-help.letsdothis.com/api-reference/endpoints/teams/import-teams.md) | The bookings whose participants make up each team |
| [Referrals](https://partner-help.letsdothis.com/api-reference/endpoints/referrals/import-referrals.md) | The bookings on both sides of each referral, and an active referral program covering their events |
| [Reserved entry places](https://partner-help.letsdothis.com/api-reference/endpoints/reservedentries/import-reserved-entry-participants.md) | The bookings, and the reserved entry groups to place them in |

## 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](https://partner-help.letsdothis.com/api-reference/endpoints/bookings/get-booking-import-status.md).
   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](#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

| Field | What it tells you |
| - | - |
| `results` | One entry per row, with its `status` (`succeeded`, `alreadyImported` or `failed`) and, for a failed row, its `errors`. |
| `rowCounts` | How many rows succeeded, were already imported or failed so far. A non-zero `failed` means some rows need your attention. |
| `status` | `queued`, `processing`, `completed` or `cancelled`. |

`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](https://partner-help.letsdothis.com/api-reference/endpoints/bookings/delete-an-imported-booking.md),
  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](https://partner-help.letsdothis.com/api-reference/overview.md#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`](https://partner-help.letsdothis.com/api-reference/endpoints/participant/import-an-off-platform-marketing-opt-in))
  take one email address per request and answer straight away, without a job.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.