pull_api.md

Pull API

Documentation for Absolventa and Azubi.de

Our application is able to process data streams served via HTTP of different format. If you already have your jobs wrapped into a custom data stream ready to read via HTTP, please contact our team to verify if we can handle it.
Once a connection is established, we regularly (usually once a day) parse the provided feed and adjust the published job offers accordingly:

• Job offers present in the feed that are not yet published on our platform will be published.
• Job offers present in the feed that are already published on our platform will be updated according to the provided information.
• Job offers not present in the feed anymore but published on our platform will be quit.

Note that job offers can only be published if the booked contract allows for it. If a job offer is still present in a feed after its runtime as specified by the contract is over, it will be treated as a new job offer (and hence get newly published if the contract still allows for it). If you want to connect to more than one of our platforms, please provide one feed per platform.

Sample Data Format

Here's an ideal XML feed for our applications. If you are able to provide your job data in this format, we can immediately configure a connection:

<?xml version='1.0' encoding='utf-8' ?>
<job_offers type='array'>
  <job_offer>
    <external_id>ABC-12345</external_id>
    <title>Seefahrer:in (w/m/d)</title>

    <application_email>elaine.marley@absolventa.de</application_email>
    <application_url><![CDATA[https://www.example.com/jobs/seefahrt/apply]]></application_url>
    <application_system_email>guybrush.threepwood@absolventa.de</application_system_email>

    <job_offer_locations>
      <job_offer_location>
        <city>Berlin</city>
        <street>Greifswalder Straße 212</street>
        <zip>10405</zip>
        <country>Deutschland</country>
      </job_offer_location>
    </job_offer_locations>

    <description_headline>Komm' an Bord!</description_headline>
    <description>
      <![CDATA[
        <p>
          Unser renormiertes Seefahrtsunternehmen heuert verlässlich und regelmäßig die besten
          Seefrauen und -männer (w/m/d) östlich des Atlantiks an. Generationen von Seefahrtsexperten
          haben ihre Karriere mit ersten nautischen Schritten in unserem Unternehmen gestartet.
        </p>
      ]]>
    </description>

    <tasks_headline>Du kannst im Schlaf unter tosendem Sturm problemlos Segel setzen?</tasks_headline>
    <tasks>
      <![CDATA[
        <ul>
          <li>Du peppst die rauhen und kantigen Geschichten unserer weltweit verstreuten Mitarbeiter linguistisch gekonnt auf</li>
          <li>Dein Instikt lässt dich spielerisch prüfbare Fakten von hanebüchenem Seemannsgarn unterscheiden</li>
        </ul>
      ]]>
    </tasks>

    <qualifications_headline>Du bist mutig genug, in allen Ozeanen dieser Welt zu schwimmen?</qualifications_headline>
    <qualifications>
      <![CDATA[
        <ul>
          <li>Du kannst schwimmen (Seepferdchen notwendig)</li>
          <li>Ein leichtes Schaukeln ist für dich kein Problem</li>
        </ul>
      ]]>
    </qualifications>

    <benefits_headline>Bestens ausgerüstet!</benefits_headline>
    <benefits>
      <![CDATA[
        <ul>
          <li>Reise zum Ende der Welt</li>
          <li>Ein loyales Team</li>
          <li>Remote first: Wir begrüßen ausdrücklich das eigenständige, asynchrone Arbeiten in entlegenen Gegenden</li>
        </ul>
      ]]>
    </benefits>

    <contact_headline>Frag' unsere Expertin Elaine!</contact_headline>
    <contact>
      <![CDATA[
        <p>Elaine Marley</p>
        <p>elaine.marley@absolventa.de</p>
        <small>Senior Seefahrt-Personalmanagerin</small>
      ]]>
    </contact>

    <company_description_headline>Unser Geschäft ist kein Voodoo!</company_description_headline>
    <company_description>
      <![CDATA[
        <p>Marley & Threepwood Ventures - Ihr Partner in Sachen Seefahrt- und Handelsbeziehungen</p>
      ]]>
    </company_description>

    <video_url><![CDATA[https://api.example.com/videos/seemannsgarn]]></video_url>
    <header_image_url><![CDATA[https://api.example.com/content/header_image.jpg]]></header_image_url>
    <color>#efefef</color>
    <custom_company_title>Threepwood GmbH</custom_company_title>

    <remote_work>required</remote_work>
    <work_experience>optional</work_experience>
    <work_hours>part_time</work_hours>
    <without_cover_letter>true</without_cover_letter>

    <!-- attributes only relevant for absolventa.de -->

    <!-- with fixed salary -->
    <salary_information_type>fixed</salary_information_type>
    <salary_type>monthly</salary_type>
    <salary_fixed>3000</salary_fixed>

    <!-- with salary range -->
    <salary_information_type>range</salary_information_type>
    <salary_type>yearly</salary_type>
    <salary_min>50000</salary_min>
    <salary_max>60000</salary_max>

    <!-- end of attributes only relevant for absolventa.de -->

    <!-- attributes only relevant for azubi.de -->

    <apprenticeship_started_at type='datetime'>
      2017-07-07T00:00:00+02:00
    </apprenticeship_started_at>
    <minimal_degree>basic</minimal_degree>
    <duration>36</duration>
    <salary_first_year>1000</salary_first_year>
    <salary_second_year>1200</salary_second_year>
    <salary_third_year>1400</salary_third_year>
    <salary_fourth_year>1600</salary_fourth_year>

    <!-- end of attributes only relevant for azubi.de -->

    <!-- attributes only relevant for agencies -->

    <company_title><![CDATA[Marley & Threepwood Ventures GmbH]]></company_title>
    <company_external_id>1234</company_external_id>
    <company_logo_url><![CDATA[https://api.example.com/company_logo.jpg]]></company_logo_url>
    <agency_order_number>12345abc</agency_order_number>

    <!-- end of attributes only relevant for agencies -->
  </job_offer>
  <job_offer>
    ...
  </job_offer>
</job_offers>

Data fields

attribute	value	type
external_id	Your internal identifier of the record. Has to be unique among published records and is not allowed to change.	String	required
title	Title	String	required
application_email	Email address potential candidates shall send their applications to.	String	required (Either application_url, application_email or application_system_email is needed. If several are provided, we prioritize application_url, then application_email.)
application_url	URL pointing to the application online formular of the job offer.	String	required (Either application_url, application_email or application_system_email is needed. If several are provided, we prioritize application_url, then application_email.)
application_system_email	Email address where applications are forwarded to from the job board's internal application system.	String	required (Either application_url, application_email or application_system_email is needed. If several are provided, we prioritize application_url, then application_email.)
job_offer_locations	List of job_offer_location objects. Each job_offer_location contained in the list has to include at least a city and a zip value. Usually, only one job_offer_location object is allowed.	job_offer_location object	optional
description_headline	Headline summarizing the introductory description-content.	Text	optional
description	Description text of your job ad. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	required
tasks_headline	Headline summarizing the tasks-content.	Text	optional
tasks	Text summarizing the job tasks of the candiates. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	optional
qualifications_headline	Headline summarizing the introductory qualifications-content.	Text	optional
qualifications	Text summarizing the requirements of the candiates. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	optional
benefits_headline	Headline summarizing the benefits-content.	Text	optional
benefits	Text summarizing the job benefits of the candiates. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	optional
contact_headline	Headline summarizing the contact-content.	Text	optional
contact	Text summarizing the contact information for the candiates. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	optional
company_description_headline	Headline summarizing the company_description-content.	Text	optional
company_description	Description text of your company. Simple HTML tags such as strong, em, u, i, ol, ul, li, p, br, a are allowed.	Text	optional
video_url	URL to embeddable video content.	String	optional
header_image_url	URL to image that is being displayed at the top of the job ad. Image resolution: 2340 x 936 px (5:2 aspect ratio) Max. file size: 1 MB Formats: jpg, png	String	optional
color	Hex code for headline color.	String	optional
custom_company_title	Custom company title, e.g. to display a specific branch's or subsidiary's name.	String	optional
remote_work	Possibilities to work remotely. Possible values: optional required unavailable	String	optional
work_experience	Prior work experience. Possible values: optional preferred required	String	optional
work_hours	Part-time or full-time position. Possible values: full_time optionally_part_time part_time	String	optional
without_cover_letter	Whether cover letter can be omitted. true or false (as strings) are possible values. Defaults to false, i.e. application requires cover letter.	String	optional
Attributes only relevant for absolventa.de:
salary_information_type	Type of salary information. Possible values: fixed (Precise, fixed salary information available) range (Salary information available as a range of two values) Will default to an unset value not_set	String	optional
salary_type	Type of given salary. Possible values: yearly monthly hourly	String	optional
salary_fixed	The fixed salary in EUR.	Integer	only required if salary_information_type is fixed
salary_min	The lower bound of the salary range in EUR.	Integer	only required if salary_information_type is range
salary_max	The upper bound of the salary range in EUR.	Integer	only required if salary_information_type is range
Attributes only relevant for azubi.de:
apprenticeship_started_at	Date on which the apprenticeship will start.	Datetime	required for azubi.de
minimal_degree	Minimal graduation degree the candidates should own. Possible values: basic (Hauptschulabschluss) certificate (Mittlere Reife) graduation ([Fach-]Abitur)	String	optional
duration	Duration of the apprenticeship in months.	Integer	optional
salary_first_year	Salary during the first year of the apprenticeship. The second, third, and forth years can be added in the same way, eg. salary_second_year, etc.	Integer	optional

Additional data fields for agencies

These fields are only relevant for customers that post job offers on behalf of multiple companies.

attribute	value	type
company_title	The name of the company for which the job is posted.	String	required
company_external_id	Your internal, unique identifier of the company. Should remain consistent across all job offers for the same company.	String	required (If you don't use IDs, the company_title can be given.)
company_logo_url	URL to the company's logo image to be displayed with the job posting. Image resolution: min. 400 x 400 px Formats: jpg, png	Text	optional
agency_order_number	Order number	String	optional