REST API for ontavio career platforms

Table of contents

1. General API Usage Information
2. Job offer
3. Company Data
   1. Contact Persons
   2. Locations
   3. Company Uploads
   4. Default Company Benefits
   5. Company Job Boards
4. Routes For General Information
   1. Categories
   2. HTML-Tags
   3. Occupational Fields
5. Object structure
   1. Offer Description
   2. Contact Person
   3. Location
   4. Uploads
   5. Temporary Work
   6. Occupational Field
   7. Wage
6. Response schema

1. General API Usage Information

Syntax of this documentation

Depending on your specific goals, the routes you can use in this API can be adjusted to your needs.
In the beginning of each section is an overview of the available routes. Append the route name to the base URL to match the desired route.
Squared Brackets indicate that everything between them is not required for a successful processing.
Curly Braces indicate that you have to send data in the request URL.

General API Information

If you don’t send an ID with the URL for PUT- and DELETE-requests in many cases you need to specify the object you are referring to in the request body via object-ID or in case of a job offer via reference ID.
For POST- and PUT-Requests for a single offer it doesn't matter if you wrap them in an array or not.

Authentication

You need your company ID and your specific company API key to receive a JSON Web Token (JWT). Send both values as form-data in the request body. The JWT is valid for 180 seconds. To receive test credentials for development, contact our support.

Authentication examples

Example request for receiving a JWT:

curl -X POST "https://api.karriere-suedwestfalen.de/v1/authenticate" \
  -F "companyId=12345" \
  -F "apiKey=YOUR_API_KEY"

Example response:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<payload>.<signature>

Example usage of the JWT in further requests:

curl -X GET "https://api.karriere-suedwestfalen.de/v1/import/joboffer" \
  -H "Authorization: Bearer YOUR_JWT"

2. Job offer

For POST- and PUT-requests you can send the following data as JSON in the request body.

Locations are identified by their id or name. So, if there is a location saved in the company, that matches the received name or id, the further data gets ignored. If you want to change that data you have to update the location as described in 3.2.

The same applies for the contact persons, which are identified by id or email. There you can update that data as described in 3.1.

2.1 Response schema

All job offer endpoints return an array of response objects. To keep the schema readable, the response fields are split into a generic schema and operation-specific schemas below.

All response date/time fields are returned as ISO 8601 strings (for example 2026-06-17T10:15:00+00:00), except for legacy fields, which contain a DateTime object.

During the transition period, legacy timestamp fields remain available where applicable.

2.1.1 Response Schema (All Operations)

2.1.2 GET response schema

2.1.3 Schema For POST/PUT/DELETE Responses

Example success response

