REST-Schnittstelle für Karriereportale von ontavio

Inhaltsverzeichnis

1. Allgemeine Information zur Nutzung der Schnittstelle
2. Stellenangebote
3. Unternehmensdaten
   1. Ansprechpartner
   2. Standorte
   3. Unternehmens-Uploads
   4. Standardmäßige Vorteile/Benefits des Unternehmens
   5. Jobbörsen des Unternehmens
4. Routen für allgemeine Informationen
   1. Kategorien
   2. HTML-Tags
   3. Berufsfelder
5. Objektstruktur
   1. Stellenbeschreibung
   2. Ansprechpartner
   3. Standort
   4. Uploads
   5. Zeitarbeit
   6. Berufsfeld
   7. Gehalt
6. Antwortschema

1. Allgemeine Information zur Nutzung der Schnittstelle

Syntax dieser Dokumentation

Die Routen in dieser REST-Schnittstelle müssen je nach Ziel der Anfrage angepasst werden.
Am Beginn jedes Themenabschnitts befindet sich eine Übersicht über die möglichen Routen. Fügen Sie diese zur jeweiligen Basis-URL hinzu, um die gewünschte Route zu erreichen.
Eckige Klammern bedeuten, dass alles zwischen ihnen optional ist, um einen fehlerfreien Ablauf der Anfrage sicherzustellen.
Geschweifte Klammern zeigen an, dass zwischen Ihnen Daten eingefügt werden müssen.

Allgemeine Information zur Schnittstelle

Wenn keine ID (bzw. Referenz-ID für Stellenangebote) in der URL für PUT- oder DELETE-Requests mitgeliefert wird, muss diese im Request-Body hinzugefügt werden, um das entsprechende Objekt zu bestimmen.
Bei POST- oder PUT-Requests für einzelne Stellenangebote ist es irrelevant, ob diese in einem Array oder als einzelnes Objekt gesendet werden.

Authentifizierung

Sie benötigen Ihre Unternehmens-ID und Ihren unternehmensspezifischen API-Schlüssel, um ein JSON Web Token (JWT) zu erhalten. Senden Sie beide Werte als Form-Data im Request-Body. Das JWT ist 180 Sekunden gültig. To receive test credentials for development, contact our support.

Authentifizierungsbeispiele

Beispielanfrage zum Erhalten eines JWT:

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

Beispielantwort:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.<payload>.<signature>

Beispielhafte Verwendung des JWT in weiteren Anfragen:

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

2. Stellenangebote

In POST- und PUT-Requests können folgende Daten als JSON im Request-body gesendet werden.

Standorte werden anhand ihrer ID oder ihres Namens identifiziert. Daraus folgt, dass wenn ein Standort gesendet wird, der in einem dieser Punkte übereinstimmt, die weiteren Standortdaten ignoriert werden. Wenn diese Daten geändert werden sollen, muss der Standort aktualisiert werden. Siehe dazu Abschnitt 3.2.

Dasselbe gilt für die Ansprechpartner, die anhand ihrer ID oder der E-Mail identifiziert werden. Hier können die Daten aktualisiert werden wie beschrieben in Abschnitt 3.1.

2.1 Antwortschema

Alle Stellenangebot-Endpunkte geben ein Array von Antwortobjekten zurück. Um das Schema übersichtlich zu halten, sind die Antwortfelder unten in ein generisches Schema und operationsspezifische Schemata aufgeteilt.

Alle Datums-/Zeitfelder in der Antwort werden als ISO-8601-Strings zurückgegeben (zum Beispiel 2026-06-17T10:15:00+00:00), mit Ausname von Legac-Feldern.

Während der Übergangsphase bleiben Legacy-Zeitstempelfelder dort verfügbar, wo sie zutreffen.

2.1.1 Antwortschema (alle Operationen)

2.1.2 GET-Antwortschema

2.1.3 Schema für POST/PUT/DELETE-Antworten

Beispiel für eine erfolgreiche Antwort

