REST API · v1

Partner API
Documentatie

Integreer uw systeem rechtstreeks met het Jobhopr-platform. Maak bedrijfsaccounts aan, beheer vacatures en haal uw data op via een beveiligde REST-API.

Actief
Authenticatie vereist
JSON · UTF-8

Aan de slag

Quickstart in 3 stappen

Volg deze stappen om uw eerste succesvolle API-call te plaatsen.

Ontvang uw API-sleutel

Contacteer het Jobhopr-team op info@jobhopr.be. U ontvangt een persoonlijke x-api-key en een x-partner-id die uniek zijn voor uw integratie. Bewaar deze sleutels veilig, sla ze nooit op in publieke code of versiebeheer.

Maak een bedrijf aan

Stuur een POST-verzoek naar /api/v1/partner/companies met de basisgegevens van het bedrijf. U ontvangt een companyID terug die u voor de volgende stap nodig heeft.

Publiceer een vacature

Gebruik de companyID uit stap 2 om een vacature aan te maken via POST /api/v1/partner/companies/:companyID/jobs. De job is direct zichtbaar op het platform zodra status op ONLINE staat.

Beveiliging

Authenticatie

Elke aanvraag naar de Partner API vereist twee HTTP-headers: een API-sleutel en een partner-ID. Beide worden door Jobhopr verstrekt bij het starten van een integratie.

  • x-api-key — uw persoonlijke geheime API-sleutel. Elk partner-account heeft een eigen unieke sleutel. Verzoeken zonder geldige sleutel worden geweigerd met 401 Unauthorized.
  • x-partner-id — uw unieke partner-identifier, door Jobhopr aan u toegekend. Dit is een intern, opaak kenmerk van uw partner-account zodat u alleen uw eigen bedrijven kunt beheren. Verzoeken met een onbekend partner-ID worden geweigerd met 403 Forbidden.
Bewaar uw sleutels veilig. Stel beide headers in als omgevingsvariabelen in uw systeem. Verwijs er nooit rechtstreeks naar in broncode of Git-repositories.
Basis-URL: https://api.jobhopr.be
Alle endpoints beginnen met dit prefix, gevolgd door het pad in de voorbeelden hieronder.

Verplichte headers

HTTP-headers 
x-api-key:    jhr_live_xxxxxxxxxxxxxxxx
x-partner-id: ff3ff042-ec7a-4771-af60-d10db7cf5ad2

Voorbeeld — cURL

cURL 
curl https://api.jobhopr.be/api/v1/partner/companies \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..." \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ ... }'

Foutrespons — ongeldige API-sleutel

