Skip to content
API key

API reference

Leads endpoints

Read the people who left their details on the account’s cards and pages — form leads, contact exchanges and scanned paper cards.

List leads

GEThttps://api.qrbold.com/api/public/v1/leads Try it

Returns the account’s leads, newest first.

API key required. Scope: leads:read. Campaign-scoped keys are refused. Plan: Pro, or the Business card plan.

Request

Request headers
HeaderRequiredValue
AuthorizationRequiredBearer YOUR_API_KEY. X-API-Key: YOUR_API_KEY is accepted instead.

Query parameters

Query parameters
NameTypeRequiredDescription
limitintegerOptionalItems per page, 1 to 100. Default: 25.
offsetintegerOptionalHow many items to skip. Default: 0.
cardIdstringOptionalOnly leads on this card or page.
sourcestringOptionalform: a form block. exchange: a contact exchange. scan: a paper card photographed in the dashboard. manual: typed in. One of form, exchange, scan, manual.
sincestringOptionalISO 8601 date-time. Only leads created at or after it — the cursor for an incremental sync.
includeArchivedbooleanOptionalInclude leads archived in the dashboard. Default: false.

Example request

curl "https://api.qrbold.com/api/public/v1/leads?source=exchange&since=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

Response

200 A list of lead objects.

200 response
{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "cmf3k6l1d0005",
      "cardId": "cmf3k2a9x0001",
      "cardName": "Ada Lovelace",
      "source": "exchange",
      "trigger": "after_save",
      "formName": "Contact exchange",
      "createdAt": "2026-10-12T09:41:07.000Z",
      "read": false,
      "archived": false,
      "locked": false,
      "contact": {
        "name": "Charles Babbage",
        "email": "charles@example.com",
        "phone": "+44 20 7946 0123",
        "company": "Difference Engines",
        "title": "Founder"
      },
      "answers": [
        {
          "fieldId": "xc_name",
          "label": "Name",
          "type": "text",
          "value": "Charles Babbage"
        },
        {
          "fieldId": "xc_email",
          "label": "Email",
          "type": "email",
          "value": "charles@example.com"
        }
      ],
      "marketingOptIn": null,
      "consentAt": null,
      "country": "GB",
      "city": "London",
      "hubspot": {
        "status": "sent",
        "sentAt": "2026-10-12T09:41:09.000Z",
        "nextAttemptAt": null,
        "contactUrl": "https://app.hubspot.com/contacts/1234567/record/0-1/51",
        "error": null
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "hasMore": false
  }
}

Errors

Errors specific to List leads
StatusCodeWhenRetry?
422validation_failedThe request body or the query string did not pass validation.Only after changing the request or the account

Every endpoint can also answer 401 invalid_api_key, 403 forbidden, 403 upgrade_required_api, 404 unknown_endpoint, 429 rate limited and 500 internal_error. One failing response is shown below.

422 response
{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "fields.links.0.type",
        "message": "Invalid enum value",
        "code": "invalid_enum_value"
      },
      {
        "field": "shortCode",
        "message": "Slugs can only contain letters, numbers, and hyphens",
        "code": "invalid_string"
      }
    ]
  }
}

Good to know

  • To sync, remember the createdAt of the newest lead you stored and pass it as since next time.
  • A locked lead has locked: true and null contact details. It unlocks, and reads in full, once the account’s allowance covers it.
  • hubspot is null unless the lead’s form sends to HubSpot. status is one of sent, pending, retrying, failed, held_locked, held_plan, held_disconnected, skipped_no_email or expired; contactUrl is null on a locked lead.

Related

Retrieve a lead

GEThttps://api.qrbold.com/api/public/v1/leads/:id Try it

Returns one lead with every answer it carries.

API key required. Scope: leads:read. Campaign-scoped keys are refused. Plan: Pro, or the Business card plan.

Request

Request headers
HeaderRequiredValue
AuthorizationRequiredBearer YOUR_API_KEY. X-API-Key: YOUR_API_KEY is accepted instead.
Path parameters
NameTypeRequiredDescription
idstringRequiredThe lead id.

Example request

curl "https://api.qrbold.com/api/public/v1/leads/cmf3k2a9x0001" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

Response

200 A lead object.

200 response
{
  "object": "lead",
  "id": "cmf3k6l1d0005",
  "cardId": "cmf3k2a9x0001",
  "cardName": "Ada Lovelace",
  "source": "exchange",
  "trigger": "after_save",
  "formName": "Contact exchange",
  "createdAt": "2026-10-12T09:41:07.000Z",
  "read": false,
  "archived": false,
  "locked": false,
  "contact": {
    "name": "Charles Babbage",
    "email": "charles@example.com",
    "phone": "+44 20 7946 0123",
    "company": "Difference Engines",
    "title": "Founder"
  },
  "answers": [
    {
      "fieldId": "xc_name",
      "label": "Name",
      "type": "text",
      "value": "Charles Babbage"
    },
    {
      "fieldId": "xc_email",
      "label": "Email",
      "type": "email",
      "value": "charles@example.com"
    }
  ],
  "marketingOptIn": null,
  "consentAt": null,
  "country": "GB",
  "city": "London",
  "hubspot": {
    "status": "sent",
    "sentAt": "2026-10-12T09:41:09.000Z",
    "nextAttemptAt": null,
    "contactUrl": "https://app.hubspot.com/contacts/1234567/record/0-1/51",
    "error": null
  }
}

Errors

Errors specific to Retrieve a lead
StatusCodeWhenRetry?
404resource_not_foundNothing with that id exists in this account.No

Every endpoint can also answer 401 invalid_api_key, 403 forbidden, 403 upgrade_required_api, 404 unknown_endpoint, 429 rate limited and 500 internal_error. One failing response is shown below.

404 response
{
  "error": {
    "type": "not_found",
    "code": "resource_not_found",
    "message": "Card not found"
  }
}

Related