Create Job

curl --request POST \
  --url https://api.kardow.com/jobs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "title": "Backend Engineer",
  "description": "Build internal and public APIs.",
  "company_name": "Acme"
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "slug": "<string>",
    "url": "<string>",
    "status": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "company_logo_url": "<string>"
  },
  "meta": {
    "organization_id": 123,
    "board_url": "<string>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

POST

jobs

curl --request POST \
  --url https://api.kardow.com/jobs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "title": "Backend Engineer",
  "description": "Build internal and public APIs.",
  "company_name": "Acme"
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "title": "<string>",
    "slug": "<string>",
    "url": "<string>",
    "status": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "company_logo_url": "<string>"
  },
  "meta": {
    "organization_id": 123,
    "board_url": "<string>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "details": "<unknown>",
    "url": "<string>"
  }
}

Use this endpoint when an external system needs to publish jobs directly into Kardow.

Required Fields

string

required

Job title.

string

required

Full job description. HTML is accepted.

string

required

Hiring company name.

Application method

how_to_apply and how_to_apply_method only mean something together. If the method is email, website, phone or form-external, you must send a how_to_apply value, otherwise the apply button has nowhere to send candidates. The request is rejected with 422 invalid_apply_destination rather than saved with a dead button. Only form takes no destination.

string

Where candidates apply: an external URL, an email address, or a phone number. Required unless how_to_apply_method is form.This is not the job’s own page on your board. That URL is generated automatically and returned in the response.

string

Controls how Kardow presents the apply button. One of:

Value	When to use
`form-external`	`how_to_apply` is a link to an external application form or ATS (most common)
`website`	`how_to_apply` is a general company or job page
`email`	`how_to_apply` is an email address
`phone`	`how_to_apply` is a phone number
`form`	Kardow hosts the application form — no `how_to_apply` needed

If omitted, Kardow detects the method from the how_to_apply value, which is usually the safest choice.A method that contradicts its value is also rejected: email pointing at a URL would render a broken mailto: link. Where the intent is unambiguous, Kardow recovers instead of failing: email with no destination falls back to contact_email, website falls back to company_website, and a bare domain is upgraded to https://.The response echoes the resolved destination in meta.apply so you can confirm what was stored.

Common optional fields

string

Category name, e.g. Engineering. Matched to an existing category (case-insensitive) or created if new. See Categories.

string

Existing category UUID. Takes precedence over category if both are sent.

string

One of full-time, part-time, contract, internship, temporary, or casual.

string

The location shown on the job: Remote, Paris, San Francisco, CA, or a full street address.Kardow resolves this to a real place and links the job to it, so the job appears on the right location page and in location filters. Street addresses are filed under their city, and the exact coordinates are kept on the job for map pins.

string

An existing location id from Locations. Takes precedence over location text and skips resolution entirely.Resolve first and pass the id whenever you can: it removes any guesswork about which place the job lands on.

string

Two-letter country code used when resolving location text, e.g. ca. Ignored when location_id is given.

boolean

Set to true for remote roles.

number

Minimum salary amount.

number

Maximum salary amount.

string

Currency code such as USD.

string

One of hourly, daily, weekly, monthly, or yearly.

string

Recruiter or HR contact email (not the apply destination — use how_to_apply for that).

string

default:"pending"

One of pending, active, expired, or draft.

Examples

Link to an external application form

The most common case: your ATS or careers page hosts the form.

cURL

curl --request POST \
  --url https://api.kardow.com/jobs \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key-here" \
  --data '{
    "title": "Backend Engineer",
    "description": "Build internal and public APIs.",
    "company_name": "Acme",
    "how_to_apply": "https://jobs.acme.com/backend-engineer",
    "how_to_apply_method": "form-external"
  }'

Apply via email

cURL

curl --request POST \
  --url https://api.kardow.com/jobs \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key-here" \
  --data '{
    "title": "Office Manager",
    "description": "Run day-to-day office operations.",
    "company_name": "Acme",
    "how_to_apply": "jobs@acme.com",
    "how_to_apply_method": "email"
  }'

Remote role with salary details

cURL

curl --request POST \
  --url https://api.kardow.com/jobs \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key-here" \
  --data '{
    "title": "Senior Product Designer",
    "description": "Lead product design across web and mobile.",
    "company_name": "Acme",
    "location": "Remote",
    "is_remote": true,
    "job_type": "full-time",
    "how_to_apply": "https://jobs.acme.com/designer",
    "how_to_apply_method": "form-external",
    "salary_min": 90000,
    "salary_max": 120000,
    "salary_currency": "USD",
    "salary_period": "yearly",
    "contact_email": "jobs@acme.com"
  }'