JSON · 401 
{
  "success": false,
  "error": {
    "code":    "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Foutrespons — onbekend partner-ID

JSON · 403 
{
  "success": false,
  "error": {
    "code":    "FORBIDDEN",
    "message": "Invalid or missing partner ID."
  }
}

Overzicht

Alle endpoints

Klik op een endpoint om naar de volledige documentatie te gaan.

POST
/api/v1/partner/companies Nieuw bedrijfsaccount aanmaken
→ GET
/api/v1/partner/companies Alle bedrijven van uw account ophalen
→ GET
/api/v1/partner/companies/:companyID Één bedrijf ophalen via ID
→ PATCH
/api/v1/partner/companies/:companyID Bedrijfsgegevens bijwerken
→ DELETE
/api/v1/partner/companies/:companyID Bedrijf verwijderen
→ POST
/api/v1/partner/companies/:companyID/jobs Nieuwe vacature aanmaken voor een bedrijf
→ GET
/api/v1/partner/companies/:companyID/jobs Alle vacatures van een bedrijf ophalen
→ GET
/api/v1/partner/companies/:companyID/jobs/:jobID 1 specifieke vacature ophalen
→ PATCH
/api/v1/partner/companies/:companyID/jobs/:jobID Vacature bijwerken
→ DELETE
/api/v1/partner/companies/:companyID/jobs/:jobID Vacature verwijderen
→ POST
/api/v1/partner/companies/:companyID/jobs/:jobID/campaigns Campagne starten voor een vacature
→

Endpoint 01

Bedrijf aanmaken

POST /api/v1/partner/companies

Maakt een nieuw bedrijfsaccount aan op het Jobhopr-platform. Sla de companyID uit de respons op, u heeft deze nodig om vacatures aan te maken.

Als een bedrijf met hetzelfde BTW-nummer al bestaat, retourneert de API een 409 Conflict-fout.

De respons bevat steeds alle gegevens van het bedrijf, dit geldt consistent voor elk company-endpoint (aanmaken, ophalen, bijwerken, verwijderen).

Verplichte body-velden

firstNamevereist string Voornaam van de contactpersoon.
lastNamevereist string Achternaam van de contactpersoon.
emailvereist string Zakelijk e-mailadres. Moet geldig formaat hebben.
companyNamevereist string Officiële naam van het bedrijf zoals het op het platform verschijnt.
telvereist string Belgisch telefoonnummer. Toegestane formaten: "0471234567", "+32471234567", "32471234567", "0032471234567". Spaties en streepjes worden automatisch verwijderd. Opgeslagen als "32xxxxxxxxx". Wordt overgenomen door vacatures die geen eigen telefoonnummer opgeven.
VATNumbervereist string Belgisch BTW-nummer. Formaat: BE gevolgd door 10 cijfers, bv. "BE0123456789". Punten, spaties en streepjes worden automatisch verwijderd.
addressvereist object Adres van de maatschappelijke zetel. Verplichte sub-velden: city, street, houseNumber, zip. Wordt overgenomen door vacatures die geen eigen adres opgeven.

Voorbeeldverzoek

JSON · Request body 
{
  "firstName":   "Jan",
  "lastName":    "Peeters",
  "email":       "jan@peeters-nv.be",
  "companyName": "Peeters NV",
  "tel":         "32471234567",
  "VATNumber":   "BE0123456789",
  "address": {
    "city":        "Gent",
    "street":      "Korenmarkt",
    "houseNumber": "5",
    "zip":         "9000"
  }
}
201 Created
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "companyID":   "a3f8d2c1-...",
              "companyName": "Peeters NV",
              "email":       "jan@peeters-nv.be",
              "tel":         "32471234567",
              "VATNumber":   "BE0123456789",
              "status":      "REGISTERED",
              "createdTime": "2025-07-13T10:30:00Z",
              "address":     { ... }
            }
          }
409 Conflict
JSON · Foutrespons 
{
            "success": false,
            "error": {
              "code":    "COMPANY_EXISTS",
              "message": "A company with VAT number 'BE0123456789' already exists."
            }
          }

Endpoint 02

Bedrijven ophalen

GET /api/v1/partner/companies

Geeft een lijst terug van alle bedrijven die zijn aangemaakt onder uw partner-account. U ziet nooit bedrijven van andere partners.

De lijst is gesorteerd op aanmaakdatum, nieuwste eerst.

Query-parameter

includeJobsoptioneel boolean Standaard false. Zet op true om per bedrijf ook een jobs-array mee te sturen met alle vacatures van dat bedrijf — elke job met exact dezelfde velden als bij het apart ophalen van jobs.
Geen body nodig. Dit endpoint vereist alleen de authenticatie-headers. Er zijn geen request body-velden.

Voorbeeld — cURL

cURL 
curl "https://api.jobhopr.be/api/v1/partner/companies?includeJobs=true" \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons (met includeJobs=true) 
{
            "success": true,
            "data": [
              {
                "companyID":   "a3f8d2c1-...",
                "companyName": "Peeters NV",
                "email":       "jan@peeters-nv.be",
                "tel":         "32471234567",
                "VATNumber":   "BE0123456789",
                "status":      "REGISTERED",
                "createdTime": "2025-07-13T10:30:00Z",
                "address":     { ... },
                "jobs": [
                  {
                    "jobID": "b7e2a1f0-...",
                    // ... exact dezelfde velden als bij "Vacatures ophalen"
                  }
                ]
              },
              // ...
            ]
          }

Endpoint 03

Bedrijf ophalen

GET /api/v1/partner/companies/:companyID

Haalt de volledige gegevens op van één bedrijf via zijn ID. Het bedrijf moet aangemaakt zijn door uw partner-account. U kunt geen bedrijven van andere partners opvragen.

