Job Position Directory — list roles and related jobs

Job Positions API

What it does

Job Position Directory returns a paginated list of job positions with stable identifiers, names, and URL-friendly slugs. Send optional query parameters to filter by name, control per_page, and include related roles when you need a richer view of the job taxonomy.

Use it when you need a canonical source of role names for hiring flows, onboarding forms, search autocomplete, or internal HR tooling. The response gives you a data array of job position objects, plus pagination meta and navigation links so you can build result lists page by page.

When include_related is set to true, each job position can also include related_job_positions, with related role IDs, names, slugs, and relevancy weight values. That makes it useful for suggesting adjacent roles, building role-mapping logic, or grouping similar positions in a talent product.

If you only need the basics, keep the request simple and work from id, name, and slug. If you need relationship data, opt in explicitly and use the returned weights to rank the related positions.

What you'll get back

Returns a JSON object with data (an array of job position objects), meta (pagination details), and links (pagination URLs).

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Software Engineer",
      "slug": "software-engineer"
    }
  ],
  "meta": {
    "to": 1,
    "from": 1,
    "path": "https://example.com",
    "links": [],
    "total": 1,
    "per_page": 1,
    "last_page": 1,
    "current_page": 1
  },
  "links": {
    "last": "https://example.com?page=1",
    "next": null,
    "prev": null,
    "first": "https://example.com?page=1"
  }
}

About this endpoint

What it does

Returns a paginated list of job positions. You can filter the results by name, and optionally include related job positions in each item.

Query Parameter(s)

Attribute	Type	Mandatory	Description
name	String	No	Filters job positions by name.
per_page	Integer	No	Number of items returned per page. Default: `1`.
include_related	Boolean	No	Whether to include `related_job_positions` in each result item. Default: `false`.

Response

Returns a JSON object with three top-level fields: data is an array of job position objects, meta is an object containing pagination metadata, and links is an object containing pagination URLs. This endpoint is paginated.

Parameter	Type	Mandatory	Description
data	Object Array	Yes	List of job positions returned for the current page. Each item includes `id`, `name`, `slug`, and, when `include_related` is `true`, `related_job_positions`.
data[].id	String	Yes	Unique identifier of the job position. Format: UUID.
data[].name	String	Yes	Name of the job position.
data[].slug	String	Yes	URL-friendly slug for the job position.
data[].related_job_positions	Object Array	No	Related job positions with their relevancy weights. Only populated when `include_related` is set to `true`.
data[].related_job_positions[].id	String	Yes	Unique identifier of the related job position. Format: UUID.
data[].related_job_positions[].name	String	Yes	Name of the related job position.
data[].related_job_positions[].slug	String	Yes	URL-friendly slug for the related job position.
data[].related_job_positions[].weight	Number	Yes	Relevancy weight of the related job position.
meta	Object	Yes	Pagination metadata for the current result set.
links	Object	Yes	Pagination navigation links.

Query parameters

Name

Type

Description

nameOPTIONAL

string

—

per_pageOPTIONAL

integer

—

DEFAULT 1

include_relatedOPTIONAL

boolean

—

DEFAULT false

Job Positions API

What it does

Quickstart

What you'll get back

About this endpoint

What it does

Query Parameter(s)

Response

Query parameters

Errors any endpoint can return