> ## 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. # Import referrals > Asynchronously imports referral progress between existing bookings created through the Public API. Each row names the `referredBookingId`, whose start-list entries each count as referral progress, and the `referralCodeOwnerBookingId`, whose generated referral code receives credit. The owner booking's code is reused or generated internally. Both bookings must belong to this organizer and their occurrences must be covered by the same active referral program. This operation does not create bookings or participants and does not trigger booking or threshold emails. The whole batch is validated synchronously — either every row is accepted or none is. Each start-list entry is attributed at most once. Send an `Idempotency-Key` header to make submission replayable. This endpoint is restricted and not generally available: organizations that have not been enabled receive a `403`. Contact your Let's Do This representative if you'd like access. ## OpenAPI ````yaml /openapi.json post /v0/referrals/import openapi: 3.1.0 info: title: Let's Do This API version: 0.1.0 description: > The full reference — getting started, pagination, error responses, rate limits and the changelog — lives at [partner-help.letsdothis.com/api-reference](https://partner-help.letsdothis.com/api-reference/overview). This page is the interactive OpenAPI view of the same specification. # Authentication Create an API key from **Settings** → **Credentials** in your Let's Do This account and send it as a bearer token: ```bash curl --request GET \ --url "https://api.letsdothis.com/v0/participants" \ --header "Authorization: Bearer YOUR-API-KEY" ``` Keep the key secret: it identifies your organization, so do not ship it in a website or native app. If a key is exposed, revoke it from the same section and create a replacement. # OpenAPI schema Download the [OpenAPI schema](https://api.letsdothis.com/documentation/json) to use with Postman or an OpenAPI client generator. servers: - url: https://api.letsdothis.com description: Production - url: https://api.staging.letsdothis.com description: Staging security: - bearerAuth: [] tags: - name: Events x-group: Events description: Events that participants can register for. - name: EventOccurrences x-group: Event occurrences description: >- Event occurrences scoped to the organizer associated with your Public API credentials. Unlike the public Events catalog, results are limited to your own events. - name: Races x-group: Races description: >- Races within an event occurrence. An event occurrence may have one or more races, for example a 5K and a 10K within the same race day. - name: Tickets x-group: Tickets description: Tickets that are available for events. - name: BookingForms x-group: Booking forms description: >- Booking forms define the questions a booker answers when registering for a ticket. A ticket usually references a single booking form, so expect zero or one, while a booking form may be shared across multiple tickets. - name: BookingFormFields x-group: Booking form fields description: >- Booking form fields are the individual questions on a booking form — their type, label, options, and whether an answer is required. A field can be reused across multiple forms. - name: Bookings x-group: Bookings description: >- Bookings are the transaction record for a registration. A booking may contain one or more participants (entries). - name: Participant x-group: Participants description: Participants are users who successfully booked an event. - name: LineItem x-group: Line items description: Financial details related to individual items within transactions. - name: AddOns x-group: Add-ons description: >- Organizer-owned products that can be purchased and allocated to participants. Imported products retain stable external identities. - name: DiscountCodes x-group: Discount codes description: >- Discount codes participants enter at checkout to reduce the price of a booking. - name: Credits x-group: Credits description: >- Credits are balances participants can spend at checkout, identified by their email address. - name: Referrals x-group: Referrals description: >- Referral programs, the referrers registered on them, and asynchronous imports of historical referrals. - name: Application x-group: Applications description: >- Applications are created when a user applies for tickets that are set up to require an application process, such as balloted or "Good For Age" entries. - name: Partner x-group: Partners description: >- Partners that were created by the organization who can have Reserved Entries assigned to them. - name: ReservedEntries x-group: Reserved entries description: >- Reserved Entries are entries that are reserved for a partner. After being assigned, the partner can then allocate these entries to participants. - name: Timing x-group: Timing description: >- Timing providers push bib numbers and bib-pack shipments back to Let's Do This for the startlist entries they received. Available to select timing partners only. paths: /v0/referrals/import: post: tags: - Referrals summary: Import referrals description: >- Asynchronously imports referral progress between existing bookings created through the Public API. Each row names the `referredBookingId`, whose start-list entries each count as referral progress, and the `referralCodeOwnerBookingId`, whose generated referral code receives credit. The owner booking's code is reused or generated internally. Both bookings must belong to this organizer and their occurrences must be covered by the same active referral program. This operation does not create bookings or participants and does not trigger booking or threshold emails. The whole batch is validated synchronously — either every row is accepted or none is. Each start-list entry is attributed at most once. Send an `Idempotency-Key` header to make submission replayable. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferralImportRequest' responses: '202': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ReferralImportAccepted' '400': description: Bad request content: application/json: schema: description: Bad request type: object properties: statusCode: type: number enum: - 400 error: type: string message: type: string '409': description: Conflict content: application/json: schema: description: Conflict type: object properties: statusCode: type: number enum: - 409 error: type: string message: type: string '413': description: Payload too large content: application/json: schema: description: Payload too large type: object properties: statusCode: type: number enum: - 413 error: type: string message: type: string '422': description: Default Response content: application/json: schema: $ref: '#/components/schemas/ReferralImportValidationFailure' '429': description: Rate limit exceeded headers: retry-after: schema: type: integer description: Seconds to wait before retrying the request. x-ratelimit-limit: schema: type: integer description: Requests permitted in the current window. x-ratelimit-remaining: schema: type: integer description: Requests still permitted in the current window. x-ratelimit-reset: schema: type: integer description: Seconds until the current window resets. content: application/json: schema: description: Rate limit exceeded type: object properties: statusCode: type: number enum: - 429 error: type: string message: type: string components: schemas: ReferralImportRequest: title: ReferralImportRequest type: object properties: referrals: type: array items: $ref: '#/components/schemas/ReferralImportRow' description: The referrals to import. minItems: 1 maxItems: 1000 required: - referrals additionalProperties: false description: >- An asynchronous referral import request: the whole batch is accepted or none of it. example: referrals: - referredBookingId: 65f708192a3b4c5d6e7f80 referralCodeOwnerBookingId: 65f708192a3b4c5d6e7f70 ReferralImportAccepted: title: ReferralImportAccepted type: object properties: jobId: type: string description: The id of the queued import job. status: type: string enum: - queued required: - jobId - status additionalProperties: false description: The accepted import job. Poll the job endpoint for progress and results. example: jobId: 66393a4b5c6d7e8f901a2b3c status: queued ReferralImportValidationFailure: title: ReferralImportValidationFailure type: object properties: error: type: string enum: - validation_failed message: type: string description: A human summary of the failure. totalRows: type: number description: How many rows the batch contained. rowsWithErrors: type: number description: How many rows had at least one error. errorCount: type: number description: How many errors were found in total. summary: type: array items: $ref: '#/components/schemas/ReferralImportErrorSummary' errors: type: array items: $ref: '#/components/schemas/ReferralImportRowErrors' truncated: type: boolean description: Whether `errors` was capped. `summary` is never capped. required: - error - message - totalRows - rowsWithErrors - errorCount - summary - errors - truncated additionalProperties: false description: >- The whole-batch validation failure: nothing was imported. `summary` is the load-bearing part — every error class, uncapped, ordered by frequency. `errors` carries capped per-row detail; `truncated` refers to `errors` only, never `summary`. ReferralImportRow: title: ReferralImportRow type: object properties: referredBookingId: type: string description: >- The id of the booking whose start-list entries count as referral progress. Re-importing the same booking returns the original referrals, reported as `alreadyImported`. minLength: 1 maxLength: 255 referralCodeOwnerBookingId: type: string description: >- The id of the booking whose generated referral code receives credit. The code is reused or generated internally by the import. minLength: 1 maxLength: 255 required: - referredBookingId - referralCodeOwnerBookingId additionalProperties: false description: One booking credited to another booking's referral code. ReferralImportErrorSummary: title: ReferralImportErrorSummary type: object properties: code: type: string fieldId: type: string description: The row field the class relates to, when field-scoped. count: type: number description: How many times this class occurred across the batch. message: type: string description: A representative message for the class. examples: type: array items: $ref: '#/components/schemas/ReferralImportErrorLocator' description: The first few occurrences, located. required: - code - count - message - examples additionalProperties: false description: One validation problem class, aggregated across the batch. ReferralImportRowErrors: title: ReferralImportRowErrors type: object properties: referredBookingId: type: string description: The `referredBookingId` of the row. rowIndex: type: number description: The zero-based position of the row in `referrals`. errors: type: array items: $ref: '#/components/schemas/ReferralImportErrorDetail' required: - rowIndex - errors additionalProperties: false description: The per-row detail of a failed validation, grouped by row. ReferralImportErrorLocator: title: ReferralImportErrorLocator type: object properties: referredBookingId: type: string description: The `referredBookingId` of the offending row. rowIndex: type: number description: The zero-based position of the offending row in `referrals`. value: type: string description: The offending submitted value, when one exists. required: - rowIndex additionalProperties: false description: Where in the batch a validation error occurred. ReferralImportErrorDetail: title: ReferralImportErrorDetail type: object properties: code: type: string fieldId: type: string message: type: string required: - code - message additionalProperties: false description: One occurrence of a validation error. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````