URL-parameter

companyIDvereist string (uuid) Unieke identifier van het bedrijf, verkregen via het endpoint "Bedrijf aanmaken".

Query-parameter

includeJobsoptioneel boolean Standaard false. Zet op true om ook een jobs-array mee te sturen met alle vacatures van dit bedrijf — elke job met exact dezelfde velden als bij het apart ophalen van jobs.

Voorbeeld — cURL

cURL 
curl "https://api.jobhopr.be/api/v1/partner/\
companies/a3f8d2c1-...?includeJobs=true" \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons (met includeJobs=true) 
{
            "success": true,
            "data": {
              "companyID":   "a3f8d2c1-...",
              "companyName": "Peeters NV",
              "email":       "jan@peeters-nv.be",
              "tel":         "32471234567",
              "VATNumber":   "BE0123456789",
              "status":      "REGISTERED",
              "createdTime": "2025-07-13T10:30:00Z",
              "address":     { ... },
              "jobs": [
                {
                  "jobID": "b7e2a1f0-...",
                  // ... exact dezelfde velden als bij "Vacatures ophalen"
                }
              ]
            }
          }
404 Not Found
JSON · Foutrespons 
{
              "success": false,
              "error": {
                "code":    "COMPANY_NOT_FOUND",
                "message": "No company found with
                        id '...' for this partner."
              }
            }

Endpoint 04

Bedrijf bijwerken

PATCH /api/v1/partner/companies/:companyID

Werkt de gegevens bij van een bestaand bedrijf. Stuur alleen de velden mee die u wilt wijzigen — velden die u weglaat blijven ongewijzigd.

Eigendomscontrole is van kracht: u kunt alleen bedrijven bijwerken die door uw partner-account zijn aangemaakt.

URL-parameter

companyIDvereist string (uuid) Unieke identifier van het te wijzigen bedrijf.

Body-velden (allemaal optioneel)

companyNameoptioneel string Nieuwe naam van het bedrijf.
emailoptioneel string Nieuw e-mailadres. Moet geldig formaat hebben. Wordt automatisch omgezet naar kleine letters.
teloptioneel string Nieuw Belgisch telefoonnummer. Zelfde formaten als bij aanmaken. Wordt automatisch genormaliseerd naar "32xxxxxxxxx".
addressoptioneel object Nieuw adres. Sub-velden: city, street, houseNumber, zip.

Voorbeeldverzoek

JSON · Request body 
PATCH /api/v1/partner/companies/a3f8d2c1-...
          {
            "tel": "32499876543"
          }
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "companyID":   "a3f8d2c1-...",
              "companyName": "Peeters NV",
              "email":       "jan@peeters-nv.be",
              "tel":         "32499876543",
              "VATNumber":   "BE0123456789",
              "status":      "REGISTERED",
              "createdTime": "2025-07-13T10:30:00Z",
              "address":     { ... }
              
            }
          }

Endpoint 05

Bedrijf verwijderen

DELETE /api/v1/partner/companies/:companyID

Verwijdert een bedrijf. Dit is een soft delete: het bedrijf wordt gemarkeerd met status DELETED en verdwijnt daarna uit alle overzichten (GET /companies) en is niet langer opvraagbaar via GET /companies/:companyID. De onderliggende data blijft bewaard, maar kan niet meer bijgewerkt worden.

Eigendomscontrole is van kracht: u kunt alleen bedrijven verwijderen die door uw partner-account zijn aangemaakt. Een reeds verwijderd bedrijf opnieuw verwijderen geeft een 404.

URL-parameter

companyIDvereist string (uuid) Unieke identifier van het te verwijderen bedrijf.

Voorbeeld — cURL

cURL 
curl -X DELETE https://api.jobhopr.be/api/v1/partner/\
companies/a3f8d2c1-... \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "companyID":   "a3f8d2c1-...",
              "companyName": "Peeters NV",
              "email":       "jan@peeters-nv.be",
              "tel":         "32499876543",
              "VATNumber":   "BE0123456789",
              "status":      "DELETED",
              "createdTime": "2025-07-13T10:30:00Z",
              "address":     { ... }
            }
          }
