Create a job

Create a job through your account's standard CVViZ workflow.

Active is not automatically published. Both publication channels default to off on creation. You can explicitly request career-page or eligible free-job-board publication for an active, approved job.

Before you begin

1. Look up valid values

Replace example IDs with your lookup results. Employer types are classifications, not client companies. Lookups are paginated where documented.

2. Create a job

Grant jobs.write to your credential. For supporting lookups, also grant organization.read. There is no separate jobs.create permission.

Complete job requests require the fields shown below. Replace the sample classification IDs with values from your lookups; staffing accounts must also include a valid customerId from /customers. Job code is generated when omitted. The description needs at least 100 words, and full location is required even for remote jobs. skills means Required; optionalSkills means Good to have.

curl --request POST \
 --url 'https://api.cvviz.com/v1/jobs' \
 --header 'Authorization: Bearer YOUR_API_SECRET' \
 --header 'Content-Type: application/json' \
 --header 'Idempotency-Key: create-engineer-001' \
 --data '{
 "title": "Backend Engineer",
 "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.",
 "jobType": "Full Time",
 "industryId": 12,
 "jobFunctionId": 14,
 "employerTypeId": 16,
 "country": "India",
 "state": "Maharashtra",
 "city": "Pune",
 "zipCode": "411001",
 "educationLevel": "Bachelor",
 "qualifications": [
 "B.Tech"
 ],
 "minimumExperience": 2,
 "maximumExperience": 5,
 "skills": [
 "TypeScript"
 ],
 "optionalSkills": [
 "PostgreSQL"
 ]
}'

Creation returns 201 with a data object containing id, status, isDraft and isDeleted:

• When job approval is disabled, the job is active with status: 5.

• When job approval is enabled, the job is pending approval with status: 3.

For example, an active job can return:

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

Approval fields are returned by GET /jobs/{jobId}, which requires jobs.read. A newly pending-approval job has approvalStatus: 0 on that read.

Retry with the same idempotency key and body to retrieve the original result without creating another job.

Use /job-options, /industries, /job-functions?industry_id=…, /employer-types?industry_id=…, /customers, /departments, /hiring-managers and /users for valid values and account-owned IDs. All collection endpoints default to 10 items. Qualifications and locations are text fields; experience is in years, and salary intervals are H, D, W, M, or Y.

Without publication flags, new jobs use the account's default workflow and remain unpublished on the career page and job boards. When approval is enabled, complete the normal approval flow in CVViZ. Use PATCH /jobs/{jobId}/status with jobs.status.write for a later lifecycle change. Activating a job enforces the active-job limit and revalidates its required details. Complete any missing required details in CVViZ before retrying activation.

If active-job capacity is unavailable for an account that creates jobs directly as active, the API returns 409 and creates no job. Pending-approval jobs do not consume an active-job slot until activation.

Save a draft instead

Add "saveAsDraft": true to the complete creation body to create a draft with status: 1 and isDraft: true. A draft request still requires all documented creation fields, including the 100-word description, location, qualifications and required skills. Publication flags must be omitted or false.

Do not send status, approvalStatus or approvalStatusLabel in a creation request. CVViZ chooses the initial lifecycle and approval state.

3. Choose publication channels

Use these optional boolean fields on POST /jobs or PATCH /jobs/{jobId}:

To create and publish in one request, add the desired flags to the normal creation body. This succeeds only when the account workflow creates an active, approved job. If approval is required, the API returns 409; create the job without publication, complete approval, then update publication afterward. Alternatively, update publication after the job is active and approved:

{
 "publishToCareerPage": true,
 "publishToFreeJobBoards": true
}

Send this body to PATCH /jobs/{jobId} with jobs.write and a new Idempotency-Key. Enabling either channel on an inactive or unapproved job returns 409; publication never bypasses approval or active-job capacity checks.

Include publishToFreeJobBoards: true on each job update that should keep free distribution enabled. Omitting it, even when only changing a title, disables that channel. Explicit false disables the corresponding channel. Status-only requests to /jobs/{jobId}/status do not change publication settings.

CVViZ manages eligible free boards without exposing individual board selections. Existing account, integration, moderation and provider requirements still apply; some channels also need career-page publication enabled. No paid advertising is purchased. Provider listing and removal can be delayed and are not guaranteed. Publication changes and the job mutation share the same transaction and replay receipt; reuse a key only with the same request.

4. Read lifecycle and approval status

GET /jobs/{jobId} and job lists include status, statusLabel, approvalStatus and approvalStatusLabel. These are separate states: approval 0 means pending, 1 approved and -1 rejected; unavailable values are returned as null / Unknown. Lifecycle status 5 is labelled In Progress and means active, not publicly advertised.

GET /job-options returns initialStatus: "account_workflow" and a statuses list with code, label, and canSet. canSet describes status-endpoint support, not whether approval or capacity permits a particular transition. Supported status updates remain 1, 2, 4, and 5; 2 means New and 4 means Rejected, not Closed and On Hold. Setting a lifecycle code does not approve or reject an approval request. Activating a job clears isDraft; other supported lifecycle changes preserve its existing value.