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

# Per-item status of a talent-network submission batch

<Info>
  **Required scopes:** `talent_network:read`<br />
  **Rate limit:** `default` tier, 120 requests per minute per key
</Info>

Returns the current per-item outcome of a `submit` or `submit-bulk` request, ordered by item `index`. Statuses: `queued` (an ingestion task is live), `processing` (the worker is running — including LinkedIn profile verification, which can take tens of seconds), `succeeded` (ingested; `candidateUserId` set), `failed` (terminal; `errorCode`/`errorMessage` set), `deduplicated` (an identical submission was in flight — status only, the original submission is never identified and may not appear in any batch).

A `failed` item is always resubmittable: dedupe only holds while an earlier submission of the same candidate is unsettled, so a resubmission after a terminal outcome starts a fresh attempt rather than coming back `deduplicated`.

`itemCount` is the number of items the request SENT. Items rejected at submit time have no row here (their errors were returned synchronously), so `items` may have index gaps and `itemCount - items.length` is the request-time rejection count. The exception is `enqueue_failed`, which does get a row and appears here as `failed`.

Stable `errorCode` values: `invalid_linkedin_url`, `invalid_email`, `invalid_resume_reference`, `recruiter_not_found`, `recruiter_deactivated`, `resume_parse_failed`, `resume_identity_mismatch`, `linkedin_profile_not_found`, `linkedin_no_experience`, `linkedin_verification_unavailable`, `internal_error`, `enqueue_failed`, `ingest_timed_out`. Codes are never renamed, but new ones may be added — treat unknown codes as terminal failures.

`succeeded` means listed: profile enrichment runs inside the ingestion worker, so the candidate is visible in the talent network the moment the item reaches `succeeded`. Rarely (a transient enrichment failure) enrichment is retried asynchronously and the candidate appears shortly after. `updatedAt` is the row's last transition. `queued`/`processing` is never a permanent state: an item that never completes is failed automatically with `ingest_timed_out` a few hours after submission, and can then be resubmitted. `candidateUserId` can rarely appear on a `failed` item when ingestion failed after the candidate records were already committed.

## Path parameters

<ParamField path="batchId" type="string" required>
  Constraints: format `uuid`.
</ParamField>

## Response

<ResponseField name="batchId" type="string" required>
  Constraints: format `uuid`.
</ResponseField>

<ResponseField name="createdAt" type="string" required />

<ResponseField name="itemCount" type="integer" required />

<ResponseField name="items" type="object[]" required>
  <Expandable title="items properties">
    <ResponseField name="submissionId" type="string" required>
      Constraints: format `uuid`.
    </ResponseField>

    <ResponseField name="index" type="integer" required />

    <ResponseField name="clientReferenceId" type="string" />

    <ResponseField name="status" type="string" required>
      Allowed values: `queued`, `processing`, `succeeded`, `failed`, `deduplicated`.
    </ResponseField>

    <ResponseField name="errorCode" type="string" />

    <ResponseField name="errorMessage" type="string" />

    <ResponseField name="candidateUserId" type="string" />

    <ResponseField name="updatedAt" type="string" required />
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://external-api.paraform.com/api/external/v1/talent-network/batches/$BATCH_ID" \
    -H "Authorization: Bearer $PARAFORM_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "string",
    "itemCount": 0,
    "items": [
      {
        "submissionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "index": 0,
        "status": "queued",
        "updatedAt": "string"
      }
    ]
  }
  ```
</ResponseExample>


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