404 Not Found
JSON · Foutrespons 
{
            "success": false,
            "error": {
              "code":    "COMPANY_NOT_FOUND",
              "message": "No company found with
                      id '...' for this partner."
            }
          }

Endpoint 06

Vacature aanmaken

POST /api/v1/partner/companies/:companyID/jobs

Maakt een nieuwe vacature aan voor een bestaand bedrijf. Vervang :companyID in de URL door de companyID die u ontving bij het aanmaken van het bedrijf.

Een job is standaard meteen zichtbaar op het platform (status: "ONLINE"). Gebruik status: "PAUSE" om de vacature voorlopig te verbergen.

De respons bevat steeds alle gegevens van de vacature, dit geldt consistent voor elk job-endpoint (aanmaken, ophalen, bijwerken, verwijderen).

URL-parameter

companyIDvereist string (uuid) Unieke identifier van het bedrijf, verkregen via het endpoint "Bedrijf aanmaken".

Verplichte body-velden

titlevereist string Titel van de vacature, bv. "Frontend Developer".
descriptionvereist string Volledige functieomschrijving in platte tekst of HTML.
workTypevereist string Type werknemer. Toegestane waarden: "ARBEIDER", "BEDIENDE", "FLEXI", "STUDENT".
categoriesvereist array van strings
Eén of meerdere jobcategorieën voor matching, bv. ["ICT"]. Een enkele string (bv. "ICT") wordt ook aanvaard en automatisch als array van één element behandeld.
Toegestane waarden 
[
  "Administratie & Management",
  "Retail & Verkoop",
  "Commercieel & Sales",
  "Zorgsector",
  "Bouw",
  "Wetenschap & Onderzoek",
  "Facility & Onderhoud",
  "Horeca & Toerisme",
  "Creatief & Media",
  "ICT",
  "Techniek & Engineering",
  "Land- en tuinbouw",
  "Logistiek & Transport",
  "Ambacht",
  "Onderwijs",
  "Productie",
  "Andere"
]

Optionele body-velden

contractTypeoptioneel string Contractduur. Toegestane waarden: "VAST", "TIJDELIJK", "INTERIM".
statusoptioneel string Toegestane waarden: "ONLINE" (standaard) of "PAUSE".
addressoptioneel object Locatie van tewerkstelling. Sub-velden: city, street, houseNumber, zip. Weggelaten → adres van het bedrijf wordt gebruikt.
teloptioneel string Belgisch telefoonnummer voor de vacature. Zelfde formaten als bij bedrijf aanmaken. Weggelaten → telefoonnummer van het bedrijf wordt gebruikt.
jobLoonoptioneel object Looninfo als object met drie sub-velden:
· type (verplicht als jobLoon opgegeven): "bruto" of "netto"
· amount: positief getal of numeric string, bv. "3500"
· time: "uur", "dag", "week" of "maand"
searchRadiusoptioneel number Zoekradius in km voor kandidaatmatching, bv. 25.
redirectUrloptioneel string URL voor externe sollicitaties (external apply).

Voorbeeldverzoek

JSON · Request body 
POST /api/v1/partner/companies/a3f8d2c1-.../jobs

{
  "title":        "Frontend Developer",
  "description":  "Wij zoeken een gedreven
    Frontend Developer...",
  "workType":    "BEDIENDE",
  "contractType": "VAST",
  "categories":   ["ICT"],
  "status":       "ONLINE",
  "jobLoon": {
    "type":   "bruto",
    "amount": "3500",
    "time":   "maand"
  },
  "searchRadius": 25
}
201 Created
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "jobID":            "b7e2a1f0-...",
              "title":            "Frontend Developer",
              "description":      "Wij zoeken een gedreven...",
              "status":           "ONLINE",
              "categories":       ["ICT"],
              "contractType":     "VAST",
              "tel":              "32471234567",
              "workType":         "BEDIENDE",
              "searchRadius":     25,
              "redirectUrl":      null,
              "jobLoon": {
                "type":   "bruto",
                "amount": "3500",
                "time":   "maand"
              },
              "address":          { ... },
              "campaign":         null,
              "createdTime":      "2025-07-13T10:35:00Z",
              "updatedTime":      "2025-07-13T10:35:00Z"
            }
          }
