openapi: "3.0.0"
info:
  description: "Die größte Stellendatenbank Deutschlands durchsuchen, Details zu Stellenanzeigen und Informationen über Arbeitgeber abrufen. <br><br>Die Authentifizierung funktioniert über die clientId:<br><br>clientId: jobboerse-jobsuche<br><br>Bei folgenden GET-requests ist die clientId als Header-Parameter 'X-API-Key' zu übergeben.<br><br>Ablauf: (1) Stellen suchen via /pc/v6/jobs oder /pc/v4/app/jobs → refnr merken (in `/pc/v6/jobs` die `referenznummer`). (2) Details abrufen via /pc/v4/jobdetails/{base64(refnr)}. (3) Arbeitgeberlogo abrufen via /ct/v1/arbeitgeberlogo/{arbeitgeberKundennummerHash} (sofern vorhanden)."
  version: "2.1.0"
  title: "Arbeitsagentur Jobsuche API"

servers:
  - url: "https://rest.arbeitsagentur.de/jobboerse/jobsuche-service"

paths:
  /pc/v6/jobs:
    get:
      summary: Jobsuche
      description: "Die Jobsuche ermöglicht verfügbare Jobangebote mit verschiedenen get Parametern zu filtern."
      responses:
        '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/JobSearchResponse'
      parameters:
        - in: query
          name: was
          schema:
            type: string
          description: Freitext suche Jobtitel
          example: Referatsleiter
          required: false
        - in: query
          name: wo
          schema:
            type: string
          description: Freitext suche Beschäftigungsort
          example: Berlin
          required: false
        - in: query
          name: berufsfeld
          schema:
            type: string
          description: Freitext suche Berufsfeld
          example: Informatik
          required: false          
        - in: query
          name: page
          schema:
            type: integer
          description: Ergebnissseite
          example: 1
          required: false
        - in: query
          name: size
          schema:
            type: integer
          example: 50
          description: Anzahl von Ergebnissen
          required: false
        - in: query
          name: arbeitgeber
          schema:
            type: string
          example: Deutsche%20Bahn%20AG
          description: Arbeitgeber der Stelle
          required: false
        - in: query
          name: veroeffentlichtseit
          schema:
            type: integer
          example: 30
          description: Anzahl der Tage, seit der Job veröffentlicht wurde. Kann zwischen 0 und 100 Tagen liegen.
          required: false
        - in: query
          name: zeitarbeit
          schema:
            type: boolean
          example: true
          description: Gibt an, ob Jobs von Zeitarbeitsfirmen in die Suchergebnisse einbezogen werden sollen (default true).
          required: false
        - in: query
          name: angebotsart
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 4
              - 34
          example: 1
          description: 1=ARBEIT; 2=SELBSTAENDIGKEIT, 4=AUSBILDUNG/Duales Studium, 34=Praktikum/Trainee
          required: false
        - in: query
          name: befristung
          schema:
            type: integer
            enum:
              - 1
              - 2
          example: 1
          required: false
          description: Semikolon-separierte mehrere Werte möglich (z.B. befristung=1;2) 1 = befristet; 2 = unbefristet
        - in: query
          name: arbeitszeit
          schema:
            type: string
            enum:
              - vz
              - tz
              - snw
              - ho
              - mj
          description: Semikolon-separierte mehrere Werte möglich (z.B. arbeitszeit=vz;tz) vz=VOLLZEIT, tz=TEILZEIT, snw=SCHICHT_NACHTARBEIT_WOCHENENDE, ho=HEIM_TELEARBEIT, mj=MINIJOB
          example: vz
          required: false

        - in: query
          name: behinderung
          schema:
            type: boolean
          example: true
          required: false
        - in: query
          name: corona
          schema:
            type: boolean
          example: true
          description: Wenn true, werden nur Jobs die im Kontext von Corona angeboten werden angezeigt.
          required: false
        - in: query
          name: umkreis
          schema:
            type: integer
          description: Umkreis in Kilometern von Wo-Parameter. (z.B. 25 oder 200)
          example: 25
          required: false

  /pc/v4/app/jobs:
    get:
      summary: Jobsuche via App
      description: "Die Jobsuche via App ermöglicht verfügbare Jobangebote mit verschiedenen get Parametern zu filtern."
      responses:
        '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/JobSearchResponse'
      parameters:
        - in: query
          name: was
          schema:
            type: string
          description: Freitext suche Jobtitel
          example: Referatsleiter
          required: false
        - in: query
          name: wo
          schema:
            type: string
          description: Freitext suche Beschäftigungsort
          example: Berlin
          required: false
        - in: query
          name: berufsfeld
          schema:
            type: string
          description: Freitext suche Berufsfeld
          example: Informatik
          required: false          
        - in: query
          name: page
          schema:
            type: integer
          description: Ergebnissseite
          example: 1
          required: false
        - in: query
          name: size
          schema:
            type: integer
          example: 50
          description: Anzahl von Ergebnissen
          required: false
        - in: query
          name: arbeitgeber
          schema:
            type: string
          example: Deutsche%20Bahn%20AG
          description: Arbeitgeber der Stelle
          required: false
        - in: query
          name: veroeffentlichtseit
          schema:
            type: integer
          example: 30
          description: Anzahl der Tage, seit der Job veröffentlicht wurde. Kann zwischen 0 und 100 Tagen liegen.
          required: false
        - in: query
          name: zeitarbeit
          schema:
            type: boolean
          example: true
          description: Gibt an, ob Jobs von Zeitarbeitsfirmen in die Suchergebnisse einbezogen werden sollen (default true).
          required: false
        - in: query
          name: angebotsart
          schema:
            type: integer
            enum:
              - 1
              - 2
              - 4
              - 34
          example: 1
          description: 1=ARBEIT; 2=SELBSTAENDIGKEIT, 4=AUSBILDUNG/Duales Studium, 34=Praktikum/Trainee
          required: false
        - in: query
          name: befristung
          schema:
            type: integer
            enum:
              - 1
              - 2
          example: 1
          required: false
          description: Semikolon-separierte mehrere Werte möglich (z.B. befristung=1;2) 1 = befristet; 2 = unbefristet
        - in: query
          name: arbeitszeit
          schema:
            type: string
            enum:
              - vz
              - tz
              - snw
              - ho
              - mj
          description: Semikolon-separierte mehrere Werte möglich (z.B. arbeitszeit=vz;tz) vz=VOLLZEIT, tz=TEILZEIT, snw=SCHICHT_NACHTARBEIT_WOCHENENDE, ho=HEIM_TELEARBEIT, mj=MINIJOB
          example: vz
          required: false

        - in: query
          name: behinderung
          schema:
            type: boolean
          example: true
          required: false
        - in: query
          name: corona
          schema:
            type: boolean
          example: true
          description: Wenn true, werden nur Jobs die im Kontext von Corona angeboten werden angezeigt.
          required: false
        - in: query
          name: umkreis
          schema:
            type: integer
          description: Umkreis in Kilometern von Wo-Parameter. (z.B. 25 oder 200)
          example: 25
          required: false


  /pc/v4/jobdetails/{encryptedJobCode}:
    get:
      summary: Jobdetails (v4)
      description: "Abrufen der Details einer Stellenanzeige anhand des Base64-kodierten Referenzwertes (base64(refnr)). Empfohlene Version."
      parameters:
        - name: encryptedJobCode
          in: path
          required: true
          schema:
            type: string
            example: MTAwMDEtMTAwMjcxNjkyMi1T
          description: "Base64-kodierter Wert der refnr aus der Jobsuche. Beispiel: base64('10001-1002716922-S') = 'MTAwMDEtMTAwMjcxNjkyMi1T'"
      responses:
        '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/JobDetails'

  /pc/v3/jobdetails/{encryptedJobCode}:
    get:
      summary: Jobdetails (v3)
      description: "Abrufen der Details einer Stellenanzeige anhand des Base64-kodierten Referenzwertes (base64(refnr))."
      parameters:
        - name: encryptedJobCode
          in: path
          required: true
          schema:
            type: string
            example: MTAwMDEtMTAwMjcxNjkyMi1T
          description: "Base64-kodierter Wert der refnr aus der Jobsuche. Beispiel: base64('10001-1002716922-S') = 'MTAwMDEtMTAwMjcxNjkyMi1T'"
      responses:
        '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/JobDetails'

  /ct/v1/arbeitgeberlogo/{kundennummerHash}:
    servers:
      - url: "https://rest.arbeitsagentur.de/vermittlung/ag-darstellung-service"
    get:
      summary: Unternehmen Logo
      description: "Abrufen des Logos eines Unternehmens anhand des arbeitgeberKundennummerHash aus der Jobdetail-Antwort. Gibt 404 zurück, wenn kein Logo vorhanden ist."
      parameters:
        - name: kundennummerHash
          in: path
          required: true
          schema:
            type: string
            example: Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA=
          description: "Wert des Feldes arbeitgeberKundennummerHash aus der Jobdetail-Antwort (URL-kodiert falls nötig)."
      responses:
        '200':
            description: OK
            content:
              image/webp:
                schema:
                  type: string
                  format: binary
              image/png:
                schema:
                  type: string
                  format: binary
        '404':
            description: Kein Logo für diesen Arbeitgeber vorhanden.


