Job-API

Quickstart in 3 Schritten

1. 1

   API-Key erstellen

   Lege in deinem Konto unter Dashboard → API-Keys einen Schlüssel an. Er wird dir einmalig im Klartext angezeigt — kopiere ihn sofort.

2. 2

   Verbindung prüfen

   Ein erster Call an GET /api/v1/me bestätigt, dass dein Key gültig ist, und zeigt deine Guthaben-Stände.

   curl https://gewerbejobs24.de/api/v1/me \
     -H "Authorization: Bearer gj_live_dein_key"

3. 3

   Erste Stelle posten

   Schick einen POST /api/v1/jobs mit Titel, Beschreibung, Kategorie und Standort. Die Anzeige geht bei ausreichendem Guthaben sofort live. Das vollständige Beispiel findest du bei den Code-Beispielen.

Verbindung testen

Trag deinen API-Key ein und teste ihn direkt hier im Browser. Dieser Test ruft ausschließlich das lesende GET /api/v1/me auf — es wird nichts gepostet und kein Guthaben verbraucht. Dein Key bleibt lokal in deinem Browser und wird nirgends gespeichert.

Authentifizierung

Jeder Request trägt deinen API-Key im Authorization-Header als Bearer-Token. Es gibt keine Cookies und keinen Login-Flow — die API ist rein Maschine-zu-Maschine.

Authorization: Bearer gj_live_dein_key

• •Der Key wird nur einmal bei der Erstellung im Klartext angezeigt. Gespeichert wird bei uns nur ein Hash — verlierst du ihn, erstelle einen neuen.
• •Du kannst mehrere Keys parallel führen (z. B. für Rotation) und jeden einzeln widerrufen.
• •Behandle den Key wie ein Passwort. Gib ihn nicht im Frontend oder in öffentlichen Repos preis.

Abrechnung (Prepaid)

Beim Posten wird das Guthaben in dieser Reihenfolge belastet:

1. Zuerst ein Bundle-Credit (1 Credit = 1 Anzeige × 30 Tage), ältester zuerst.
2. Sonst dein Geld-Guthaben, sofern es den Anzeigenpreis deckt.
3. Reicht beides nicht, antwortet die API mit HTTP 402 und einem Hinweis, ein Bundle zu kaufen oder aufzuladen.

Deine aktuellen Stände fragst du jederzeit über GET /api/v1/credits ab.

Endpoints-Referenz

Basis-URL: https://gewerbejobs24.de/api/v1. Alle Antworten sind JSON, Enums werden als String übertragen.

{
  "companyName": "Muster Elektro GmbH",
  "email": "kontakt@muster-elektro.de",
  "customerNumber": 10042,
  "moneyCredit": 49.00,
  "bundleCreditsRemaining": 8
}

{
  "moneyCredit": 49.00,
  "bundleCreditsRemaining": 8
}

{
  "jobs": [
    {
      "id": "665f0c1e9b3a2f00123abcd0",
      "title": "Elektroniker (m/w/d) für Energie- und Gebäudetechnik",
      "status": "Active",
      "publicUrl": "https://gewerbejobs24.de/job/elektroniker-mwd-frankfurt",
      "expiresAt": "2026-10-06T00:00:00Z",
      "createdAt": "2026-09-06T09:12:00Z",
      "externalRef": "req-2026-00042"
    }
  ]
}

{
  "id": "665f0c1e9b3a2f00123abcd0",
  "title": "Elektroniker (m/w/d) für Energie- und Gebäudetechnik",
  "status": "Active",
  "publicUrl": "https://gewerbejobs24.de/job/elektroniker-mwd-frankfurt",
  "expiresAt": "2026-10-06T00:00:00Z",
  "createdAt": "2026-09-06T09:12:00Z",
  "externalRef": "req-2026-00042"
}

{
  "title": "Elektroniker (m/w/d) für Energie- und Gebäudetechnik",
  "description": "…Volltext der Stellenbeschreibung…",
  "companyName": "Muster Elektro GmbH",
  "categorySlug": "elektro",
  "types": ["FullTime"],
  "locations": [
    { "city": "Frankfurt am Main", "postalCode": "60311", "state": "Hessen" }
  ],
  "isRemote": false,
  "isNationwide": false,
  "contactEmail": "bewerbung@muster-elektro.de",
  "salaryFrom": 3200,
  "salaryTo": 4100,
  "salaryUnit": "month",
  "whatsAppNumber": null,
  "attachmentUrl": null,
  "externalRef": "req-2026-00042"
}

{
  "id": "665f0c1e9b3a2f00123abcd0",
  "status": "Active",
  "publicUrl": "https://gewerbejobs24.de/job/elektroniker-mwd-frankfurt",
  "creditSource": "Bundle",
  "expiresAt": "2026-10-06T00:00:00Z",
  "externalRef": "req-2026-00042"
}

{
  "jobs": [
    {
      "title": "Elektroniker (m/w/d)",
      "description": "…",
      "companyName": "Muster Elektro GmbH",
      "categorySlug": "elektro",
      "types": ["FullTime"],
      "locations": [{ "city": "Frankfurt am Main", "postalCode": "60311" }],
      "externalRef": "req-1"
    },
    {
      "title": "Anlagenmechaniker (m/w/d)",
      "description": "…",
      "companyName": "Muster Elektro GmbH",
      "categorySlug": "shk",
      "types": ["FullTime"],
      "locations": [{ "city": "Offenbach", "postalCode": "63065" }],
      "externalRef": "req-2"
    }
  ]
}