404 Not Found
JSON · Foutrespons 
{
  "success": false,
  "error": {
    "code":    "COMPANY_NOT_FOUND",
    "message": "No company found with
             id '...' for this partner."
  }
}

Endpoint 07

Vacatures ophalen

GET /api/v1/partner/companies/:companyID/jobs

Geeft een lijst terug van alle vacatures die aangemaakt zijn voor een specifiek bedrijf. Het bedrijf moet eigendom zijn van uw partner-account.

Als het bedrijf niet bestaat of niet van u is, ontvangt u een 404-fout.

URL-parameter

companyIDvereist string (uuid) Unieke identifier van het bedrijf.

Respons-veld

campaign object of null De huidige campagne van de vacature, of null als er geen loopt. Bevat startTime, endTime en budget. Bestaat een campagne uit meerdere aaneensluitende periodes (bv. na een verlenging), dan worden die hier samengevoegd tot 1 campagne: startTime is de start van de eerste periode, endTime het einde van de laatste, budget de som van alle periodes.

Voorbeeld — cURL

cURL 
curl https://api.jobhopr.be/api/v1/partner/\
companies/a3f8d2c1-.../jobs \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": [
              {
                "jobID":            "b7e2a1f0-...",
                "title":            "Frontend Developer",
                "description":      "Wij zoeken een gedreven...",
                "status":           "ONLINE",
                "categories":       ["ICT"],
                "contractType":     "VAST",
                "tel":              "32471234567",
                "workType":         "BEDIENDE",
                "searchRadius":     25,
                "redirectUrl":      null,
                "jobLoon": {
                  "type":   "bruto",
                  "amount": "3500",
                  "time":   "maand"
                },
                "address":          { ... },
                "campaign": {
                  "startTime": "2026-08-27T00:00:00Z",
                  "endTime":   "2026-11-27T00:00:00Z",
                  "budget":    900
                },
                "createdTime":      "2025-07-13T10:35:00Z",
                "updatedTime":      "2025-07-13T10:35:00Z"
              },
              // ...
            ]
          }

Endpoint 08

Vacature ophalen

GET /api/v1/partner/companies/:companyID/jobs/:jobID

Haalt 1 specifieke vacature op. Zowel het bedrijf als de vacature moeten eigendom zijn van uw partner-account.

URL-parameters

companyIDvereist string (uuid) Unieke identifier van het bedrijf.
jobIDvereist string (uuid) Unieke identifier van de vacature.

Voorbeeld — cURL

cURL 
curl https://api.jobhopr.be/api/v1/partner/\
companies/a3f8d2c1-.../\
jobs/b7e2a1f0-... \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "jobID": "b7e2a1f0-...",
              // ... exact dezelfde velden als bij "Vacatures ophalen"
            }
          }
404 Not Found
JSON · Foutrespons 
{
  "success": false,
  "error": {
    "code":    "JOB_NOT_FOUND",
    "message": "No job found with id '...'
             for this company and partner."
  }
}

Endpoint 09

Vacature bijwerken

PATCH /api/v1/partner/companies/:companyID/jobs/:jobID

Werkt de gegevens bij van een bestaande vacature. Stuur alleen de velden mee die u wilt wijzigen — velden die u weglaat blijven ongewijzigd.

Zowel het bedrijf als de vacature moeten eigendom zijn van uw partner-account. Als een van beide niet gevonden wordt of niet van u is, ontvangt u een 404-fout.

URL-parameters

companyIDvereist string (uuid) Unieke identifier van het bedrijf.
jobIDvereist string (uuid) Unieke identifier van de vacature, verkregen bij het aanmaken.

Body-velden (allemaal optioneel)

