> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userecord.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Candidates and results

> Step 3. See where each candidate stands and read what they answered.

Read candidates while a campaign runs, and results once they finish. Both carry your `external_id` and the candidate's full phone number, so you can match them to your own records.

| Needs | You get | Scope |
| - | - | - |
| `enrichment_id` | `candidate_id`, `result_id` | `enrichment:read` (any enrichment scope also reads) |

> [!NOTE]
>
> Answers are **self-reported and not verified**. No verification link is ever returned.

## How to get results

Read them with [`GET /results`](#list-results). A result is written once, when a candidate finishes or declines, and never changes, so it is final the moment it appears. Poll as often as suits you (reads have their own [rate limit](https://docs.userecord.io/enrichment-api/reference/limits.md)), page with `cursor` until `has_more` is false, and skip a `result_id` you already stored. Many integrations poll every minute or two, and again after starting a campaign.

## Candidate or result?

| | Candidate | Result |
| - | - | - |
| When it exists | As soon as the campaign is created | Only when the candidate finishes or declines |
| Changes | Yes, as the candidate moves through the [statuses](https://docs.userecord.io/enrichment-api/reference/statuses.md) | Never. Written once. |
| Use it for | Following progress, who to chase | Pulling the final answers into your ATS |

## Endpoints

### List candidates

`GET /enrichments/{enrichment_id}/candidates`

Every candidate of an enrichment and where each stands, most recently finished first.

**Scope:** `enrichment:read`

| Query | Description |
| - | - |
| `campaign_id` | Only this campaign's candidates. |
| `status` | One [status](https://docs.userecord.io/enrichment-api/reference/statuses.md): `queued`, `sent`, `link_opened`, `interested`, `in_progress`, `completed`, `not_interested`, `opted_out` or `failed`. |
| `search` | Part of the name or phone number. |
| `limit`, `cursor` | Paging. `limit` 1 to 100, default 25. |

```json Response · 200 theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "candidate_id": "6f1d2c3e-8a4b-4c57-9d10-2b7e5a9c1f33",
        "external_id": "cand-1001",
        "name": "Ravi Kumar",
        "phone_number": "+919876543210",
        "status": "completed",
        "language": "english",
        "campaign_id": "EC_261121095438377TFUX07WN2XT42V",
        "is_completed": true,
        "completed_channel": "whatsapp",
        "answered_count": 2,
        "question_count": 2,
        "delivery_error": null,
        "answers": {
          "eqq_cc9800817588972e": ["Yes"],
          "eqq_7a31f0c2d95b84e6": ["Forklift operator, 4 years, Chennai"]
        }
      }
    ],
    "count": 1, "total": 1, "next_cursor": null, "has_more": false
  }
}
```

`answers` is the answer text per `question_id`. `completed_channel` is where they finished: `whatsapp`, `sms`, `voice` or `web`.

### Get a candidate

`GET /enrichments/{enrichment_id}/candidates/{candidate_id}`

One candidate in full.

**Scope:** `enrichment:read` · **Errors:** `404 NOT_FOUND`

* `journey` shows what was sent and when: the invite, follow-ups, SMS, call attempts, link opened and opt-out.
* `answers` has every question, answered or not, with `text`, the `channel` it came on, an English transcript for a spoken answer (`transcript_english`) and, for `yes_no`, whether it `qualified`.
* `result` is the final result once the candidate has finished, otherwise `null`.

> [!NOTE]
>
> The English transcript of a spoken answer is translated the first time it is read, so that first read can be slower.

### List results

`GET /enrichments/{enrichment_id}/results`

The final result of each candidate who finished or declined, newest first.

**Scope:** `enrichment:read`

| Query | Description |
| - | - |
| `campaign_id` | Only this campaign's results. |
| `limit`, `cursor` | Paging. `limit` 1 to 100, default 25. |

```json Response · 200 theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "result_id": "ERS_261121100210123X5T9K2M7Q4R8WV",
        "enrichment_id": "WF_EN_261121094822026AEDRUB86TQVSML",
        "candidate_id": "6f1d2c3e-8a4b-4c57-9d10-2b7e5a9c1f33",
        "external_id": "cand-1001",
        "name": "Ravi Kumar",
        "phone_number": "+919876543210",
        "campaign_id": "EC_261121095438377TFUX07WN2XT42V",
        "status": "completed",
        "completed_channel": "whatsapp",
        "completed_at": "2026-11-10T11:02:10.000Z",
        "summary": { "answered_count": 2, "required_count": 2, "qualified_count": 1 },
        "answers": [
          { "question_id": "eqq_cc9800817588972e", "order": 0, "question_text": "Are you open to a new job right now?", "type": "yes_no", "value": true, "qualified": true, "channel": "whatsapp" },
          { "question_id": "eqq_7a31f0c2d95b84e6", "order": 1, "question_text": "Tell us about the work you do and where you want to work.", "type": "voice", "value": "Forklift operator, 4 years, Chennai", "qualified": null, "channel": "voice" }
        ]
      }
    ],
    "count": 1, "total": 1, "next_cursor": null, "has_more": false
  }
}
```

| Field | Description |
| - | - |
| `enrichment_id` | The enrichment the result belongs to. |
| `status` | `completed`, or `not_interested` when the candidate declined. |
| `summary` | `answered_count`, `required_count`, `qualified_count`. When the candidate gave them also `open_to_work`, `work`, `location`, `disinterest_reason` and `partial` (finished with only some answers). |
| `answers[].value` | `true` or `false` for `yes_no`; a text summary for `voice`. |
| `answers[].qualified` | `yes_no` only: whether the answer matched the question's `preferred_answer`. |

Poll this endpoint for new results: they are final as soon as they appear.


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