Export leads with registrant details

Export event or sponsor leads, include the captured registrant and creator, and follow every result page.

Read the lead records and explicitly request the related registrant objects. A token’s association allowlist and the request’s include parameter do different jobs.

Configure access

The leads scope needs Read access to the event. Select the lead fields you need, including sponsor_ids when ownership matters, and allow the registrant and created_by_registrant associations with their desired fields. For a sponsor-specific export, enable the sponsor_id query filter. A sponsor restriction on the scope is the authorization boundary; a query filter alone does not restrict the token’s access.

For an event export that includes leads without a sponsor, use a scope with no sponsor row restriction and omit the sponsor_id query filter. A sponsor-restricted scope excludes those leads even when the query filter is omitted.

Build the first page

The request uses include=registrant,created-by-registrant. The latter is the dashed relationship name; created_by_registrant is the scope configuration name.

curl --fail-with-body --silent --show-error --globoff --max-time 30 --request GET \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/leads?sponsor_id=103705&include=registrant%2Ccreated-by-registrant&page%5Bnumber%5D=1&page%5Bsize%5D=50' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"

The starting request filters to one sponsor. Clear sponsor_id in the builder to include leads with and without sponsors that the scope can read. The event-wide query is:

GET /api/core/organizations/123/events/456/leads?include=registrant,created-by-registrant&page[number]=1&page[size]=50

Join the related records

For each lead, resolve relationships.registrant.data against included using both type and id. Resolve relationships.created-by-registrant.data the same way. Keep the lead even when creator linkage is null; this can be valid for a lead created without a creator registrant.

When sponsor_ids is selected, a lead without a sponsor has sponsor-ids: []. Preserve that lead in an event export and leave its sponsor columns empty. A missing sponsor-ids attribute means the field was not returned; it does not establish that the lead has no sponsor.

The association permits external-id, first-name, last-name and email. It does not expose arbitrary registrant fields. If you specifically need the imported external_* identity values, use a separately authorized registrant read and join by registrant ID; do not silently substitute profile values.

GET /api/core/organizations/123/events/319986/leads?include=registrant

{
  "data": [
    {
      "id": "3898",
      "type": "lead",
      "attributes": {
        "event-id": 319986,
        "sponsor-ids": [
          103705
        ],
        "registrant-id": 1201,
        "created-by-registrant-id": 1301,
        "notes": "Interested in a product demo for their autumn event.",
        "created-at": "2026-09-08T09:00:00.000Z",
        "updated-at": "2026-09-08T09:00:00.000Z"
      },
      "relationships": {
        "registrant": {
          "data": {
            "id": "1201",
            "type": "event-registrant"
          }
        },
        "created-by-registrant": {
          "data": {
            "id": "1301",
            "type": "event-registrant"
          }
        }
      }
    }
  ],
  "meta": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1
  },
  "included": [
    {
      "id": "1201",
      "type": "event-registrant",
      "attributes": {
        "external-id": "CRM-10042",
        "first-name": "Alex",
        "last-name": "Morgan",
        "email": "alex@example.com"
      }
    }
  ]
}

Export every page

Start at page 1, process data and included together, then increment page[number] until meta.current_page reaches meta.total_pages. Page size is at most 100. Deduplicate by lead ID if restarting an export, and preserve one output row per lead.

A multi-page export is not a database snapshot; records can change while you read. For routine exports, keep a fixed time window using authorized created_from and created_to filters. Dates should be explicit ISO 8601 values.

Keep exported contact data in the customer’s intended destination. On 429, respect Retry-After; see retry guidance.