▣ HR · SMART GENERATION

Related Job Positions Generator API

What it does

Related Job Positions generates related roles from a job title or position you send in the request body. Submit a content string, and optionally set language and max_quantity to control the output language and how many suggestions you want back.

The first POST returns a job_id and a status_url. Use the status endpoint to poll by job_id until the job is complete. When the job succeeds, the response includes the original job_position and a related_job_positions array. Each related role includes a name and a weight so you can rank or filter the suggestions in your own workflow.

Use Related Job Positions when you need to expand a single role into nearby titles for recruiting, candidate search, career-path mapping, or internal taxonomy cleanup. For example, you can start with “Data Analyst” and build a shortlist of adjacent positions to power job recommendations or search suggestions.

The API is asynchronous, which makes it suitable for longer-running generation jobs without blocking your application. You submit once, then fetch the result when the status changes to success.

▣ ENDPOINT 01 / 02

POST

Related Job Positions Generator - Submit Job

http://localhost:8080/sharpapi/related-job-positions-generator

QUICKSTARTGUIDE

Quickstart

Submit a job to generate related positions for a role.

curl -X POST "http://localhost:8080/sharpapi/related-job-positions-generator" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Product Manager","language":"English","max_quantity":5}'

What you'll get back

Returns a JSON object with a job_id string and a status_url string. job_id is the unique identifier of the submitted job, and status_url is the URL to poll for status and results.

{
  "status_url": "https://apyhub.com/services/provider/sharpapi/api/v1/hr/related_job_positions/job/status/352ad2e4-191d-4ca5-bc75-38f87e04ede5",
  "job_id": "352ad2e4-191d-4ca5-bc75-38f87e04ede5"
}

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 asynchronous job to generate related job positions from a provided job role. The request sends the input in the body, and the response returns a job identifier plus a status URL for polling the job 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 job_id and status_url fields. job_id is a string UUID identifying the submitted job, and status_url is a string URI you can poll for the job's status and result.

Parameter	Type	Mandatory	Description
job_id	String	Yes	The unique identifier of the submitted job. Format: UUID.
status_url	String	Yes	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 poll the status_url field from the response.

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 02

GET

Related Job Positions Generator - Check Job Status

http://localhost:8080/sharpapi/related-job-positions-generator/job/status/:job_id

QUICKSTARTGUIDE

Quickstart

Check the status of a related-job-positions generation job by its job_id.

curl -X GET "http://localhost:8080/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 field. data contains the job result metadata, including 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 previously submitted related job positions generation job using its job ID. The response returns a data object containing the job result wrapper and 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. Inside data, the response includes an id UUID, a type string, and an attributes object containing the job type, status, and result object.

Attribute	Type	Mandatory	Description
data	Object	No	Wrapper object for the job status payload.
data.id	String	No	The job result identifier, formatted as a UUID.
data.type	String	No	The top-level resource type.
data.attributes	Object	No	Container for the job attributes, including `type`, `status`, and `result`.
data.attributes.type	String	No	The job type.
data.attributes.status	ENUM	No	Job status. Allowed values: `running`, `failed`, `queued`, `success`.
data.attributes.result	Object	No	The generated related job positions payload.
data.attributes.result.job_position	String	No	The original job position/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.

Notes

Poll this endpoint with the job_id returned by the submit call. The data.attributes.status field cycles through transitional values (queued, running) before reaching a terminal state (success, failed); read data.attributes.result once status is 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.