# Sessions

> Embed InsureTrek license applications in your platform with the Sessions API: pre-fill profile data, create a session, redirect the user, and get webhooks.

Note

**Early Access** — The Sessions API is in development. If you're interested in integrating, reach out to [hello@insuretrek.com](mailto:hello@insuretrek.com) and we'll get you set up as an early partner.

## Overview

The Sessions API lets you embed InsureTrek license applications directly into your platform. Instead of building complex application forms yourself, you create a **session** via API and redirect your user to InsureTrek. We handle the hard parts — SSN collection, \~150 dynamic background questions, state-specific disclosures, and payment — then redirect the user back to your app when they're done.

## How It Works

1. **Sync profile data** — Pre-fill what you already know (name, NPN, address, etc.) so your user doesn't have to re-enter it.
2. **Create a session** — Call the API with the license type, states, and payment preference. You get back a URL.
3. **Redirect your user** — Send them to the InsureTrek application URL. They complete SSN entry, background questions, disclosures, and payment in our secure environment.
4. **Receive webhooks** — Get notified when the application is submitted, approved, denied, or needs action.

## Pre-filling Profile Data

Sync your user's profile ahead of time so the application is pre-filled when they arrive.

```
curl -X PATCH https://api.insuretrek.com/v1/users/usr_abc123/licensing-profile \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "npn": "12345678",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "555-123-4567",
    "dateOfBirth": "1990-01-15",
    "residentialAddress": {
      "street": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    }
  }'
```

Sensitive data like SSN and background question answers are **never** transmitted through your systems — they're always collected directly by InsureTrek.

## Creating a Session

```
curl -X POST https://api.insuretrek.com/v1/applications/sessions \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_abc123",
    "applicationType": "new",
    "licenseType": "life_health",
    "states": ["TX", "CA"],
    "paymentMethod": "user_pays",
    "returnUrl": "https://yourapp.com/callback",
    "webhookUrl": "https://yourapp.com/webhooks"
  }'
```

**Response:**

```
{
  "sessionId": "sess_xyz",
  "applicationId": "app_abc",
  "applicationUrl": "https://apply.insuretrek.com/s/xyz",
  "estimatedFees": { "total": 155.00 },
  "prefilled": { "npn": true, "ssn": false, "backgroundQuestions": false }
}
```

Redirect your user to `applicationUrl`. When they finish, they're sent back to your `returnUrl` with a status parameter (e.g., `?status=submitted`).

## Checking Application Status

```
curl https://api.insuretrek.com/v1/applications/app_abc \
  -H "Authorization: Bearer your-access-token"
```

Returns status per state: `pending_review`, `approved`, `denied`, or `requires_action`.

## Webhooks

Subscribe to events instead of polling. InsureTrek sends POST requests to your `webhookUrl` as the application progresses.

| Event                         | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| application.session\_started  | User opened the application URL                              |
| application.progress\_updated | User completed a step                                        |
| application.submitted         | Application submitted to the state                           |
| application.status\_changed   | State approved, denied, or updated the application           |
| application.requires\_action  | User action needed — includes an actionUrl to send them back |

## Payment Options

| Method           | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| user\_pays       | User pays state + processing fees during the application (default) |
| partner\_billing | Partner invoiced monthly. User skips the payment step.             |

Note

**Interested?** The Sessions API is in early access. Email [hello@insuretrek.com](mailto:hello@insuretrek.com) to get started.