> ## 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.

# API Introduction

> Integrate with Firstwork using our REST API for applications, hiring flows, candidates, and automations

## Overview

The Firstwork API provides programmatic access to manage applications, hiring flows, candidates, automations, and more. It's designed for integrating Firstwork with your existing systems, building custom workflows, and automating HR operations.

## Base URL

All API requests are made to your Firstwork instance's external API base path:

```
https://your-instance.firstwork.com/external/
```

## API Versions

| Version | Base Path       | Status |
| ------- | --------------- | ------ |
| v1      | `/external/v1/` | Stable |
| v2      | `/external/v2/` | Latest |

> \[!NOTE]
> New integrations should use v2 endpoints where available. v1 endpoints are maintained for backward compatibility.

## Quick Start

Here's a quick example to list all hiring flows:

```bash theme={null}
curl -X GET "https://your-instance.firstwork.com/external/v1/hiring-flow/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Available Endpoints

### Applications

| Endpoint                                                                               | Method | Description               |
| -------------------------------------------------------------------------------------- | ------ | ------------------------- |
| [`/v1/application/create/`](/api-reference/endpoints/create-application)               | POST   | Create a new application  |
| [`/v1/applications/`](/api-reference/endpoints/list-applications)                      | GET    | List applications         |
| [`/v1/applications/{id}/`](/api-reference/endpoints/get-application)                   | GET    | Get application details   |
| [`/v1/applications/{id}/advance/`](/api-reference/endpoints/update-application-status) | POST   | Update application status |
| [`/v1/applications/{id}/history/`](/api-reference/endpoints/application-history)       | GET    | Get transition history    |
| `/v1/applications/advance/`                                                            | POST   | Bulk update status        |
| `/v1/applications/bulk_transition_history/`                                            | POST   | Bulk transition history   |
| `/v1/applications/{id}/upload_documents/`                                              | POST   | Upload documents          |
| `/v2/applications/`                                                                    | GET    | List applications (v2)    |

### Hiring Flows

| Endpoint                                                            | Method | Description             |
| ------------------------------------------------------------------- | ------ | ----------------------- |
| [`/v1/hiring-flow/`](/api-reference/endpoints/list-hiring-flows)    | GET    | List hiring flows       |
| [`/v1/hiring-flow/{id}/`](/api-reference/endpoints/get-hiring-flow) | GET    | Get hiring flow details |

### Candidates

| Endpoint                                                                             | Method | Description                         |
| ------------------------------------------------------------------------------------ | ------ | ----------------------------------- |
| [`/v1/get_candidate_data`](/api-reference/endpoints/get-candidate)                   | GET    | Get candidate data                  |
| [`/v1/create_or_update_candidate`](/api-reference/endpoints/create-update-candidate) | POST   | Create or update candidate          |
| `/v1/get_candidate_data_and_submissions/`                                            | GET    | Get candidate data with submissions |

### Automations

| Endpoint                                                                               | Method | Description            |
| -------------------------------------------------------------------------------------- | ------ | ---------------------- |
| [`/v1/automations/webhooks/{id}/fire/`](/api-reference/endpoints/fire-webhook-trigger) | POST   | Fire a webhook trigger |

### Other

| Endpoint                                                                      | Method | Description               |
| ----------------------------------------------------------------------------- | ------ | ------------------------- |
| [`/v1/company/`](/api-reference/endpoints/company-info)                       | GET    | Get company information   |
| [`/v1/external_billing_data_export`](/api-reference/endpoints/billing-export) | GET    | Export billing data       |
| [`/v1/applications/magic-link/`](/api-reference/endpoints/magic-link)         | POST   | Generate magic login link |

## Response Format

All API responses follow a consistent JSON format:

```json theme={null}
{
  "status": "success",
  "data": {
    // Response data
  }
}
```

### Error Responses

```json theme={null}
{
  "status": "error",
  "message": "Description of the error",
  "code": "ERROR_CODE"
}
```

### HTTP Status Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 201  | Created                                   |
| 400  | Bad Request — Invalid parameters          |
| 401  | Unauthorized — Invalid or missing API key |
| 403  | Forbidden — Insufficient permissions      |
| 404  | Not Found — Resource doesn't exist        |
| 429  | Too Many Requests — Rate limit exceeded   |
| 500  | Internal Server Error                     |

## Rate Limiting

API requests are rate-limited to ensure fair usage:

* **Default limit:** 100 requests per minute per API key
* **Burst limit:** 20 requests per second
* Rate limit headers are included in responses

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /external/v1/applications/?page=1&page_size=50
```

| Parameter   | Description      | Default |
| ----------- | ---------------- | ------- |
| `page`      | Page number      | 1       |
| `page_size` | Results per page | 25      |