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

# Integration Flow

> End-to-end flow for criteria setup, scoring, and webhooks

## Phase 1: Job setup (once per job)

<Steps>
  <Step title="Generate clarification questions (optional)">
    `POST /v1/jobs/{jobId}/question-sets` with your job context.

    Store `questionSet.id` and show `questionSet.questions` in your UI.
  </Step>

  <Step title="Generate criteria">
    `POST /v1/jobs/{jobId}/criteria/generate` with your job context.

    If you collected answers, include `questionSetId` and `answers`.
  </Step>

  <Step title="Refine criteria (optional)">
    Use the [criteria management endpoints](/embed-api/endpoints/criteria/overview) to add, edit, remove, or archive criteria. See [criteria versioning](/embed-api/concepts/criteria-versioning) for how changes affect scoring.
  </Step>
</Steps>

## Phase 2: Application scoring (per application)

<Steps>
  <Step title="Generate a resume URL">
    Produce a public HTTPS URL. See [supported formats](/embed-api/guides/supported-formats) for requirements.
  </Step>

  <Step title="Submit a scoring request">
    `POST /v1/jobs/{jobId}/applications/{applicationId}/scoring-jobs` with the `resume` object and `jobDescription`.

    Store `scoringJob.id` and `scoringJob.criteriaVersionId` for webhook correlation and polling. See [idempotency](/embed-api/concepts/idempotency) for retry, duplicate submission, and re-scoring behavior.
  </Step>

  <Step title="Handle webhooks">
    Verify the signature and process `score.completed` and `score.failed` events. See [webhooks](/embed-api/concepts/webhooks).
  </Step>
</Steps>

## Polling fallback

If you miss a webhook: `GET /v1/jobs/{jobId}/applications/{applicationId}/scoring-jobs/{scoringJobId}`

## Phase 3: Deletion handling

Build deletion calls into your customer offboarding and application deletion workflows.

<Steps>
  <Step title="Delete one application">
    Call `DELETE /v1/jobs/{jobId}/applications/{applicationId}` with `X-Tenant-Id`.

    Use this when an application must be removed before automatic cleanup runs.
  </Step>

  <Step title="Delete one tenant">
    Call `DELETE /v1/tenants/{tenantExternalId}` when a customer leaves or asks you to delete all tenant data.

    This endpoint scopes the request by path, so it doesn't need `X-Tenant-Id`.
  </Step>

  <Step title="Poll for completion">
    Store the returned `deletionRequest.id` and poll `GET /v1/deletion-requests/{deletionRequestId}` until the request is `completed` or `failed`.

    Completed responses confirm the request was processed. Nova keeps internal cleanup evidence separately.
  </Step>
</Steps>

See [Deletion Requests](/embed-api/endpoints/deletion/overview) for the API flow and [Data Retention](/embed-api/concepts/data-retention) for retention windows.