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 |
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:
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/ | POST | Create a new application |
/v1/applications/ | GET | List applications |
/v1/applications/{id}/ | GET | Get application details |
/v1/applications/{id}/advance/ | POST | Update application status |
/v1/applications/{id}/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/ | GET | List hiring flows |
/v1/hiring-flow/{id}/ | GET | Get hiring flow details |
Candidates
| Endpoint | Method | Description |
|---|
/v1/get_candidate_data | GET | Get candidate data |
/v1/create_or_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/ | POST | Fire a webhook trigger |
Other
| Endpoint | Method | Description |
|---|
/v1/company/ | GET | Get company information |
/v1/external_billing_data_export | GET | Export billing data |
/v1/applications/magic-link/ | POST | Generate magic login link |
{
"status": "success",
"data": {
// Response data
}
}
Error Responses
{
"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
List endpoints support pagination:
GET /external/v1/applications/?page=1&page_size=50
| Parameter | Description | Default |
|---|
page | Page number | 1 |
page_size | Results per page | 25 |
