Jobs

Create a job

Create a job through your account's standard workflow.

POST

/jobs

Create a job

curl --request POST \
  --url https://api.cvviz.com/v1/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: cvviz-integration-operation-001' \
  --header 'Content-Type: application/json' \
  --data '
{
  "city": "Pune",
  "country": "India",
  "description": "We are looking for a Backend Engineer to build and maintain reliable services for our recruitment platform. You will design APIs, implement business workflows, improve database queries, and write automated tests. You will collaborate with product managers, designers, and other engineers to deliver clear and dependable customer experiences. The role includes reviewing code, investigating production issues, documenting technical decisions, and improving application security and performance. Candidates should be comfortable with TypeScript, relational databases, version control, and practical debugging. We value thoughtful communication, ownership, and a willingness to learn. You will receive regular feedback and work with the team to plan improvements, share knowledge, and maintain high engineering standards.",
  "educationLevel": "Bachelor",
  "employerTypeId": 16,
  "industryId": 12,
  "jobFunctionId": 14,
  "jobType": "Full Time",
  "maximumExperience": 5,
  "minimumExperience": 2,
  "qualifications": [
    "B.Tech"
  ],
  "saveAsDraft": true,
  "skills": [
    "TypeScript"
  ],
  "state": "Maharashtra",
  "title": "Backend Engineer",
  "zipCode": "411001"
}
'

{
  "data": {
    "id": 901,
    "isDeleted": false,
    "isDraft": false,
    "status": 5
  }
}

For a complete walkthrough, see Create a job.

Permissions

Action	Required scopes
Create a job	`jobs.write`
Change its lifecycle later	`jobs.status.write`
Read job-creation lookups	`organization.read`

Before you begin

Use lookup endpoints to obtain valid classification IDs; do not copy example IDs unchanged.
Complete every field marked required below.
Provide a description of at least 100 words and a full location, including for remote jobs.
Staffing accounts must include customerId from the client-company lookup.
Omit code or leave it blank to generate a job code automatically.

What happens after creation?

By default, the job becomes active when job approval is disabled for the account.
When job approval is enabled, the job is created pending approval and follows the normal CVViZ approval workflow.
Use PATCH /jobs/{jobId}/status for later lifecycle changes.

If active-job capacity is unavailable, normal creation returns 409 and creates no job. Pending-approval jobs do not consume active-job capacity.

Publication (optional)

publishToCareerPage: request publication on your career page.
publishToFreeJobBoards: request distribution to eligible free job boards managed by CVViZ. Individual boards are not exposed.
Both default to false. Enabling either during creation is allowed only when the account workflow creates an active, approved job.
Jobs pending approval must be created without publication. Enable publication later with PATCH /jobs/{jobId} after activation and approval.
Account, integration, moderation and provider eligibility still apply. Some distribution channels require career-page publication. No paid advertising is purchased; listing and removal may be delayed by providers.
To change publication later, use PATCH /jobs/{jobId}. Enabling requires an active, approved job. Publication does not activate or approve a job.

Retries and errors

Send an Idempotency-Key with every creation request. Retry the same request with the same key to avoid duplicates. Use a new key for a new operation.

400: fix missing or invalid fields.
403: check scopes and API access.
409: check approval, active-job capacity, or conflicting reuse of the idempotency key.

Authorizations

Authorizationstringheaderrequired

Use Authorization: Bearer <api-credential>.

Headers

Idempotency-Keystringheaderrequired

Unique key for this write: 8-128 letters, digits, periods, underscores, colons or hyphens. Reusing the same key with the same request replays its original result; different content returns 409.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]{8,128}$

Example: cvviz-integration-operation-001

Body

assignedRecruiterIdsinteger[]

Active account user IDs from GET /v1/users. No automatic assignment to a human user.

Maximum array length: 50

citystringrequired

Required string length: 1 - 255

Example: Pune

codestring

Job code. Automatically generated if omitted or blank.

Maximum string length: 255

Example: ENG-104

countrystringrequired

Required string length: 1 - 255

Example: India

customerIdinteger

Required for staffing accounts. An account-owned client company from GET /v1/customers.

Required range: 1 <= x

departmentIdinteger

Required range: 1 <= x

Example: 12

descriptionstringrequired

At least 100 words of visible job description. HTML is supported; markup does not count as words. Maximum 65,535 UTF-8 bytes.

Required string length: 1 - 65535

Example:

