▣ ARTIFICIAL INTELLIGENCE · HR

Related Job Positions Generator API

What it does

Related Job Positions Generator takes a job title or role name and returns related positions ranked by relevance. Submit content with the role you want to expand from, and you can also set language and max_quantity to control the response.

The service is designed for HR and recruiting workflows where you want to build out comparable roles, adjacent titles, or alternative search terms from a single input. For example, you can start with a title like "Product Manager" and use the generated list to broaden candidate sourcing, normalize job taxonomies, or suggest related roles in a careers product.

The POST endpoint submits the job and returns a job_id plus a status_url you can poll. When the job completes, the status endpoint returns a structured result that includes the original job_position, a related_job_positions array, and a status value such as queued, running, failed, or success.

Use Related Job Positions Generator when you need machine-generated role expansion without building your own title-matching logic. It gives you a simple asynchronous flow: submit one role, poll for completion, and read back related positions with their relevance weights.

▣ ENDPOINT 01 / 02

POST

Related Job Positions Generator - Submit Job

https://api.eu.apyverse.com/sharpapi/related-job-positions-generator

QUICKSTART

GUIDE

Quickstart

Submit a job to generate related positions from a given role.

curl -X POST "https://api.eu.apyverse.com/sharpapi/related-job-positions-generator" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Software Engineer"}'

What you'll get back

Returns a JSON object with job_id and status_url fields. job_id is a UUID for the submitted job, and status_url is the URI you can poll for status and results.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_url": "https://example.com/jobs/550e8400-e29b-41d4-a716-446655440000"
}

TRY ITLIVE · 50 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

Submits an async job to generate related job positions for the provided role or job title. The request body supplies the input content and optional generation settings, and the response returns a job identifier plus a URL to check the job status and result later.

Request Body

Parameter	Type	Mandatory	Description
content	String	Yes	Provide a job position/role to generate related job positions for.
language	String	No	Specify the language of the output. Default: `English`.
max_quantity	Number	No	Maximum number of related job positions to generate. Minimum: `1`.

Response

Returns a JSON object with a job_id string field and a status_url string field. job_id is the unique identifier of the submitted job, and status_url is the URL used to poll for the job’s status and result.

Parameter	Type	Mandatory	Description
job_id	String	No	The unique identifier of the submitted job. Format: UUID.
status_url	String	No	URL to poll for the job's status and result. Format: URI.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Use the returned job_id to track the job, and the status_url can be used to poll for updates.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 02

GET

Related Job Positions Generator - Check Job Status

https://api.eu.apyverse.com/sharpapi/related-job-positions-generator/job/status/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a related job by its job_id.

curl -X GET "https://api.eu.apyverse.com/sharpapi/related-job-positions-generator/job/status/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object. The data object includes id, type, and attributes; attributes includes type, result, and status.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "api_job_result",
    "attributes": {
      "type": "hr_related_job_positions",
      "result": {
        "job_position": "Software Engineer",
        "related_job_positions": [
          {
            "name": "Backend Engineer",
            "weight": 0.92
          }
        ]
      },
      "status": "success"
    }
  }
}

TRY ITLIVE · 1 ATOM

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

Checks the status of a related job positions generation job using the job_id path parameter. On success, it returns a JSON object containing the job result wrapper and its status information.

Path Parameter(s)

Attribute	Type	Mandatory	Description
job_id	String	Yes	The job identifier, formatted as a UUID.

Response

Returns a JSON object with a data object field. The data object contains the job result id string, type string, and an attributes object with type, result, and status fields. The status field is an enum with running, failed, queued, and success.

Attribute	Type	Mandatory	Description
data	Object	No	Wrapper object for the job result.
data.id	String	No	The job result identifier, formatted as a UUID.
data.type	String	No	The response type.
data.attributes	Object	No	Job attributes, including result data and status.
data.attributes.type	String	No	The result type.
data.attributes.result	Object	No	The generated related job positions result object.
data.attributes.result.job_position	String	No	The original job position or role that was submitted.
data.attributes.result.related_job_positions	Object Array	No	The list of generated related job positions with their relevance weights.
data.attributes.result.related_job_positions[].name	String	No	The name of the related job position.
data.attributes.result.related_job_positions[].weight	Number	No	The relevance weight of this related job position.
data.attributes.status	ENUM	No	Status of the job. Allowed values: `running`, `failed`, `queued`, `success`.

Path parameters

Name

Type

Description

job_idREQUIRED

string

—

▣ 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.