API Introduction

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:

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

Response Format

All API responses follow a consistent JSON format:

{
  "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

Pagination

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

Getting Started

Features

Settings

Overview

Base URL

API Versions

Quick Start

Available Endpoints

Applications

Hiring Flows

Candidates

Automations

Other

Response Format

Error Responses

HTTP Status Codes

Rate Limiting

​Overview

​Base URL

​API Versions

​Quick Start

​Available Endpoints

​Applications

​Hiring Flows

​Candidates

​Automations

​Other

​Response Format

​Error Responses

​HTTP Status Codes

​Rate Limiting

​Pagination

Overview

Base URL

API Versions

Quick Start

Available Endpoints

Applications

Hiring Flows

Candidates

Automations

Other

Response Format

Error Responses

HTTP Status Codes

Rate Limiting

Pagination