Please align Jobsuche documentation/OpenAPI with the currently working live detail and logo endpoints

[katsaran]

Hello,

we re-tested the live BA Jobsuche API and now have a reproducible working flow for:

• vacancy discovery
• vacancy detail retrieval
• employer logo retrieval

The main issue is that the currently working live API behavior does not match the currently published documentation / OpenAPI on:

• https://jobsuche.api.bund.dev/
• https://github.com/bundesAPI/jobsuche-api

Summary

From live testing, the currently working flow is:

1. Discover vacancies via:

   • GET /pc/v4/jobs
   • or GET /pc/v4/app/jobs

2. Retrieve vacancy details via:

   • GET /pc/v3/jobdetails/{base64(refnr)}
   • or GET /pc/v4/jobdetails/{base64(refnr)}

3. Retrieve employer logo via:

   • GET /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/{kundennummerHash}

However, the current public docs/OpenAPI still expose only:

• /pc/v4/jobs
• /pc/v4/app/jobs
• /ed/v1/arbeitgeberlogo/{hashID}

and do not document the currently working jobdetails flow.

Confirmed working live flow

1. Vacancy discovery

These endpoints work for vacancy discovery:

• GET /pc/v4/jobs
• GET /pc/v4/app/jobs

In live responses we consistently observed fields such as:

• refnr
• titel
• arbeitgeber
• arbeitsort
• beruf
• kundennummerHash (optional)
• externeUrl (optional)

In our live samples, we did not see a usable hashId in the listing payload.

2. Vacancy details

The currently working detail lookup is based on refnr, not on hashId.

The working key is:

• base64(refnr)

Confirmed working endpoints:

• GET /pc/v3/jobdetails/{base64(refnr)}
• GET /pc/v4/jobdetails/{base64(refnr)}

Example:

• refnr = 10001-1002716922-S
• base64(refnr) = MTAwMDEtMTAwMjcxNjkyMi1T

Working requests:

• GET /pc/v3/jobdetails/MTAwMDEtMTAwMjcxNjkyMi1T -> 200
• GET /pc/v4/jobdetails/MTAwMDEtMTAwMjcxNjkyMi1T -> 200

Non-working request:

• GET /pc/v2/jobdetails/MTAwMDEtMTAwMjcxNjkyMi1T -> 403

The detail response returns fields such as:

• stellenangebotsBeschreibung
• stellenangebotsTitel
• referenznummer
• arbeitgeberKundennummerHash

So at least in the currently working live API, vacancy details are retrievable via base64(refnr).

3. Employer logo

The currently working logo lookup is:

• GET /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/{kundennummerHash}

Example with an existing logo:

• refnr = 12016-10004206993-S
• detail request works
• arbeitgeberKundennummerHash = Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA=
• GET /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA%3D -> 200 image/webp

4. Important edge cases

a) Details work even when the listing has no kundennummerHash

We found live listings that have:

• refnr
• externeUrl
• no kundennummerHash

Example:

• refnr = 18024-100YY0001DV0U-S
• externeUrl = https://helixjobs.com/_/jobad?prj=2142p4681&source=ba

For this vacancy:

• GET /pc/v3/jobdetails/{base64(refnr)} -> 200
• stellenangebotsBeschreibung is present
• arbeitgeberKundennummerHash is null

This suggests:

• kundennummerHash is not required for vacancy detail retrieval
• it is only relevant for employer/logo retrieval
• some listings may simply not expose a logo identifier at all

b) 404 on the working logo endpoint appears to mean “logo not available”

We tested a case where details work, but the logo endpoint returns 404:

• refnr = 10001-1002716922-S
• GET /pc/v3/jobdetails/{base64(refnr)} -> 200
• arbeitgeberKundennummerHash = fP-AxW5lLoUep5J8SsYdE6zrucX-wqNZGBX_OFYHyJY=
• GET /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/{...} -> 404

We also tested a case where the same endpoint returns a real image:

• GET /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/Z-HzVkUCLGQiQFxQSAICs302sSdB9Sp7XtgOiO4GGCA%3D -> 200 image/webp

So 404 on the currently working ct/v1 logo endpoint appears to be a normal “logo not available” case, not necessarily an API misuse case.

What appears to be out of sync

Current OpenAPI/docs still expose only:

• /pc/v4/jobs
• /pc/v4/app/jobs
• /ed/v1/arbeitgeberlogo/{hashID}

But the live working behavior we verified is:

• discovery via /pc/v4/jobs or /pc/v4/app/jobs
• details via /pc/v3/jobdetails/{base64(refnr)} or /pc/v4/jobdetails/{base64(refnr)}
• logo via /vermittlung/ag-darstellung-service/ct/v1/arbeitgeberlogo/{kundennummerHash}

The currently documented logo endpoint does not match our live tests:

• GET /vermittlung/ag-darstellung-service/ed/v1/arbeitgeberlogo/{kundennummerHash} -> 403
• GET /jobboerse/jobsuche-service/ed/v1/arbeitgeberlogo/{kundennummerHash} -> 403

So ed/v1 does not appear to be the currently working public logo path for kundennummerHash, while ct/v1 does.

Request

Could you please:

1. Document the currently supported vacancy detail lookup path
2. Document clearly that the currently working detail key is base64(refnr)
3. Document the currently supported employer logo path and identifier
4. Document the important edge cases:
   • listings without kundennummerHash
   • 404 from the working logo endpoint when no logo exists
5. Align:
   • jobsuche.api.bund.dev
   • openapi.yaml
   • generated clients / examples
6. Clarify whether:
   • /pc/v3/jobdetails/{base64(refnr)}
   • /pc/v4/jobdetails/{base64(refnr)}
     are both supported, and which one should be preferred

Related issues

This seems related to:

• jobsearch does not return hashes so the jobdetails cannot be retrieved #59
• Endpunkt für Jobdetails gibt 404 #57
• 404 bei /pc/v4/jobs/{refnr} trotz gültiger Referenznummer aus Suchergebnis #61
• How can I get employer logo? #62

At this point the main issue is no longer only how to reverse-engineer the workaround, but documenting the currently working API contract clearly and consistently across all official/public surfaces.

Thanks.