Leads

Leads: available fields, filters, associations, and API operations.

Operations

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' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"

{
  "data": [
    {
      "id": "1201",
      "type": "lead"
    }
  ],
  "meta": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1
  }
}

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/1201' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"

{
  "data": {
    "id": "1201",
    "type": "lead"
  }
}

curl --fail-with-body --silent --show-error --globoff --max-time 30 --request POST \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/leads' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "registrant_id": 1201,
  "notes": "Requested pricing information"
}'

{
  "data": {
    "id": "1201",
    "type": "lead"
  }
}

curl --fail-with-body --silent --show-error --globoff --max-time 30 --request PATCH \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/leads/3898' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "notes": "Requested pricing and a Q4 follow-up",
  "custom_fields_attributes": [
    {
      "sponsor_id": 103705,
      "question_id": 901,
      "values": [
        "Q4"
      ]
    }
  ]
}'

{
  "data": {
    "id": "1201",
    "type": "lead"
  }
}

curl --fail-with-body --silent --show-error --globoff --max-time 30 --request DELETE \
  --url "${BRELLA_API_BASE_URL}"'/api/core/organizations/123/events/456/leads/1201' \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: ${BRELLA_API_ACCESS_TOKEN}"

Path: events/{event_id}/leads
Methods: GET collection/record, POST, PATCH, DELETE.

Fields, filters and associations

• Filters: sponsor_id, registrant_id, created_by_registrant_id, created_from, created_to, updated_from, updated_to.
• Associations:
  • sponsors: linkage only;
  • registrant: external-id, first-name, last-name, email;
  • created_by_registrant → response created-by-registrant: external-id, first-name, last-name, email;
  • custom_fields → response custom-fields: definition-key, definition-title, field-type, values.
• Row restriction: by the sponsors association.

GET .../leads?sponsor_id=103705&include=registrant,created-by-registrant,custom-fields

Leads without a sponsor

With no sponsor row restriction, collection and individual GET requests can return leads without a sponsor. The lead belongs to its registrant’s event and returns sponsor-ids: [] when sponsor_ids is selected in the scope’s readable fields.

Omit the sponsor_id query filter to include these leads in an event export. An enabled sponsor_id filter only returns leads owned by that sponsor. Sponsor-restricted scopes exclude leads without a sponsor from collections and return 404 for individual GET or PATCH requests targeting them.

Create and update

POST/PATCH inputs: registrant_id, created_by_registrant_id, notes, sponsor_id, custom_fields_attributes (raw JSON). The custom-field input is consumed on PATCH; lead creation does not process lead-scan answers.

To create a lead without a sponsor, use a scope with no sponsor row restriction and omit sponsor_id or send "sponsor_id": null:

{
  "registrant_id": 1201,
  "created_by_registrant_id": 1301,
  "notes": "Requested pricing information"
}

The target registrant and any supplied creator, sponsor, or lead-scan answers must belong to the URL event. Select sponsor_ids in Write-response fields to receive sponsor-ids: [] for a lead created without a sponsor.

To create a lead for a sponsor, supply sponsor_id. A scope with sponsor restrictions uses the first configured restricted sponsor when the input is omitted or null; a scope restricted to exactly one sponsor uses that sponsor. Supply an explicit allowed ID when choosing among several restricted sponsors. A sponsor outside the event or restricted set returns 404.

Omitting sponsor_id on PATCH preserves existing ownership. Sending null on PATCH returns 404; it does not remove sponsors. See the lead cookbook for ownership replacement rules and complete requests.

A sponsor-restricted scope cannot change created_by_registrant_id on PATCH. A lead created without a creator correctly returns created-by-registrant-id: null and a null relationship.

Lead-scan answers on PATCH use the configured request key for custom_fields_attributes and this raw shape:

{
  "custom_fields_attributes": [
    {
      "sponsor_id": 103705,
      "question_id": 901,
      "values": ["Q4"]
    }
  ]
}