# Create an Intake Session
Create a hosted intake session and hand the applicant a signed Klarefi intake URL
Source: https://www.klarefi.com/docs/guides/create-intake-session

## Overview

An intake session is the applicant-facing entry point for one case. Create a
session when your system knows which workflow should run and who needs to submit
answers or documents.

## Inputs

A session creation request should include:

- Case type identifier from your Klarefi dashboard
- Applicant or case reference from your system
- Optional callback or return destination
- Optional locale and trace ID for support/debugging

## Example Request

Install the SDK:

```bash
npm install @klarefi/node
```

Create the session from trusted server-side code:

```ts
import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  idempotency_key: "session_claim_48392",
  external_case_id: "claim_48392",
  external_applicant_id: "applicant_789",
  return_url: "https://claims.example.com/claim_48392",
  locale: "nl",
});

return Response.redirect(session.signed_url, 303);
```

For a CLI smoke test:

```bash
npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_48392 \
  --external-applicant-id applicant_789 \
  --return-url https://claims.example.com/claim_48392 \
  --url-only
```

The same request over HTTP:

```http
POST /api/v1/sessions
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
```

```json
{
  "case_type_id": "motor_claim",
  "idempotency_key": "session_claim_48392",
  "external_case_id": "claim_48392",
  "external_applicant_id": "applicant_789",
  "return_url": "https://claims.example.com/claim_48392",
  "locale": "nl"
}
```

The response contains `signed_url`, which can be opened by the applicant. Store
the Klarefi `session_id` alongside your own case identifier. In v1 hosted
sessions, the `session_id` is also the case ID used by case reads.

## Operational Guidance

Create sessions from trusted server-side code. Do not build session URLs in the
browser. Treat session links as scoped applicant access, and expire or revoke
them when the case no longer needs applicant input.

## Related Guides

- [Hosted intake](/docs/guides/hosted-intake)
- [Sessions API](/docs/api/sessions)
- [Webhook setup](/docs/guides/webhooks)
- [Sessions reference](/docs/reference/sessions)