Publish a Job Ad

Complete the four steps below in order. Every call uses the Authorization and Company-Id headers from Authentication.

Step 1: Get or create the job

Load the job you want to promote with List Jobs, or create a new one with Create Job. Publishing needs the Kini id of a job.

Step 2: Choose a product

List Products returns the product catalogue curated for this company, along with their custom prices. Two ids from each product are needed when publishing a booking - id (the product ID), and provider_product (the company-specific pricing ID).

list_price is the catalogue price in EUR. price is the actual billable amount that will be invoiced, and it already includes any applicable partner discount. list_days is the number of days the booking is visible on the job board.

If required_fields specifies job fields or custom fields, include those values when you publish so the job board can process the booking. Custom fields go in custom_fields.

Talent channels

List Talent Channels returns the same products, but grouped under their respective job boards. This is particularly useful when building a clean, frontend interface that shows one 'product' card per talent channel. Creating a booking only needs id and provider_product from List Products, not Talent Channels.

Step 3: Add billing details

List Billing Details returns the company's active billing details. Choose an existing billing detail, or if the list is empty, create a new one with Create Billing Detail. Store the returned id, and send it as company_billing_detail when creating a booking. The purchased products are invoiced to this record.

Step 4: Publish the job

Create Job Booking creates the booking. job_bookings is an array, and each object is one booking, so one request can create multiple bookings, placing the same job on several products. Every object needs job, product, and provider_product.

You can also optionally send job fields on that object, such as title, city, or description, when the booking content should differ from the job. For example, to use a different title for Indeed, send that title on the booking object with the Indeed product. If you leave a field out, its value is automatically copied from the job.

The price is set from the provider_product. Each new booking starts with status booked. The full list of status values can be found under Job Booking Status Update.

For accountability, the created transaction also records the API User or Key as the responsible entity who published the job ad.

{
  "company_billing_detail": 12,
  "job_bookings": [
    {
      "job": 123456,
      "product": 2526,
      "provider_product": 2861,
      "title": "Software Engineer (m/w/d)",
      "city": "Berlin"
    }
  ]
}

The response id is the transaction id. total_price is the price sum of all the products purchased, in EUR. job_bookings lists the individual ads that were created.

Follow status updates on each ad with the Job Booking Status Update webhook, or read bookings back with List Job Bookings. These are helpful in tracking the publishing progress and lifecycle of a booking. To set up a new webhook or receive these notifications, contact tech@getkini.com.

Once the booking is created, it goes through an automated review and is posted on the job board within a few hours in most cases, and within two days if a review takes longer. The price of purchased products is then invoiced separately at the end of the month.