▣ HR

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.

GET

List Job Positions

https://api.eu.apyhub.com/sharpapi/list-job-positions

QUICKSTART

GUIDE

Quickstart

List job positions with the default page size.

curl -X GET "https://api.eu.apyhub.com/sharpapi/list-job-positions?per_page=1" \
  -H "apy-token: $APY_TOKEN"

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

TRY ITLIVE · 1000 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

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	Description
name	String	Filters job positions by name.
per_page	Integer	Number of items returned per page. Default: `1`.
include_related	Boolean	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	Description
data	Object Array	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	Unique identifier of the job position. Format: UUID.
data[].name	String	Name of the job position.
data[].slug	String	URL-friendly slug for the job position.
data[].related_job_positions	Object Array	Related job positions with their relevancy weights. Only populated when `include_related` is set to `true`.
data[].related_job_positions[].id	String	Unique identifier of the related job position. Format: UUID.
data[].related_job_positions[].name	String	Name of the related job position.
data[].related_job_positions[].slug	String	URL-friendly slug for the related job position.
data[].related_job_positions[].weight	Number	Relevancy weight of the related job position.
meta	Object	Pagination metadata for the current result set.
links	Object	Pagination navigation links.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

From the blog

Reads that touch this API.

Top 5 Rank Tracking APIs to Build Your Own SEO Monitoring StackAug 24, 2026 7 AI Hiring APIs to Automate Recruitment, From Job Post to Offer (2026)Aug 5, 2026 Building an Application Tracking System using Retool and ApyHub Aug 7, 2026 AI-Powered HR APIs Transforming Recruitment in 2026Jul 9, 2026