titleoptioneel string Nieuwe titel van de vacature.
descriptionoptioneel string Nieuwe functieomschrijving.
statusoptioneel string Toegestane waarden: "ONLINE" of "PAUSE".
contractTypeoptioneel string Nieuwe contractduur. Toegestane waarden: "VAST", "TIJDELIJK", "INTERIM".
workTypeoptioneel string Toegestane waarden: "ARBEIDER", "BEDIENDE", "FLEXI", "STUDENT".
categoriesoptioneel array van strings Nieuwe jobcategorie(ën) — vervangt de volledige lijst. Zelfde toegestane waarden als bij aanmaken. Een enkele string wordt ook aanvaard.
teloptioneel string Belgisch telefoonnummer voor de vacature. Zelfde formaten als bij bedrijf aanmaken. Weggelaten → telefoonnummer van het bedrijf blijft ongewijzigd.
jobLoonoptioneel object Looninfo als object met drie sub-velden:
· type (verplicht als jobLoon opgegeven): "bruto" of "netto"
· amount: positief getal of numeric string, bv. "3800"
· time: "uur", "dag", "week" of "maand"
addressoptioneel object Nieuw werkadres. Sub-velden: city, street, houseNumber, zip.
redirectUrloptioneel string URL voor externe sollicitaties.

Voorbeeldverzoek

JSON · Request body 
PATCH /api/v1/partner/companies/a3f8d2c1-.../\
jobs/b7e2a1f0-...

{
  "status": "PAUSE",
  "jobLoon": {
    "type":   "bruto",
    "amount": "3800",
    "time":   "maand"
  }
}
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "jobID":            "b7e2a1f0-...",
              "title":            "Frontend Developer",
              "description":      "Wij zoeken een gedreven...",
              "status":           "PAUSE",
              "categories":       ["ICT"],
              "contractType":     "VAST",
              "tel":              "32471234567",
              "workType":         "BEDIENDE",
              "searchRadius":     25,
              "redirectUrl":      null,
              "jobLoon": {
                "type":   "bruto",
                "amount": "3800",
                "time":   "maand"
              },
              "address":          { ... },
              "campaign":         null,
              "createdTime":      "2025-07-13T10:35:00Z",
              "updatedTime":      "2025-07-13T11:02:00Z"
            }
          }
404 Not Found
JSON · Foutrespons 
{
            "success": false,
            "error": {
              "code":    "JOB_NOT_FOUND",
              "message": "No job found with id '...'
                      for this company and partner."
            }
          }

Endpoint 10

Vacature verwijderen

DELETE /api/v1/partner/companies/:companyID/jobs/:jobID

Verwijdert een vacature. Dit is een soft delete: de vacature wordt gemarkeerd met status DELETED en verdwijnt daarna uit alle overzichten (GET /companies/:companyID/jobs) en het platform. De onderliggende data blijft bewaard, maar kan niet meer bijgewerkt worden.

Zowel het bedrijf als de vacature moeten eigendom zijn van uw partner-account. Als een van beide niet gevonden wordt, niet van u is, of al verwijderd is, ontvangt u een 404-fout.

URL-parameters

companyIDvereist string (uuid) Unieke identifier van het bedrijf.
jobIDvereist string (uuid) Unieke identifier van de te verwijderen vacature.

Voorbeeld — cURL

cURL 
curl -X DELETE https://api.jobhopr.be/api/v1/partner/\
companies/a3f8d2c1-.../\
jobs/b7e2a1f0-... \
  -H "x-api-key: jhr_live_xxxxxxxxxxxxxxxx" \
  -H "x-partner-id: ff3ff042-..."
200 OK
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "jobID":            "b7e2a1f0-...",
              "title":            "Frontend Developer",
              "description":      "Wij zoeken een gedreven...",
              "status":           "DELETED",
              "categories":       ["ICT"],
              "contractType":     "VAST",
              "tel":              "32471234567",
              "workType":         "BEDIENDE",
              "searchRadius":     25,
              "redirectUrl":      null,
              "jobLoon": {
                "type":   "bruto",
                "amount": "3500",
                "time":   "maand"
              },
              "address":          { ... },
              "campaign":         null,
              "createdTime":      "2025-07-13T10:35:00Z",
              "updatedTime":      "2025-07-13T11:10:00Z"
            }
          }
404 Not Found
JSON · Foutrespons 
{
            "success": false,
            "error": {
              "code":    "JOB_NOT_FOUND",
              "message": "No job found with id '...'
                      for this company and partner."
            }
          }

