apyhub
▣ HR · SMART GENERATION

Job Description Generator API

What it does

Job Description Generator creates structured job descriptions from a job title and optional hiring context. Send a name and, when needed, add fields like remote, country, language, voice_tone, company_name, visa_sponsored, employment_type, optional_skills, required_skills, minimum_education, minimum_work_experience, and context.

Use it when you need a fast first draft for a new opening, a localized posting, or a role description that reflects specific hiring constraints. The submit endpoint returns a job_id and status_url so you can track generation asynchronously.

When the job finishes, the status endpoint returns a data object with id, type, and attributes. Inside attributes, you get status plus a result object containing job_requirements, job_responsibilities, and job_short_description.

Job Description Generator is useful for HR teams, recruiters, and internal tools that need consistent job copy without hand-writing every posting. It fits workflows where a title, a few requirements, and basic role metadata need to become a ready-to-review description.

▣ ENDPOINT 01 / 02
POST
Job Description Generator - Submit Job
http://localhost:8080/sharpapi/job-description-generator
QUICKSTARTGUIDE

Quickstart

Submit a job description generation request with the required job title.

curl -X POST "http://localhost:8080/sharpapi/job-description-generator" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Senior PHP Software Engineer"}'

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 for the submitted job, and status_url is the URL you can poll for the job status and result.

{
  "status_url": "https://apyhub.com/services/provider/sharpapi/api/v1/hr/job_description/job/status/4443651e-378c-4daf-b1a5-bd341358bdf7",
  "job_id": "4443651e-378c-4daf-b1a5-bd341358bdf7"
}
TRY ITLIVE · 50 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
The job title for the position (e.g., Senior PHP Software Engineer).
Specifies if the job is remote.
Additional context or requirements (e.g., add requirement of C-class driving license).
The country where the job is located (e.g., United Kingdom).
The language for the job description (e.g., English).
The tone of voice for the description (e.g., neutral, professional).
The name of the company offering the position (e.g., Apple Inc).
Specifies if visa sponsorship is available.
Type of employment (e.g., full time, part time, contract).
optional_skills
A list of optional skills for the position.
required_skills
A list of required skills for the position.
The minimum required education level (e.g., Bachelor Degree).
The minimum required work experience (e.g., 5 years).

About this endpoint

What it does

Submits a job-description generation request and starts an async job. The request body contains the job details to use, and the response returns a job identifier plus a status URL for polling.

Request Body

ParameterTypeMandatoryDescription
nameStringYesThe job title for the position.
remoteBooleanNoSpecifies if the job is remote.
contextStringNoAdditional context or requirements.
countryStringNoThe country where the job is located.
languageStringNoThe language for the job description.
voice_toneStringNoThe tone of voice for the description.
company_nameStringNoThe name of the company offering the position.
visa_sponsoredBooleanNoSpecifies if visa sponsorship is available.
employment_typeStringNoType of employment.
optional_skillsString ArrayNoA list of optional skills for the position.
required_skillsString ArrayNoA list of required skills for the position.
minimum_educationStringNoThe minimum required education level.
minimum_work_experienceStringNoThe minimum required work experience.

Response

Returns a JSON object with two required string fields: job_id and status_url. job_id is a UUID identifying the submitted job, and status_url is a URI used to poll for the job's status and result.

ParameterTypeMandatoryDescription
job_idStringYesThe unique identifier of the submitted job. Format: UUID.
status_urlStringYesURL 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 job_id field from the response to track the job.

Body

Name
Type
Description
bodyREQUIRED
object
—
▣ ENDPOINT 02 / 02
GET
Job Description Generator - Check Job Status
http://localhost:8080/sharpapi/job-description-generator/job/status/:job_id
QUICKSTARTGUIDE

Quickstart

Check the status of a job by its job_id.

curl -X GET "http://localhost:8080/sharpapi/job-description-generator/job/status/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object. Inside data, the id is a UUID, type is the response type, and attributes contains the job status plus the generated result data when available.

{
  "data": {
    "id": "2f1c2d4a-8c9d-4f4b-9f86-8c5f2f0d5d2e",
    "type": "api_job_result",
    "attributes": {
      "type": "hr_job_description",
      "result": {
        "job_requirements": "- 3+ years of experience\n- Strong communication skills",
        "job_responsibilities": "- Write job descriptions\n- Collaborate with hiring managers",
        "job_short_description": "A concise summary of the generated job description."
      },
      "status": "success"
    }
  }
}
TRY ITLIVE · 1 ATOM
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 job description generation job by job ID and returns the job record in the response. When the job succeeds, the generated job description content is available in the nested result object.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

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

ParameterTypeMandatoryDescription
dataObjectNoWrapper object containing the job record.
data.idStringNoJob result identifier in UUID format.
data.typeStringNoResource type for the job result.
data.attributesObjectNoObject containing the job attributes: type, result, and status.
data.attributes.typeStringNoJob attribute type.
data.attributes.resultObjectNoGenerated job description content returned when the job reaches success.
data.attributes.result.job_requirementsStringNoThe generated list of job requirements, formatted as a bullet list.
data.attributes.result.job_responsibilitiesStringNoThe generated list of job responsibilities, formatted as a bullet list.
data.attributes.result.job_short_descriptionStringNoA short, narrative summary of the job description.
data.attributes.statusENUMNoJob status. Allowed values: running, failed, queued, success.

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); the result fields under data.attributes.result are only populated 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.

Product
CatalogPricingBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS