Introduktion
API:et låter externa system interagera med rekryteringsprocesser, kandidatdata, organisationsstruktur med mera.
För fullständig teknisk referens om varje endpoint, inklusive alla parametrar, request/response-scheman och datatyper, se den fullständiga Swagger UI.
Autentisering
Alla anrop till API:et kräver autentisering. Det finns två metoder som stöds: Bearer Token (rekommenderas oftast) och Basic Authentication. Välj en av metoderna för varje anrop.
Metod 1: Bearer Token (Rekommenderad)
Hämta en Token: Anropa GET /Api/Auth/Token med era client och secret koder som query parametrar.
GET /Api/Auth/Token?client={your_client_code}&secret={your_secret_code}Använd Token: Svaret från /Api/Auth/Token är en sträng (token). Denna token ska inkluderas i Authorization-headern för alla efterföljande anrop, med prefixet "Bearer ".
Authorization: Bearer <token_string_from_step_1>
En token har begränsad giltighetstid och behöver sedan förnyas genom att upprepa steg 1.
Metod 2: Basic Authentication
Ni kan också autentisera genom att använda HTTP Basic Authentication direkt i varje anrop (förutom till /Api/Auth/Token).
Skapa Base64-sträng: Kombinera ert client (användarnamn) och secret (lösenord) med ett kolon emellan (client:secret) och Base64-koda resultatet.
Exempel: Om client är mitt_client_id och secret är mitt_hemliga_lösenord, blir strängen mitt_client_id:mitt_hemliga_lösenord. Base64-kodningen av detta blir (exempelvis) bWl0dF9jbGllbnRfaWQ6bWl0dF9oZW1saWdhX2zDtnNlbm9yZA==.
(Verifiera detta: Kontrollera med Visma om det verkligen är client och secret som ska användas som användarnamn/lösenord för Basic Auth).
Använd Header: Inkludera den Base64-kodade strängen i Authorization-headern med prefixet "Basic ".
Authorization: Basic <base64_encoded_client:secret_string>
Denna header måste skickas med varje API-anrop som kräver autentisering.
1. Arkivering
Syfte: Hämta information om avslutade rekryteringsprocesser, anställningar och kandidater för arkiveringsändamål.
Relevanta Endpoints:
GET /Api/Applications/Hired: Hämtar anställda kandidater inom ett visst tidsintervall (t.ex. för att arkivera data om nyligen anställda).
Notera: Använd hiredFrom och hiredTo parametrar.
GET /Api/Applications/{id}: Hämtar detaljerad information om en specifik ansökan via dess ID.
GET /Api/Applications/CollectedCandidateInformation: Hämtar specifik insamlad kandidatinformation för en ansökan (kan vara relevant för arkivering av viss data).
GET /Api/Applications/{id}/Document/{documentId}: Hämtar specifika dokument (t.ex. CV, personligt brev) kopplade till en ansökan för arkivering.
GET /Api/Assignments: Hämtar en lista över uppdrag (annonser/rekryteringar). Kan filtreras på status (t.ex. Completed_Recruited, Completed_Cancelled) och datumintervall för att hitta avslutade annonser.
GET /Api/Assignments/{id}: Hämtar detaljerad information om en specifik annons.
GET /Api/Assignments/{id}/AsPDF: Hämtar hela annonsen som PDF.
GET /Api/HiringCases: Hämtar en lista över ärenden. Kan filtreras på datum för att hitta äldre/avslutade ärenden.
GET /Api/HiringCases/{id}: Hämtar detaljerad information om ett specifikt avslutat ärende.
GET /Api/HiringCases/{id}/RequirementsProfileAsPdf: Hämtar kravprofilen för ett ärende som PDF.
2. Annonslista
Syfte: Hämta information om publicerade och aktiva jobbannonser för att visa dem i ett externt system (t.ex. en karriärsida eller intranät).
Relevanta Endpoints:
GET /Api/Assignments: Hämtar en lista över annonser. Detta är den primära endpointen. Använd parametrar för att filtrera:
assignmentStatusIdFrom: Sätt till Published för att endast få publicerade annonser.
publishStartDateTo, applicationEndDateFrom: För att filtrera på relevanta datum.
hiringCaseId: Om du vill lista annonser för ett specifikt ärende.
GET /Api/Assignments/{id}: Hämtar fullständiga detaljer för en specifik annons baserat på dess ID (hämtat från listan ovan). Detta inkluderar beskrivningar, kvalifikationer, kontaktpersoner etc.
GET /Api/Departments: Kan användas för att hämta en lista över avdelningar, om annonslistan ska kunna filtreras per avdelning i det externa systemet.
GET /Api/HiringCases/{id}: Kan användas för att hämta information om det övergripande ärendet som en annons tillhör, om den kontexten behövs.
3. Onboarding
Syfte: Hämta data om en kandidat som har blivit anställd för att initiera onboarding-processen i ett annat system (t.ex. HR- eller lönesystem).
Relevanta Endpoints:
GET /Api/Applications/Hired: Hämtar en lista över anställda kandidater, ofta filtrerat på ett snävt datumintervall (hiredFrom, hiredTo) för att få de senaste anställningarna. Detta är startpunkten.
GET /Api/Applications/{id}: Hämtar detaljer för en specifik anställd kandidat (ID fås från listan ovan). Innehåller CV-data och referenser till dokument.
GET /Api/Applications/CollectedCandidateInformation: Hämtar eventuell ytterligare specifik information som samlats in om kandidaten under processen via dynamiska fält.
GET /Api/Applications/{id}/Document/{documentId}: Hämtar dokument som CV, intyg, personligt brev etc., baserat på dokument-ID från ansökan.
GET /Api/Assignments/{id}: Hämtar information om annonsen som kandidaten ansökte till (ID fås från ansökan).
GET /Api/HiringCases/{id}: Hämtar information om ärendet som ledde till anställningen (ID fås från annonsen).
4. Synkronisering av organisation och användare
Syfte: Synkronisera organisationsstruktur (konton, avdelningar) och användare mellan Visma Recruit och ett externt system (t.ex. AD, HR-system). Notera: Hantering av kundkonton på högsta nivå sker ofta separat från den löpande synkroniseringen av avdelningar och användare inom ett konto.
Relevanta Endpoints:
Konton (Accounts - inom ramen för synk):
GET /Api/Accounts/{id}/AccessGroups: Hämtar behörighetsgrupper för ett specifikt konto (kan behövas för kontext vid synkning av användare inom det kontot).
POST /Api/Accounts/{id}/SyncRecruiters: Synkroniserar en lista av användare mot ett specifikt konto (skapar/uppdaterar/tar bort baserat på RemoteId). Detta är ofta effektivare än enskilda POST/PUT/DELETE för användare.
POST /Api/Accounts/{id}/SimulateSyncRecruiters: Simulerar en synkronisering för ett specifikt konto.
Avdelningar (Departments):
GET /Api/Departments: Listar avdelningar.
POST /Api/Departments: Skapar en ny avdelning.
GET /Api/Departments/{id}: Hämtar detaljer för en specifik avdelning.
PUT /Api/Departments/{id}: Uppdaterar en befintlig avdelning.
DELETE /Api/Departments/{id}: Tar bort en avdelning.
GET /Api/Departments/{id}/ContactPersons: Hämtar kontaktpersoner för en avdelning.
POST /Api/Departments/{id}/ContactPersons: Skapar en kontaktperson.
GET /Api/Departments/{id}/MainProcesses: Hämtar processer kopplade till en avdelning.
GET /Api/Departments/{id}/DynamicField: Hämtar dynamiska fält för en avdelning.
POST/Api/Departments/{id}/DynamicField: Skapar ett dynamiskt fält.
DELETE /Api/Departments/{id}/DynamicField/{dynamicFieldId}: Tar bort ett dynamiskt fält.
Användare (Recruiters - oftast via SyncRecruiters, men enskilda anrop finns):
GET /Api/Recruiters: Listar användare (kan filtreras på avdelning).
POST /Api/Recruiters: Skapar en ny användare.
GET /Api/Recruiters/{id}: Hämtar detaljer för en specifik användare.
PUT /Api/Recruiters/{id}: Uppdaterar en befintlig användare.
DELETE /Api/Recruiters/{id}: Tar bort (inaktiverar oftast) en användare.
GET /Api/Recruiters/{id}/AccessGroups: Hämtar rättighetsgrupper för en användare.
POST /Api/Recruiters/{id}/AccessGroups: Kopplar en rättighetsgrupp till en användare.
5. Skapa ärende
Syfte: Skapa ett nytt ärende och eventuellt en tillhörande annons från ett externt system.
Relevanta Endpoints:
POST /Api/HiringCases: Skapar ett nytt ärende. Detta är den centrala endpointen för detta use case. Kräver information som ansvarig rekryterare, avdelning, titel, antal jobb etc.
Beroenden: Du kan behöva hämta ID:n först via:
GET /Api/Departments: För att få departmentId.
GET /Api/Departments/{id}/MainProcesses: För att få mainProcessId.
GET /Api/Recruiters: För att få ID för responsibleRecruiter och eventuella additionalRecruiters.
POST /Api/Assignments: Skapar en ny annons som kopplas till ett ärende (via hiringCaseId). Detta görs ofta i samband med eller efter att ärendet skapats.
Beroenden: Kräver hiringCaseId från det skapade ärendet. Kan också kräva ID:n för kontaktpersoner:
GET /Api/Departments/{id}/ContactPersons: För att få ID:n till kontaktpersoner.
PUT /Api/HiringCases/{id}: Kan användas för att uppdatera ärendet efter att det skapats (t.ex. lägga till mer information).
PUT /Api/Assignments/{id}: Kan användas för att uppdatera annonsen efter att den skapats.
GET /Api/HiringCases/{id}: Kan användas för att verifiera att ärendet skapades korrekt och hämta dess ID och detaljer.
GET /Api/Assignments/{id}: Kan användas för att verifiera att annonsen skapades korrekt.