API concepts

Understand jobs, candidates, applications, approval, publication, response formats, dates, and units.

Use these concepts to interpret the customer API and choose the right resource, scope, and workflow.

Base URL and response format

Use https://api.cvviz.com/v1. Endpoint paths such as /jobs are relative to this base. Use HTTPS and Bearer authentication.

Resource responses use JSON. A successful item has data; collections also have meta.pagination. The resume download endpoint instead returns a 302 redirect. Errors use Problem Details.

Understand the resources

Concept	Meaning
Job	A role you are recruiting for
Candidate	A person in your candidate database
Application	A candidate's association with one job and its hiring stage
Client company	A customer of a staffing account; not an employer-type classification
Credential scope	Operations this integration may perform
Account API access	Availability granted by a plan or active API add-on

Job status, approval and publication

These are three separate concepts. An active job is not necessarily advertised, and job lifecycle status does not grant approval. API creation defaults both publication channels off. publishToCareerPage and publishToFreeJobBoards can explicitly enable them for active, approved jobs. On job updates, an omitted career-page flag preserves its setting, but an omitted free-job-board flag defaults to false and disables free distribution.

Normal creation follows the account workflow: active when approval is disabled, or pending approval when it is enabled. Creation does not accept lifecycle codes. Use GET /job-options for the codes, labels, and canSet values supported by status updates. Support flags do not guarantee a particular transition will pass approval and capacity checks.

Job reads expose statusLabel, approvalStatus and approvalStatusLabel. Approval codes are 0 Pending Approval, 1 Approved, -1 Rejected, or null / Unknown when unavailable.

Data conventions

Job experience is in years; candidate experienceMonths is in months. Creation uses skills for Required skills and optionalSkills for skills marked Nice to have in the job form. Dates use RFC 3339 with a timezone. Treat IDs as identifiers, not sequence guarantees.

Send only documented request fields; unsupported fields return 400.

Integration guides

Compatibility

Clients should ignore unknown response fields. Backward-compatible additions can occur within v1. Breaking changes require a new major-version base URL.

Was this helpful?

Still need help? Ask the team