apyhub
Back
▣ 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 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
https://api.eu.apyhub.com/sharpapi/job-description-generator

QUICKSTART

GUIDE

Quickstart

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

curl -X POST "https://api.eu.apyhub.com/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 — the UUID of the submitted job. Poll the job status endpoint with this id to retrieve the result.

{
  "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).

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.

Request Body

ParameterTypeDescription
nameStringThe job title for the position.
remoteBooleanSpecifies if the job is remote.
contextStringAdditional context or requirements.
countryStringThe country where the job is located.
languageStringThe language for the job description.
voice_toneStringThe tone of voice for the description.
company_nameStringThe name of the company offering the position.
visa_sponsoredBooleanSpecifies if visa sponsorship is available.
employment_typeStringType of employment.
optional_skillsString ArrayA list of optional skills for the position.
required_skillsString ArrayA list of required skills for the position.
minimum_educationStringThe minimum required education level.
minimum_work_experienceStringThe minimum required work experience.

Response

Returns a JSON object with a job_id string — the UUID of the submitted job. Poll the job status endpoint with this id to retrieve the result.

ParameterTypeDescription
job_idStringThe unique identifier of the submitted job. Format: UUID.

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.

▣ ENDPOINT 02 / 02
GET
Job Description Generator - Check Job Status
https://api.eu.apyhub.com/sharpapi/job-description-generator/job/status/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a job by its job_id.

curl -X GET "https://api.eu.apyhub.com/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)

AttributeTypeDescription
job_idStringJob 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.

ParameterTypeDescription
dataObjectWrapper object containing the job record.
data.idStringJob result identifier in UUID format.
data.typeStringResource type for the job result.
data.attributesObjectObject containing the job attributes: type, result, and status.
data.attributes.typeStringJob attribute type.
data.attributes.resultObjectGenerated job description content returned when the job reaches success.
data.attributes.result.job_requirementsStringThe generated list of job requirements, formatted as a bullet list.
data.attributes.result.job_responsibilitiesStringThe generated list of job responsibilities, formatted as a bullet list.
data.attributes.result.job_short_descriptionStringA short, narrative summary of the job description.
data.attributes.statusENUMJob 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.

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

CALLJob Description Generator APISumalya APIsCALLRelated Skills Generator APISharpAPICALLRelated Job Positions Generator APISharpAPICALLGenerate Keywords/Tags APISharpAPI

From the blog

Reads that touch this API.

7 AI Hiring APIs to Automate Recruitment, From Job Post to Offer (2026)Aug 5, 2026AI-Powered HR APIs Transforming Recruitment in 2026Jul 9, 2026Top 5 Free AI Resume Parsers for Recruiters in 2025Sep 10, 2026Top 5 Rank Tracking APIs to Build Your Own SEO Monitoring StackAug 24, 2026