---
title: Embedding API
slug: embedding-api
docTags: 
createdAt: 2025-09-10T15:02:44.830Z
---

Welcome to the **Jobylon Embedding API**! 

This API allows you to integrate your pages into the Jobylon ATS platform, creating a smooth and unified experience for users.

We currently support embedding in the following areas:

- **Main Dashboard**: Add your page to the main dashboard.
- **Company Settings**: Add your page to the settings of a company.
- **Application Detail**: Provide detailed insights or actions related to specific applications.
- **Application Search for a job**: Add your page to a job.

## Provisioning

If you wish to be notified when a new company registers the integration in Jobylon ATS, we provide an optional possibility to provision the integration by sending a webhook from Joblylon ATS to your system with the following sample data:

```json
{
  "company_id": 123,
  "initial_data": {
    "company_name": "Example Company"
  }
}
```

To enable that, Jobylon ATS requires a **Callback URL **to your system.

## Authentication

Partners should implement a url for Jobylon to retrieve a token for a user per company.

- Tokens should be user-specific. If a lifetime is not provided, we will default to manually setting the token's lifespan to **one hour**.
- You need to provide us with **Token URL,** an **App ID** and an **App Key**, which Jobylon ATS will use to generate user specific tokens.

Upon token requests, Jobylon ATS posts the following payload to the partner:

```json
{
  "company_id": 123,
  "email": "user@example.com",
  "full_name": "User Userson",
  "role": "member"
}
```

Role can be one of the following: owner, admin, manager, member.

## Localisation

Jobylon will pass the user's language as a query parameter in the iframe URL.

- The language codes follow the **ISO 639-1** standard (e.g., `en` for English, `sv` for Swedish).
- It is up to you to decide whether to act on this parameter or ignore it.

## Security

- All endpoints must originate from the **same domain**.

## Specific Endpoints

Below is an overview of how each specific URL is structured and behaves. Here is an example for reference:

`https://domain.com/embed/dashboard/?token=xxx&company=xxx`

### Navigation Bar and Company Settings

These are the simplest endpoints to implement. In these cases, we will pass the **company ID** as a parameter. This allows you to tailor the content or functionality based on the specific company.

Example: `https://domain.com/embed/dashboard/?token=xxx&company=xxx`

### Application Search for a job

For the application search endpoint, we will pass the **job ID**. This enables you to provide job-specific functionality or data. Additionally, we will listen for events related to authentication or authorisation issues.

Example: `https://domain.com/embed/dashboard/?token=xxx&job_id=xxx`

### Application Detail

In the application detail endpoint, we will pass the **applicant ID**. Similar to the application search, we will monitor events for any authentication or authorisation issues, and handle errors.

Example: `https://domain.com/embed/dashboard/?token=xxx&application_id=xxx`

## Events

To accomodate for error handling, Jobylon ATS will listen for [message events](https://developer.mozilla.org/en-US/docs/Web/API/Window/message_event) from your integration. 

In the example of application detail iFrame, if an application exists in Jobylon ATS but not in your system, you can notify us using the following format:

```json
{
  "partner": "Name of the partner",
  "api": "Embedding",
  "payload": {
    "error": "not_found"
  }
}
```