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

Task	Permission
Read lookup data	`organization.read`
Create a job	`jobs.write`
Change an existing job's lifecycle status	`jobs.status.write`
Read the job back	`jobs.read`

1. Look up valid values

Value you need	Endpoint
Job types, education levels, salary intervals, lifecycle states	`GET /job-options`
Industry	`GET /industries`
Job function for an industry	`GET /job-functions?industry_id=12`
Employer type for an industry	`GET /employer-types?industry_id=12`
Client company (required for staffing accounts)	`GET /customers`
Optional department and hiring manager	`GET /departments`, `GET /hiring-managers`

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.

Creation returns 201 with the job ID and the result of the account workflow:

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,
and approvalStatus: 0.

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.

New jobs use the account's default workflow and are not published to the career
page or job boards. When approval is enabled, complete the normal approval flow
in CVViZ. Use PATCH /jobs/{jobId}/status with jobs.status.write only for a
later lifecycle change. Activating a job enforces the active-job limit and
revalidates its required details.

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.

Choose publication channels

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

Field	Creation when omitted	Update when omitted
`publishToCareerPage`	Off	Existing career-page setting is preserved
`publishToFreeJobBoards`	Off	Free-job-board publication is turned off

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.

Read job status and approval

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.

Before you begin#

1. Look up valid values#

2. Create a job#

Choose publication channels#

Read job status and approval#

Before you begin

1. Look up valid values

2. Create a job

Choose publication channels

Read job status and approval