JavaScript example

const response = await fetch("https://api.kardow.com/jobs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.KARDOW_API_KEY,
  },
  body: JSON.stringify({
    title: "Senior Software Engineer",
    description: "Build product features across the stack.",
    company_name: "Acme",
    location: "Remote",
    is_remote: true,
    job_type: "full-time",
    how_to_apply: "https://jobs.acme.com/senior-swe",
    how_to_apply_method: "form-external",
    contact_email: "jobs@acme.com",
  }),
});

const result = await response.json();
console.log(result.data.id);

Response Shape

string

required

Newly created job UUID.

string

required

Job URL path (without the domain).

string

required

The full, shareable public URL to the created job on your live board (uses your active custom domain when you have one).

string

required

Current job status.

number

required

Organization that owns the job.

string

required

The base public URL of your job board.

string

required

The full public URL for the created job (same as data.url).

string | null

The location the job was filed under, or null if it could not be resolved.

string

Human-readable summary of the apply destination that was actually stored, e.g. email: jobs@acme.com. Check it: if it says Kardow-hosted application form when you meant an external one, the destination did not arrive.

string

Human-readable summary of where the job was filed, e.g. Gatineau, QC (geocoded), or none.

string[]

Present only when something needs attention, such as a location that could not be resolved.

Example response

{
  "data": {
    "id": "4d1b6fe8-688f-467c-b233-b5d6a51ce1cb",
    "title": "Backend Engineer",
    "slug": "/companies/acme/jobs/backend-engineer-4d1b6fe8688f467cb233b5d6a51ce1cb",
    "url": "https://jobs.acme.com/companies/acme/jobs/backend-engineer-4d1b6fe8688f467cb233b5d6a51ce1cb",
    "status": "pending",
    "created_at": "2026-03-10T12:00:00.000Z",
    "company_logo_url": null,
    "how_to_apply": "https://jobs.acme.com/backend-engineer",
    "how_to_apply_method": "form-external",
    "location": "Gatineau, QC",
    "location_id": "7f8a1c2d-0b34-4c8e-9a71-2f5d6e8b0a13",
    "location_display": "Gatineau, QC"
  },
  "meta": {
    "organization_id": 42,
    "board_url": "https://jobs.acme.com",
    "url": "https://jobs.acme.com/companies/acme/jobs/backend-engineer-4d1b6fe8688f467cb233b5d6a51ce1cb",
    "apply": "form-external: https://jobs.acme.com/backend-engineer",
    "location": "Gatineau, QC (geocoded)"
  }
}

Authorizations

x-api-key

string

header

required

API key for authentication. Get yours from Settings > API Keys in the Kardow dashboard.

Body

application/json

title

string

required

description

string

required

company_name

string

required

apply_url

string

Preferred field for the application destination — an external URL, email address, or phone number. Alias of how_to_apply (which is still accepted).

apply_type

enum<string>

Preferred field for how candidates apply. Alias of how_to_apply_method.

Available options:

form-external,

website,

email,

phone,

form

how_to_apply

string

Required unless how_to_apply_method is "form". Where candidates apply: an external URL, an email address, or a phone number. A method of email/website/phone/form-external with no destination is rejected with 422 invalid_apply_destination.

how_to_apply_method

enum<string>

What the apply button does: form-external, website, email, phone, or form. Must match the how_to_apply value. Only "form" takes no destination. Omit to auto-detect from how_to_apply.

Available options:

form-external,

website,

email,

phone,

form

posted_by_email

string<email>

Email of the employer account posting this job. Must match a job board user in the org, else the request returns 422 employer_not_found.

Response

Job created

data

object

Show child attributes

Getting Started

Analytics

Jobs

Applications

Content

Members

Users

Webhooks

Secrets

CMS

Required Fields

Application method

Common optional fields

Examples

Link to an external application form

Apply via email

Remote role with salary details

JavaScript example

Response Shape

Example response

Authorizations

Body

Response

​Required Fields

​Application method

​Common optional fields

​Examples

​Link to an external application form

​Apply via email

​Remote role with salary details

​JavaScript example

​Response Shape

​Example response

Authorizations

Body

Response

Required Fields

Application method

Common optional fields

Examples

Link to an external application form

Apply via email

Remote role with salary details

JavaScript example

Response Shape

Example response