[
    {
        "type": "success",
        "time": {
            "date": "2026-03-25 10:15:00.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
        "timeIso8601": "2026-03-25T10:15:00+00:00",
        "referenceId": "1292346-2022",
        "id": 12345,
        "mainUrl": "https://example.com/stellenangebot/worker-in-example-job",
        "additionalJobBoardUrls": [
            "https://jobs.example.com/stellenangebot/worker-in-example-job"
        ],
        "message": "The offer with title \"Worker in example job\" was saved successfully."
    }
]

Example GET response

[
  {
    "type": "success",
    "title": "Software Developer (m/w/d)",
    "referenceId": "1292346-2022",
            "time": {
            "date": "2026-03-25 10:15:00.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
    "timeIso8601": "2026-03-25T10:15:00+00:00",
    "id": 12345,
    "mainUrl": "https://example.com/stellenangebot/software-developer-m-w-d-12345",
    "additionalJobBoardUrls": [
      "https://jobs.example.com/stellenangebot/software-developer-m-w-d-12345"
    ],
    "createdAt": "2026-06-10T08:00:00+00:00",
    "lastRefresh": "2026-06-17T10:00:00+00:00",
    "slug": "software-developer-m-w-d-12345",
    "status": "active",
    "referenceNumber": "1292346-2022",
    "importReference": "1292346-2022",
    "startType": "date",
    "startFrom": "2026-07-01T00:00:00+00:00",
    "limitationType": "no",
    "limitationDate": null,
    "jobOfferTypes": [
      "job"
    ],
    "contract": [
      "full time"
    ],
    "applyUrl": "https://example.com/apply/1292346-2022",
    "totalCount": 2,
    "students": false,
    "leadership": false,
    "chiffre": false,
    "mainPortal": 1,
    "portals": [
      1,
      2
    ],
    "benefits": [
      "5d9debaf67a3b775bdc8c927",
      "5d9debae67a3b775bdc8c91e"
    ],
    "description": {
      "input": true,
      "fullText": null,
      "introHeadline": "Einstieg bei uns",
      "introText": "<p>Wir suchen Verstärkung.</p>",
      "jobProfileHeadline": "Aufgaben",
      "jobProfileText": "<ul><li>Entwicklung</li><li>Tests</li></ul>",
      "applicantProfileHeadline": "Profil",
      "applicantProfileText": "<p>Typescript, React, Graphql</p>",
      "offerHeadline": "Wir bieten",
      "offerText": "<p>Flexible Arbeitszeiten</p>",
      "contactHeadline": "Kontakt",
      "contactText": "<p>HR Team</p>"
    },
    "scheduled": {
      "from": "2026-06-20T00:00:00+00:00",
      "to": "2026-09-30T00:00:00+00:00"
    },
    "temporaryWork": {},
    "workAtHome": {
      "allowed": true,
      "days": 3
    },
    "occupationalField": {
      "id": "5fabc1234567890abcde0001",
      "name": "Engineering"
    },
    "wage": {
      "type": "annual",
      "min": 40000,
      "max": 52000,
      "minWeeklyHours": 35
    },
    "categories": [
      {
        "id": "5d9debaf67a3b775bdc8c927",
        "name": "IT / Software",
        "slug": "it-software"
      }
    ],
    "locations": [
      {
        "id": "621f6a03bdef404ecf3b20ca",
        "name": "HQ Siegen",
        "street": "Musterstraße 10",
        "zip": "57072",
        "city": "Siegen",
        "region": "Südwestfalen",
        "country": "Deutschland",
        "mainLocation": true,
        "countOffers": 1
      }
    ],
    "contactPersons": [
      {
        "id": "6220d1a6bdef404ecf3b2172",
        "salutation": "Herr",
        "firstName": "Max",
        "lastName": "Mustermann",
        "position": "HR Manager",
        "email": "max.mustermann@example.com",
        "emailAlias": "karriere@example.com",
        "phone": "+49 271 123456",
        "show": true,
        "main": true,
        "notify": true,
        "showEmail": true,
        "showPhone": true
      }
    ],
    "updatedAt": "2026-06-17T10:00:00+00:00",
    "refreshedAt": "2026-06-17T10:00:00+00:00"
  }
]

Example error response

[
    {
        "type": "error",
        "time": {
            "date": "2026-03-25 10:15:00.000000",
            "timezone_type": 1,
            "timezone": "+00:00"
        },
        "timeIso8601": "2026-03-25T10:15:00+00:00",
        "message": "The offer with the reference-Id \"1292346-2022\" could not be found in the database.",
        "referenceId": "1292346-2022",
        "title": "Worker in example job"
    }
]

Example POST or PUT Request

 [
    {
        "ref": "1292346-2022",
        "title": "Worker in example job",
        "description": {
            "introHeadline": "Introduction Headline",
            "introText": "This is an introduction text.",
            "jobProfileText": "Job Profile Text. <strong>You can use HTML here.</strong>",
            "applicantProfileText": "Applicant Profile Text",
            "offerText": "Offer Text",
            "contactText": "Contact Information"
        },
        "applyUrl": "https:www.examplewebsite.com/apply/for-this-job",
        "startType": "date",
        "startFrom": "2022-01-19",
        "limitationType": "date",
        "limitationDate": "2022-03-23",
        "from": "2021-03-28",
        "to": "2022-03-28",
        "contract": 1,
        "categories": [
            "5d9debaf67a3b775bdc8c927",
            "5d9debae67a3b775bdc8c91e"
        ],
        "setReference": true,
        "status": "active",
        "portals": [
            "ksw",
            2,
            4
        ],
        "jobOfferTypes": [
            "apprenticeship",
            "dual-study"
        ],
        "occupationalField": {
            "id": "5fabc1234567890abcde0001",
            "idMainCategory": "5fabc1234567890abcde0002",
            "name": "Engineering"
        },
        "wage": {
            "type": "annual",
            "min": 40000,
            "max": 48000,
            "minWeeklyHours": 35
        },
        "leadership": false,
        "students": true,
        "contactPersons": [
            {
                "email": "contact.person@example.com",
                "firstName": "Contact",
                "lastName": "Person",
                "position": "Leader of Example",
                "image": "https://examplewebsite.com/400x300/000/ff0.png",
                "salutation": "Herr",
                "phone": "0160123456789",
                "newsletter": false,
                "persistent": true
            },
            {
                "email": "existing.contact.person@example.com"
            }
        ],
        "locations": [
            {
                "name": "Main Location",
                "amount": 1
            },
            {
                "name": "New Location",
                "street": "Hundemstr. 2",
                "zip": "57368",
                "city": "Lennestadt",
                "logo": "https://linkToExampleImage.com/450x350/000/f0f.png",
                "amount": 1,
                "persistent": true
            }
        ],
        "uploads": {
            "images": [
                "https://linkToExampleImage.com/1200x600/000/ff0.png",
                "https://linkToExampleImage.com/1250x550/000/ff0.jpg"
            ]
        }
    },
    {
        …
    }
]

Example DELETE

For DELETE-requests either append the reference ID of the offer to the request URL or send an array of JSON-objects according to the following table in the request body.

Example DELETE-request to delete the first offer from KSW and KMH, and the second one from all job boards

[
    {
        "ref": "123456789",
        "portals": ["ksw", "kmh"]
    },
    {
        "ref": "123456-2022"
    },
    {
        …
     }
]

3. Company Data

3.1 Contact Persons

Examples

POST/PUT

[
   {
       "email": "erika@example.com",
       "firstName": "Erika",
       "lastName": "Mustermann",
       "salutation": "Frau",
       "position": "Personalleitung",
       "phone": "01234 / 123456",
       "emailAlias": "e.mustermann@example.com",
       "newsletter": false,
       "cpCompanyPortrait": true,
       "cpEmailCompanyPortrait": false,
       "cpPhoneCompanyPortrait": false,
       "cpEmailJoboffer": false,
       "cpPhoneJoboffer": false
   },
   ...
]

DELETE

[
    {
        "id": "621f6a03bdef404ecf3b20ca"
    },
    {
        "id": "6220d1a6bdef404ecf3b2172"
    },
    ...
]

Example contact person response

[
    {
        "time": "2026-03-25T10:15:00+00:00",
        "message": "New Contact person with email \"erika@example.com\" created.",
        "type": "success",
        "id": "621f6a03bdef404ecf3b20ca",
        "email": "erika@example.com"
    }
]

3.2 Locations

Examples

POST/PUT

[
   {
       "name": "Example Location",
       "city": "ExampleCity",
       "zip": 12345,
       "street" : "Example street 10",
       "region" : "Südwestfalen",
       "logo" : "https://example.com/logo/1234.jpg",
   }
   ...
]

DELETE

[
    {
        "id": "621f6a03bdef404ecfxxxxx"
    },
    {
        "id": "6220d1a6bdef404ecf3xxxxx"
    },
    ...
]

Example location response

[
    {
        "time": "2026-03-25T10:15:00+00:00",
        "message": "Location with id 621f6a03bdef404ecfxxxxx updated successfully",
        "type": "success",
        "id": "621f6a03bdef404ecfxxxxx",
        "name": "Example Location"
    }
]

3.3 Company Uploads

3.4 Default Company Benefits

If you don’t want all default company benefits for a specific job offer you can send an array with all benefit IDs you want to add.

3.5 Company Job Boards

4. Routes For General Information

4.1 Categories

Deprecation warning: Categories are deprecated and may be removed in a future version. Please use occupational fields instead.

Currently we support following categories:, which you can reference via ID:

4.2 HTML-Tags

The allowed tags in the description are "<h3>", "<ul>", "<ol>", "<li>", "<a>", "<b>", "<strong>", "<br>", "<p>" and "<small>".

4.3 Occupational Fields

Example response:

[
  {
    "id": "5fabc1234567890abcde0001",
    "idMainCategory": "5fabc1234567890abcde0002",
    "name": "Engineering"
  },
  {
    "id": "5fabc1234567890abcde0003",
    "idMainCategory": "5fabc1234567890abcde0004",
    "name": "Logistics"
  }
]

5. Object structure

5.1 Offer Description

You can use the HTML-tags described in 4.2 for the text parts.

If you don’t have data for every required text part, you have to send an empty string as corresponding value.

5.2 Contact Person

5.3 Location

5.4 Uploads

If no Uploads are provided for a job offer, the second image of the company portrait gets added.

Allowed image formats are: .jpg, .png and .gif.

The preferred image ratio for job offer images is 2:1 and the default shown size is 1200x600px.

If the ratio is smaller than 1.7 or bigger than 2.3 the image will get cropped. Maximum amount of images is 5.

Contact person images should have a ratio of 1:1 or will get cropped otherwise.

5.5 Temporary Work

5.6 Occupational Field

Categories are deprecated. If category data is sent, it is mapped to an occupational field. If both categories and occupationalField are provided, occupationalField is used as the displayed value in job offers.

The idMainCategory field is not accepted as input. It is derived from the database and returned in GET responses.

5.7 Wage

6. Response schema

All import endpoints return an array of response objects. Each object contains generic response metadata and may contain additional entity-specific fields depending on the endpoint and operation.

6.1 Generic response fields

6.2 Job offer specific fields

See 2.1.2

6.3 Contact person specific fields

6.4 Location specific fields