We are looking for a Backend Engineer to build and maintain reliable services for our recruitment platform. You will design APIs, implement business workflows, improve database queries, and write automated tests. You will collaborate with product managers, designers, and other engineers to deliver clear and dependable customer experiences. The role includes reviewing code, investigating production issues, documenting technical decisions, and improving application security and performance. Candidates should be comfortable with TypeScript, relational databases, version control, and practical debugging. We value thoughtful communication, ownership, and a willingness to learn. You will receive regular feedback and work with the team to plan improvements, share knowledge, and maintain high engineering standards.

educationLevelenum<string>required

Available options: Bachelor, Doctorate / PhD, High school, Master, Middle school

Example: Bachelor

employerstring

Employer display name. Defaults to the selected client company name when omitted.

Maximum string length: 255

employerTypeIdintegerrequired

Must belong to industryId; use GET /v1/employer-types.

Required range: 1 <= x

Example: 16

hiringManagerIdinteger

Required range: 1 <= x

Example: 22

industryIdintegerrequired

Use GET /v1/industries.

Required range: 1 <= x

Example: 12

isRemoteboolean

Example: true

jobFunctionIdintegerrequired

Must belong to industryId; use GET /v1/job-functions.

Required range: 1 <= x

Example: 14

jobTypeenum<string>required

Available options: Full Time, Part Time, Contract-to-Hire, Contract, Contract Corp-to-Corp, Internship, Commission Based, Freelancer, Voluntary, Third Party

Example: Full Time

maximumExperienceintegerrequired

Maximum experience in years. Zero is valid.

Required range: 0 <= x <= 100

Example: 5

maximumSalaryinteger

Required range: 0 <= x <= 2147483647

Example: 160000

minimumExperienceintegerrequired

Minimum experience in years. Zero is valid.

Required range: 0 <= x <= 100

Example: 2

minimumSalaryinteger

Required range: 0 <= x <= 2147483647

Example: 100000

optionalSkillsstring[]

Good-to-have skills. Do not replace the mandatory skills list.

Maximum array length: 50

publishToCareerPageboolean

Request career-page publication. Defaults to false on creation; omitted on update leaves this channel unchanged. Enabling requires an active, approved job.

publishToFreeJobBoardsbooleandefault:false

Request distribution to eligible free job boards managed by CVViZ. Defaults to false on both creation and update: omission on update disables free-job-board publication. Enabling requires an active, approved job. Account, integration, moderation and provider eligibility still apply; no paid advertising or guaranteed listing.

qualificationsstring[]required

One or more qualifications. After trimming and joining with commas, the combined value must not exceed 255 characters.

Required array length: 1 - 20

salaryCurrencystring

Required string length: 3 - 3

Pattern: ^[A-Z]{3}$

Example: USD

salaryIntervalenum<string>

H/hour, D/day, W/week, M/month, Y/year.

Available options: H, D, W, M, Y

saveAsDraftbooleandefault:false

Set true to save a draft. Draft creation still requires all mandatory job fields and a description of at least 100 words.

skillsstring[]required

Required skills. At least one is mandatory. Stored as Required skills in the ATS.

Required array length: 1 - 50

statestringrequired

Required string length: 1 - 255

Example: Maharashtra

tagsstring[]

Maximum array length: 50

titlestringrequired

Required string length: 1 - 100

Example: Backend Engineer

zipCodestringrequired

ZIP/postal code; required even for remote jobs.

Required string length: 1 - 50

Example: 411001

Response

Mutation applied or safely replayed.

X-API-Daily-Limitintegerheader

Daily account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Daily-Remainingintegerheader

Requests remaining in the daily window after admission.

Required range: 0 <= x

X-API-Daily-Resetstringheader

Daily window reset time in UTC.

X-API-Monthly-Limitintegerheader

Monthly account request allowance, when metered. Shared across API credentials.

Required range: 0 <= x

X-API-Monthly-Remainingintegerheader

Requests remaining in the monthly window after admission.

Required range: 0 <= x

X-API-Monthly-Resetstringheader

Monthly window reset time in UTC.

X-Request-IDstringheader

Request correlation identifier.

X-API-Contractstringheader

Response envelope contract version.

Example: canonical-v1

RateLimit-Limitintegerheader

Example: 600

RateLimit-Remainingintegerheader

Example: 598

RateLimit-Resetintegerheader

Example: 30

dataobjectrequired

Show child attributes

Still need help? Ask the team