security:
  - APIKeyHeaders: []

components:
  securitySchemes:
    APIKeyHeaders:    
      type: apiKey
      in: header
      name: X-API-Key
      description: "X-API-Key ist die clientId jobboerse-jobsuche"
      
  schemas:

    JobSearchResponse:
      type: "object"
      properties:
        stellenangebote:
          type: array
          items: 
            type: object
            properties: 
              hashId: 
                type: string
                example: WBTAiM10b25rJgZqiLhVIHzAF9e0rnV_DXdsRZtlb54=
              beruf: 
                type: string
                example: Elektroinstallateur/in              
              refnr: 
                type: string
                example: 10000-1184867112-S
              arbeitgeber: 
                type: string
                example: Gröger & Oltermann Sicherheits- und Elektrotechnik GmbH
              aktuelleVeroeffentlichungsdatum: 
                type: string
                format: date
                example: 2021-07-25
              eintrittsdatum: 
                type: string
                format: date
                example: 2021-07-26
              arbeitsort: 
                  type: object
                  properties: 
                    plz: 
                      type: integer
                      example: 90537
                    ort: 
                      type: string
                      example: Berlin
                    strasse: 
                      type: string
                      example: Altdorfer Straße
                    region: 
                      type: string
                      example: Berlin
                    land: 
                      type: string
                      example: Deutschland
                    koordinaten: 
                      type: object
                      properties: 
                        lat: 
                          type: number
                          example: 52.4926832
                        lon: 
                          type: number
                          example: 13.4025753
              kundennummerHash:
                type: string
                nullable: true
                example: Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA=
                description: "Hash-ID des Arbeitgebers für den Logo-Abruf. Ist nicht immer vorhanden."
              externeUrl:
                type: string
                nullable: true
                example: https://example.com/job/123
                description: "Externe URL zur Stellenanzeige (optional)."
              modifikationsTimestamp: 
                type: string
        maxErgebnisse:
          type: string
        page:
          type: string
        size:
          type: string
        facetten: 
          type: array
          items: 
            type: object
            properties: 
              befristung:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              behinderung:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              pav:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              berufsfeld:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              arbeitsort:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              ausbildungsart:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              veroeffentlichtseit:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              schulbildung:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              arbeitsort_plz:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              arbeitgeber:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              beruf:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              branche:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              arbeitszeit:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              eintrittsdatum:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              zeitarbeit:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
              corona:
                type: object
                properties: 
                  counts:
                    type: object
                  maxCount:
                    type: integer
    JobDetails:
      type: object
      properties:
            aktuelleVeroeffentlichungsdatum: 
              type: string
              format: date
              example: 2021-07-25
            angebotsart: 
              type: string
              example: ARBEIT
            arbeitgeber: 
              type: string
              example: Kerstin Nickel Frisör
            branchengruppe: 
              type: string
              example:  IT, Computer, Telekommunikation
            branche: 
              type: string
              example:  Sonstige Softwareentwicklung              
            arbeitgeberHashId: 
              type: string
              example: dj32HpGiU3tdrYi6ohcMOtUhtBLPvwGIRiRlcvDsebg=
            arbeitgeberKundennummerHash:
              type: string
              nullable: true
              example: Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA=
              description: "Hash-ID des Arbeitgebers für den Logo-Abruf (/ct/v1/arbeitgeberlogo/{arbeitgeberKundennummerHash}). Kann null sein."
            arbeitsorte: 
              type: array
              items: 
                type: object
                properties: 
                  land: 
                    type: string
                    example: Deutschland
                  region: 
                    type: string
                    example: Berlin
                  plz: 
                    type: string
                    example: "13597"
                  ort: 
                    type: string
                    example: Berlin
                  strasse: 
                    type: string
                    example: Jüdenstr. 31
                  koordinaten: 
                    type: object
                    properties: 
                      lat: 
                        type: number
                        example: 52.5383857
                      lon: 
                        type: number
                        example: 13.2029692
            arbeitszeitmodelle: 
              type: array
              items: 
                type: string
                example: TEILZEIT
            befristung: 
              type: string
              example: UNBEFRISTET
            uebernahme: 
              type: boolean
              example: false
            betriebsgroesse: 
              type: string
              example: '2'
            eintrittsdatum: 
              type: string
              format: date
              example: 2021-07-25
            ersteVeroeffentlichungsdatum: 
              type: string
              format: date
              example: 2021-05-23              
            allianzpartner: 
              type: string
              example: arbeitsagentur.de
            allianzpartnerUrl: 
              type: string
              example: http://www.arbeitsagentur.de
            titel: 
              type: string
              example: Wissenschaftlicher Mitarbeiter (m/w/d)              
            stellenangebotsTitel:
              type: string
              example: Wissenschaftlicher Mitarbeiter (m/w/d)
              description: "Stellen-Titel (Feldname in v3/v4 jobdetails-Antworten)."
            hashId: 
              type: string
              example: VK2qoXBe0s-UAdH_qxLDRrZrY5iY8a1PJt3MjJCXsdo=
            beruf: 
              type: string
              example: Wissenschaftliche/r Mitarbeiter/in (Hochschule)
            modifikationsTimestamp: 
              type: string
              example: 2021-07-25T13:12:33.913
            stellenbeschreibung: 
              type: string
            stellenangebotsBeschreibung:
              type: string
              description: "Stellenbeschreibung (Feldname in v3/v4 jobdetails-Antworten)."
            refnr: 
              type: string
              example: 10000-1183999289-S
            referenznummer:
              type: string
              example: 10000-1183999289-S
              description: "Referenznummer der Stelle (Feldname in v3/v4 jobdetails-Antworten)."
            fuerFluechtlingeGeeignet: 
              type: boolean
              example: false
            nurFuerSchwerbehinderte: 
              type: boolean
              example: false
            anzahlOffeneStellen: 
              type: integer
              format: int32
              example: 1
            arbeitgeberAdresse: 
              type: object
              properties: 
                land: 
                  type: string
                  example: Deutschland
                region: 
                  type: string
                  example: Berlin
                plz: 
                  type: string
                  example: "13597"
                ort: 
                  type: string
                  example: Berlin
                strasse: 
                  type: string
                  example: Jüdenstr. 31
                strasseHausnummer: 
                  type: string
                  example: Jüdenstr. 31
            fertigkeiten: 
              type: array
              items: 
                type: object
                properties: 
                  hierarchieName: 
                    type: string
                    example: Soziales, Erziehung, Gesundheit, Sport
                  auspraegungen: 
                    type: object
            mobilitaet: 
              type: object
              properties: 
                reisebereitschaft: 
                  type: string
                  example: '1'
            fuehrungskompetenzen: 
              type: object
              properties: 
                hatVollmacht: 
                  type: boolean
                  example: false
                hatBudgetverantwortung: 
                  type: boolean
                  example: false                  
            verguetung: 
              type: string
              example: Entgeltgruppe 13 TV-L
            arbeitgeberdarstellungUrl: 
              type: string
              example: http://www.friseur-nickel.de
            arbeitgeberdarstellung: 
              type: string
            hauptDkz: 
              type: string
              example: "9907"
            istBetreut: 
              type: boolean
            istGoogleJobsRelevant: 
              type: boolean
            anzeigeAnonym: 
              type: boolean

externalDocs:
  description: "Weiterführende Dokumentation"
  url: "https://github.com/bundesAPI/jobsuche-api"