# API documentation

### Get started

This reference helps you implement the RESTful JOIN API v2. The API allows you to interact with your JOIN data programmatically – for example, to fetch job listings, retrieve applications, or manage candidate records.

The JOIN API is stateless, meaning each request must include authentication and does not rely on prior interactions. To use the API, you’ll need to generate an API token from your JOIN account.

<a href="https://docs.join.com/reference/getting-started" class="button primary">Read full API documentation</a>

***

### Authentication

To validate your API requests, JOIN requires an API token. This token identifies you and links actions performed via the API to your JOIN account.

#### Generating an API token

1. Go to `User Settings` in your JOIN account
2. Click `API Credentials`
3. Click `Generate new Token`

{% hint style="warning" %}
Keep your API token secure. It provides access to your company data in JOIN, including the ability to read, update or delete information.
{% endhint %}

#### Using the API token

You must include your token in the `Authorization` header of every API request.

**Example request:**

```bash
curl -X GET \
  https://api.join.com/v2/jobs \
  -H 'Authorization: your-api-token-here'
```

#### Revoking the API token

You can revoke a token at any time in the `API Credentials` section of your account. Keep in mind that:

* Once revoked, the token can no longer be used
* Tokens cannot be reactivated or regenerated
* You must update your integration with a new token if one is revoked

***

### Available API resources

JOIN’s API v2 gives you access to various key areas of your recruitment data. Below is a list of available endpoints grouped by category. These endpoints allow you to fetch or manage data, depending on your integration needs.

Click on the provided 'Read more' links to read the full technical documentation:

### Jobs

<table><thead><tr><th width="210.34375">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Create job </td><td>Create a new job and publish it on JOIN<br><a href="https://docs.join.com/reference/createjob">Read more</a></td></tr><tr><td>Get all jobs</td><td>Retrieve a list of all jobs<br><a href="https://docs.join.com/reference/getjobs">Read more</a></td></tr><tr><td>Get job</td><td>Fetch detailed information about a single job<br><a href="https://docs.join.com/reference/getjob">Read more</a></td></tr><tr><td>Update job</td><td>Update an existing job<br><a href="https://docs.join.com/reference/updatejob">Read more</a></td></tr><tr><td>Update a job status</td><td>Modify the status of a job (e.g. published, closed)<br><a href="https://docs.join.com/reference/updatejobstatus">Read more</a></td></tr><tr><td>Activate job</td><td>Activate a job that is currently inactive<br><a href="https://docs.join.com/reference/activatejob">Read more</a></td></tr><tr><td>Archive job</td><td>Archive a job so it no longer appears as active<br><a href="https://docs.join.com/reference/archivejob">Read more</a></td></tr></tbody></table>

### Applications

<table><thead><tr><th width="210.25390625">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get all applications</td><td>Retrieve a list of all applications received<br><a href="https://docs.join.com/reference/getapplications">Read more</a></td></tr><tr><td>Create application</td><td>Add a new application to a job manually<br><a href="https://docs.join.com/reference/createapplication">Read more</a></td></tr><tr><td>Get application</td><td>Fetch detailed data of a specific application<br><a href="https://docs.join.com/reference/getapplication">Read more</a></td></tr><tr><td>Delete application</td><td>Remove an application permanently<br><a href="https://docs.join.com/reference/deleteapplication">Read more</a></td></tr><tr><td>Update application tags</td><td>Modify tags associated with an application<br><a href="https://docs.join.com/reference/updateapplicationtags">Read more</a></td></tr></tbody></table>

### Application integration data

<table><thead><tr><th width="210.0625">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Update application integration data</td><td>Attach an external ID to the application record for third-party system reference<br><a href="https://docs.join.com/reference/updateapplicationintegrationdata">Read more</a></td></tr></tbody></table>

### Categories

<table><thead><tr><th width="210.03125">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get all categories</td><td>Returns all available job categories used in JOIN<br><a href="https://docs.join.com/reference/getcategories">Read more</a></td></tr></tbody></table>

### Employment types

<table><thead><tr><th width="210.2734375">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get all employment types</td><td>Returns all standard employment types (e.g. Full-time, Internship)<br><a href="https://docs.join.com/reference/getemploymenttypes">Read more</a></td></tr></tbody></table>

### Seniority levels

<table><thead><tr><th width="209.67578125">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get all seniority levels</td><td>Returns all job seniority levels (e.g. Entry-level, Executive)<br><a href="https://docs.join.com/reference/getsenioritylevels">Read more</a></td></tr></tbody></table>

### Offices

<table><thead><tr><th width="209.51171875">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get all offices</td><td>Retrieve all offices created in JOIN<br><a href="https://docs.join.com/reference/getoffices">Read more</a></td></tr><tr><td>Create office</td><td>Add a new office location<br><a href="https://docs.join.com/reference/createoffice">Read more</a></td></tr><tr><td>Get office</td><td>Get details of a specific office<br><a href="https://docs.join.com/reference/getoffice">Read more</a></td></tr><tr><td>Update office</td><td>Edit existing office information<br><a href="https://docs.join.com/reference/updateoffice">Read more</a></td></tr></tbody></table>

### Candidates

<table><thead><tr><th width="210.46484375">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Create candidate note</td><td>Add a note to a candidate profile<br><a href="https://docs.join.com/reference/createcandidatenote">Read more</a></td></tr><tr><td>Get all candidate notes</td><td>View all notes linked to a candidate<br><a href="https://docs.join.com/reference/getcandidatenotes">Read more</a></td></tr><tr><td>Update candidate note</td><td>Edit an existing note<br><a href="https://docs.join.com/reference/updatecandidatenote">Read more</a></td></tr><tr><td>Delete candidate note</td><td>Remove a note from a candidate profile<br><a href="https://docs.join.com/reference/deletecandidatenote">Read more</a></td></tr><tr><td>Update candidate</td><td>Update a candidate's profile fields<br><a href="https://docs.join.com/reference/updatecandidate">Read more</a></td></tr></tbody></table>

### Attachments

<table><thead><tr><th width="209.69140625">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>Get attachment by ID</td><td>Retrieve a specific attachment such as a CV<br><a href="https://docs.join.com/reference/getattachmentbyid">Read more</a></td></tr><tr><td>Get application file by ID</td><td>Access files submitted with an application<br><a href="https://docs.join.com/reference/getapplicationfilebyid">Read more</a></td></tr></tbody></table>

{% hint style="info" %}
You’ll need appropriate API permissions and an active token to use these endpoints.
{% endhint %}

#### &#x20; <a href="#discover-the-platform" id="discover-the-platform"></a>