Jobs

Publish a job

Changed on

Publishes a draft or expired job, making it visible on the public board. Plan and quota limits are enforced. expiresAt accepts an ISO 8601 string to set an explicit expiry, null to clear the explicit expiry, or may be omitted to preserve an existing expiry. An ordinary published job without an explicit expiry receives the board's defaultJobDurationDays from its publication time (30 days when unset). Sponsored jobs may have no expiry.

post/jobs/{id}/publish

Request

  • Base URL: https://api.cavuno.com/v1
  • URL: https://api.cavuno.com/v1/jobs/{id}/publish
  • Auth: HTTP bearer

Path parameters

idstring required

The job's opaque object id: the id field returned by the job endpoints (e.g. j8k2q7d4b9r3m6x0p5t1v7w2y9z4c8n3). This is NOT the slug or title; passing a slug like senior-backend-engineer returns 404. To look up a job by title or slug, use GET /v1/jobs or POST /v1/jobs/search and read the returned id.

Request body

expiresAtstring date-time nullable

New explicit expiry as an ISO 8601 datetime. Pass null to clear the explicit expiry, or omit the field to preserve an existing expiry. An ordinary published job without an explicit expiry receives the board's defaultJobDurationDays from its publication time (30 days when unset). Sponsored jobs may have no expiry.

Response

Successful response.

idstring required

Unique identifier for the object. Use this value as the {id} path parameter for the job endpoints (e.g. GET /v1/jobs/{id}).

object'job' required

String representing the object's type. Objects of the same type share the same value.

titlestring required

The job title.

slugstring nullable required

URL-friendly slug used in public board URLs, or null if no slug is set.

status'draft' | 'published' | 'expired' | 'archived' | 'pending_approval' required

Current status of the job. One of draft, published, expired, archived, or pending_approval. A pending_approval job is waiting for an operator to approve it: approve with POST /v1/jobs/:id/publish, reject with DELETE /v1/jobs/:id. It is not public, like a draft.

companyIdstring nullable required

Identifier of the company the job belongs to, or null if no company is attached.

employmentType'full_time' | 'part_time' | 'contract' | 'internship' | 'temporary' | 'volunteer' | 'other' nullable required

Employment type of the role, or null if not specified. For a job with a custom employment type, this is the Google equivalent of the custom type.

remoteOption'on_site' | 'hybrid' | 'remote' nullable required

Whether the role is on-site, hybrid, or fully remote. null only on older jobs saved without one; create requires it and PATCH cannot clear it.

seniority'entry_level' | 'associate' | 'mid_level' | 'senior' | 'lead' | 'principal' | 'director' | 'executive' nullable required

Seniority level of the role, or null if not specified.

salaryMinnumber nullable required

Minimum salary in salaryCurrency units, or null if not specified.

salaryMaxnumber nullable required

Maximum salary in salaryCurrency units, or null if not specified.

salaryCurrencystring nullable required

Three-letter ISO 4217 currency code for the salary range, or null if no salary is specified.

salaryTimeframe'per_year' | 'per_month' | 'per_week' | 'per_day' | 'per_hour' nullable required

Period the salary range is quoted against, or null if no salary is specified.

isFeaturedboolean required

Whether the job appears in featured slots on the public board.

publishedAtstring nullable required

Time at which the job was first published, or null if not yet published. ISO 8601 datetime.

expiresAtstring nullable required

Time at which the job expires as an ISO 8601 datetime. null can appear when the expiry requirement does not apply, including for drafts and sponsored jobs; ordinary published jobs always have an expiry.

createdAtstring required

Time at which the job was created. ISO 8601 datetime.

updatedAtstring required

Time at which the job was last updated. ISO 8601 datetime.

revisioninteger required

Monotonic Job lifecycle revision used to reconcile webhook events. Legacy rows are 0 until the rollout backfill runs.

skillsstring[] required

Canonical skill slugs assigned to the job.

categoriesstring[] required

Canonical category slugs assigned to the job.

externalIdstring nullable required

External identifier supplied by the caller on create, used for deduplication via GET /v1/jobs?externalId=.... null when no external identifier was set.

customFieldValuesobject required

Board-defined custom-field values for this job, keyed by the field key (the definitions are published at GET /v1/settings/job-form). Each value is returned as stored: a string (short_text / long_text / a single_select option key), a string array (multi_select option keys), a boolean, or a number. Always an object: {} when the job has no custom-field values, never null or a missing field. Only real values are stored, so this never contains null or empty values.

collectionValuesobject required

Operator-facing collection record IDs keyed by job collection field. Always an object; values are arrays even for single-select fields.

descriptionstring nullable required

Long-form description of the role (HTML), or null if not specified.

applicationUrlstring nullable required

Where candidates apply, or null if not specified. An HTTPS URL or mailto: URI.

remoteWorldwideboolean nullable required

Read-only: derived from remotePermits. true only when the authored selection is a single {type:"worldwide"} entry.

remoteAllowedTzOffsetsnumber[] required

Read-only: derived from remoteTimezones (per-country/per-region offset fan-out). UTC hour offsets used by the job-search index.

remoteWorkPermitCountryCodesstring[] required

Read-only: derived from remotePermits (hierarchical groups fan out to alpha2 sets; subdivisions auto-add the parent country). ISO 3166-1 alpha-2 codes.

remoteWorkPermitSubdivisionCodesstring[] required

Read-only: derived from remotePermits (subdivision entries only). ISO 3166-2 codes.

remoteSponsorship'yes' | 'no' | 'unknown' required

Whether the employer sponsors visas for remote candidates. One of yes, no, or unknown.

educationRequirementsstring[] required

Required education credentials. Each value is one of high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree, or no_requirements.

experienceMonthsnumber nullable required

Minimum required experience in months, or null if not specified.

experienceInPlaceOfEducationboolean nullable required

If true, equivalent experience may substitute for the listed education requirements. null if not specified.

inOfficePeriod'per_week' | 'per_month' | 'per_year' nullable required

Period denominator for inOfficeFrequency, or null if not specified.

inOfficeFrequencynumber nullable required

How often the candidate must be in-office over inOfficePeriod, or null if not specified.

Changes

  • c34152c38176Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status