{
  "results": [
    {
      "index": 0, "externalRef": "req-1", "status": "created",
      "id": "665f0c1e9b3a2f00123abcd0",
      "publicUrl": "https://gewerbejobs24.de/job/elektroniker-mwd-frankfurt",
      "creditSource": "Bundle", "expiresAt": "2026-10-06T00:00:00Z",
      "error": null, "errorCode": null
    },
    {
      "index": 1, "externalRef": "req-2", "status": "failed",
      "id": null, "publicUrl": null, "creditSource": null, "expiresAt": null,
      "error": "Kein Guthaben. Bitte kaufe ein Job-Bundle oder lade dein Guthaben auf.",
      "errorCode": "insufficient_credits"
    }
  ],
  "summary": { "created": 1, "failed": 1, "creditsUsed": 1 }
}

{
  "id": "665f0c1e9b3a2f00123abcd0",
  "status": "Deactivated"
}

Code-Beispiele

Eine Stelle anlegen (POST /api/v1/jobs) in deiner Sprache. Ersetze gj_live_dein_key durch deinen echten Key.

curl -X POST https://gewerbejobs24.de/api/v1/jobs \
  -H "Authorization: Bearer gj_live_dein_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9d5e-8b0a-4c2f-9e7d-1a2b3c4d5e6f" \
  -d '{
    "title": "Elektroniker (m/w/d)",
    "description": "…Volltext…",
    "companyName": "Muster Elektro GmbH",
    "categorySlug": "elektro",
    "types": ["FullTime"],
    "locations": [{ "city": "Frankfurt am Main", "postalCode": "60311", "state": "Hessen" }],
    "contactEmail": "bewerbung@muster-elektro.de",
    "salaryFrom": 3200, "salaryTo": 4100, "salaryUnit": "month",
    "externalRef": "req-2026-00042"
  }'

using System.Net.Http.Json;
using System.Net.Http.Headers;

var http = new HttpClient { BaseAddress = new Uri("https://gewerbejobs24.de/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "gj_live_dein_key");

var job = new
{
    title       = "Elektroniker (m/w/d)",
    description = "…Volltext…",
    companyName = "Muster Elektro GmbH",
    categorySlug = "elektro",
    types       = new[] { "FullTime" },
    locations   = new[] { new { city = "Frankfurt am Main", postalCode = "60311", state = "Hessen" } },
    contactEmail = "bewerbung@muster-elektro.de",
    salaryFrom  = 3200, salaryTo = 4100, salaryUnit = "month",
    externalRef = "req-2026-00042"
};

var request = new HttpRequestMessage(HttpMethod.Post, "api/v1/jobs")
{
    Content = JsonContent.Create(job)
};
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());

var response = await http.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());

import uuid
import requests

url = "https://gewerbejobs24.de/api/v1/jobs"
headers = {
    "Authorization": "Bearer gj_live_dein_key",
    "Idempotency-Key": str(uuid.uuid4()),
}
job = {
    "title": "Elektroniker (m/w/d)",
    "description": "…Volltext…",
    "companyName": "Muster Elektro GmbH",
    "categorySlug": "elektro",
    "types": ["FullTime"],
    "locations": [{"city": "Frankfurt am Main", "postalCode": "60311", "state": "Hessen"}],
    "contactEmail": "bewerbung@muster-elektro.de",
    "salaryFrom": 3200, "salaryTo": 4100, "salaryUnit": "month",
    "externalRef": "req-2026-00042",
}

resp = requests.post(url, json=job, headers=headers)
print(resp.status_code)
print(resp.json())

Idempotenz

Schreib-Requests solltest du mit einem Idempotency-Key-Header absichern (z. B. eine UUID pro fachlichem Vorgang). Damit sind Wiederholungen nach Timeouts oder Netzwerkfehlern sicher — du postest nie versehentlich doppelt.

Idempotency-Key: 3f1c9d5e-8b0a-4c2f-9e7d-1a2b3c4d5e6f

• •Gleicher Key + gleicher Body: Du erhältst die gespeicherte Antwort des ersten Aufrufs zurück — kein zweites Posting, kein zweiter Credit.
• •Gleicher Key, anderer Body: Die API antwortet mit 409 idempotency_conflict.
• •Gespeicherte Antworten werden nach 24 Stunden automatisch verworfen. Verwende danach einen neuen Key.

Fehlercodes

Fehler kommen als JSON mit stabilem code und einer les­baren message.

{ "error": { "code": "insufficient_credits", "message": "Kein Guthaben. Bitte kaufe ein Job-Bundle oder lade dein Guthaben auf." } }

Ein widerrufener Key wird mit 403 key_revoked abgewiesen.

Rate-Limits

Das Limit gilt pro API-Key als gleitendes Minutenfenster — aktuell großzügige 600 Requests pro Minute. Ein POST /jobs/bulk zählt dabei als ein einziger Request, egal wie viele Stellen er enthält. Bei Überschreitung antwortet die API mit 429 rate_limited — baue in deinem Client einen kurzen Retry mit Backoff ein. Brauchst du mehr Durchsatz, sprich uns an.