[
    {
        "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."
    }
]

Beispiel für eine GET-Antwort

[
  {
    "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"
  }
]

Beispiel für eine Fehlerantwort

[
    {
        "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"
    }
]

Beispiel POST oder PUT

 [
    {
        "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"
            ]
        }
    },
    {
        …
    }
]

Beispiel DELETE

Fügen Sie für DELETE-Requests entweder die Referenz-ID der Stelle zur URL hinzu oder senden Sie ein Array mit Objekten im JSON-Format entsprechend der folgenden Tabelle im Body mit.

Beispiel DELETE-Request, bei dem die erste Stelle von Karriere-Südwestfalen und Karriere-Mittelhessen gelöscht wird, und die zweite von alle Jobbörsen

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

3. Unternehmensdaten

3.1 Ansprechpartner

Beispiele

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"
    },
    ...
]

Beispielantwort für einen Ansprechpartner

[
    {
        "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 Standorte

Beispiele

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"
    },
    ...
]

Beispielantwort für einen Standort

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

3.3 Unternehmens-Uploads

3.4 Standardmäßige Vorteile/Benefits des Unternehmens

Wenn sie nicht alle Unternehmensbenefits für ein bestimmtes Jobangebot anzeigen möchten, senden sie nur die IDs der gewollten Benefits in einem Array im Stellenangebot mit.

3.5 Jobbörsen des Unternehmens

4. Routen für allgemeine Informationen

4.1 Kategorien

Hinweis zur Abkündigung: Kategorien sind veraltet und können in einer zukünftigen Version entfernt werden. Bitte verwenden Sie stattdessen Berufsfelder (occupationalField).

Derzeit unterstützen wir folgende Kategorien, die Sie über ihre ID an uns übergeben können:

4.2 HTML-Tags

Die in der Stellenbeschreibung erlaubten Tags sind "<h3>", "<ul>", "<ol>", "<li>", "<a>", "<b>", "<strong>", "<br>", "<p>" und "<small>"..

4.3 Berufsfelder

Beispielantwort:

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

5. Objektstruktur

5.1 Stellenbeschreibung

Sie können die in 4.2 erwähnten HTML-Tags in den Text-Teilen der Beschreibung nutzen.

Wenn Ihnen ein benötigter Teil des Textes fehlt, senden Sie einen leeren String für diesen Teil mit.

5.2 Ansprechpartner

5.3 Standort

5.4 Uploads

Wenn einem Stellenangebot keine Bilder hinzugefügt werden, wird das zweite Bild aus dem Unternehmensporträt hinzugefügt.

Erlaubte Formate sind: .jpg, .png und .gif.

Das bevorzugte Bildverhältnis für Stellenangebotsbilder ist 2:1 und die standardmäßige Größe ist 1200x600px.

Wenn das Verhältnis kleiner als 1,7 oder größer als 2,3 ist, wird es zugeschnitten. Pro Stellenangebot sind maximal 5 Bilder erlaubt.

Bilder von Ansprechpersonen sollten ein Seitenverhältnis von 1:1 haben, ansonsten werden sie in dieses Format zurechtgeschnitten.

5.5 Zeitarbeit

5.6 Berufsfeld

Kategorien sind veraltet. Wenn Kategoriedaten gesendet werden, werden sie einem Berufsfeld zugeordnet. Wenn sowohl categories als auch occupationalField gesendet werden, wird occupationalField als angezeigter Wert im Stellenangebot verwendet.

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

5.7 Gehalt

6. Antwortschema

Alle Import-Endpunkte geben ein Array von Antwortobjekten zurück. Jedes Objekt enthält generische Antwort-Metadaten und kann je nach Endpunkt und Operation zusätzliche entitätsspezifische Felder enthalten.

6.1 Generische Antwortfelder

6.2 Stellenangebotsspezifische Felder

Siehe 2.1.2

6.3 Ansprechpartnerspezifische Felder

6.4 Standortspezifische Felder