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
5. Object structure
   1. Offer Description
   2. Contact Person
   3. Location
   4. Uploads
   5. Temporary Work

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 it in the body of your request with the FormData-Interface. The JWT is valid for 60 seconds. To receive test credentials for development, contact our support.

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.

Example POST or 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
        ],
        "type": [
            "apprenticeship",
            "dual-study"
        ],
        "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"
    },
    ...
]

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

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

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>".

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