Endpoint 11

Campagne starten

POST /api/v1/partner/companies/:companyID/jobs/:jobID/campaigns

Start een campagne voor een bestaande vacature, voor een periode in weken of maanden. Zowel het bedrijf als de vacature moeten eigendom zijn van uw partner-account.

Heeft de vacature al een lopende of aankomende campagne, dan wordt er geen nieuwe aangemaakt en ontvangt u een 409-fout.

URL-parameters

companyIDvereist string (uuid) Unieke identifier van het bedrijf.
jobIDvereist string (uuid) Unieke identifier van de vacature waarvoor de campagne gestart wordt.

Verplichte body-velden

periodUnitvereist string Toegestane waarden: "week" of "month".
periodvereist number Aantal weken of maanden. Bij periodUnit: "week" is dit een waarde van 2 tot 10. Bij periodUnit: "month" is dit een waarde van 1 tot 6.

Optionele body-velden

startTimeoptioneel string (ISO datum) Startdatum van de campagne, in het formaat "YYYY-MM-DD" (bv. "2026-09-01"), zonder tijdstip. Weggelaten → de campagne start onmiddellijk.

Voorbeeldverzoek

JSON · Request body 
POST /api/v1/partner/companies/a3f8d2c1-.../\
jobs/b7e2a1f0-.../campaigns

{
  "periodUnit": "month",
  "period":     3
}
201 Created
JSON · Succesrespons 
{
            "success": true,
            "data": {
              "jobID":      "b7e2a1f0-...",
              "periodUnit": "month",
              "period":     3,
              "totalPrice": 900,
              "startTime":  "2026-08-27T00:00:00Z",
              "endTime":    "2026-11-27T00:00:00Z"
            }
          }
400 Validation error
JSON · Foutrespons 
{
  "success": false,
  "error": {
    "code":    "VALIDATION_ERROR",
    "message": "'period' must be between
             1 and 6 when periodUnit is 'month'."
  }
}
409 Conflict
JSON · Foutrespons 
{
  "success": false,
  "error": {
    "code":    "CAMPAIGN_ALREADY_RUNNING",
    "message": "This job already has a running
             or upcoming campaign, from '...' to '...'."
  }
}

Referentie

Foutcodes

Elke foutrespons bevat een machineleesbare code en een leesbare message. Gebruik de code in uw foutafhandeling.

HTTP-status Code Betekenis
400 MISSING_FIELDS Eén of meerdere verplichte velden ontbreken in de request body.
400 VALIDATION_ERROR Een veld bevat een ongeldige waarde. Voorbeelden: ongeldige workType, ongeldige jobLoon.type/time, jobLoon.amount is geen positief getal, ongeldig e-mailformaat, of ongeldig Belgisch telefoonnummer.
400 INVALID_EMAIL Het opgegeven e-mailadres heeft geen geldig formaat.
400 INVALID_VAT_NUMBER Het BTW-nummer is ongeldig. Verwacht formaat: BE gevolgd door 10 cijfers.
401 UNAUTHORIZED De x-api-key-header ontbreekt of bevat een ongeldige waarde.
403 FORBIDDEN De x-partner-id-header ontbreekt, is onbekend of is uitgeschakeld.
404 COMPANY_NOT_FOUND Er bestaat geen bedrijf met de opgegeven companyID dat toebehoort aan uw partner-account, of het bedrijf is verwijderd.
404 JOB_NOT_FOUND Er bestaat geen vacature met de opgegeven jobID voor dit bedrijf en partner-account, of de vacature is verwijderd.
409 COMPANY_EXISTS Er bestaat al een bedrijf met dit BTW-nummer.
409 CAMPAIGN_ALREADY_RUNNING Deze vacature heeft al een lopende of aankomende campagne. Wacht tot die afgelopen is voor u een nieuwe start.
500 INTERNAL_ERROR Onverwachte fout aan serverzijde. Het Jobhopr-team wordt automatisch op de hoogte gebracht.
Hulp nodig? Neem contact op via info@jobhopr.be en vermeld uw partner-ID en een beschrijving van het probleem. We reageren binnen één werkdag.