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

# Magic Link

> Generate a magic login link for an applicant

## Generate Magic Login Link

Generate a magic login link for an applicant. When the applicant clicks the link, an application will be created (or found if exists) and they will be logged in automatically.

### Endpoint

```
POST /external/v1/applications/magic-link/
```

### Authentication

> \[!NOTE]
> Requires a valid company API key in the `Authorization` header (format: `Api-Key <key>`).

### Request Body

| Field                        | Type           | Required    | Description                                                                 |
| ---------------------------- | -------------- | ----------- | --------------------------------------------------------------------------- |
| `email`                      | string (email) | Yes         | The email address of the applicant                                          |
| `hiring_flow_id`             | string (UUID)  | Conditional | The ID of the hiring flow (required if `hiring_flow_slug` not provided)     |
| `hiring_flow_slug`           | string         | Conditional | The slug of the hiring flow (required if `hiring_flow_id` not provided)     |
| `full_name`                  | string         | No          | The full name of the applicant                                              |
| `phone_number`               | string         | No          | The phone number of the applicant                                           |
| `application_data`           | object         | No          | Form submission data to pre-fill in the application                         |
| `page_or_stage_id`           | string (UUID)  | No          | Stage/page ID to move the application to after creation                     |
| `stage_reason_id`            | string (UUID)  | No          | Reason ID for the stage transition                                          |
| `expiry_duration_in_seconds` | integer        | No          | Duration in seconds until the magic link expires. Defaults to 86400 (1 day) |

### Example Request

```bash theme={null}
curl -X POST "https://api.firstwork.com/external/v1/applications/magic-link/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "hiring_flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "John Doe",
    "phone_number": "+1234567890",
    "expiry_duration_in_seconds": 172800
  }'
```

### Responses

#### 200: OK

Successfully generated magic login link.

#### 400: Bad Request

Missing required fields or invalid hiring flow.

#### 500: Internal Server Error

Internal server error occurred while generating the magic link.

### Notes

* Magic links expire after the configured duration (default: 24 hours)
* The link logs the user in and redirects to their application
* If the candidate already has an application in the flow, the existing application is used
* Useful for sending in SMS or email notifications