Per gli sviluppatori
Collega il tuo HRIS e il tuo ATS a Paritir
L’API di integrazione permette ai tuoi sistemi di inviare a Paritir, a cadenza regolare, i dati dei dipendenti e degli annunci di lavoro. Così l’analisi del divario retributivo lavora su dati aggiornati, senza import CSV manuali. È pensata per chi realizza l’integrazione: una società di consulenza, l’IT del cliente o gli ingegneri di Paritir.
Cosa fa
Tre compiti, una API
Dipendenti in lotti
Invia i dati dei dipendenti in lotti. Paritir abbina ogni record al tuo ID esterno, altrimenti all’email, aggiorna ciò che è cambiato e ne ricava lo storico di retribuzioni e ruoli. Lo storico non lo invii mai tu.
Mappa i campi una volta
Invia qualche riga di esempio e Paritir propone come abbinare i campi del tuo HRIS ai propri. Una persona conferma la mappatura una volta e viene salvata come profilo di origine. Le sincronizzazioni successive la applicano così com’è e trattengono un lotto se la struttura della tua origine cambia.
Entrano gli annunci, esce la conformità
Invia gli annunci di lavoro dal tuo ATS. Paritir controlla ciascuno rispetto alle regole sulla trasparenza retributiva del paese della tua sede, e puoi rileggere il risultato per ogni annuncio.
Accesso
OAuth 2.0, limitato a una organizzazione
Client credentials
Il tuo sistema scambia un client ID e un secret con un token di accesso. I token durano 15 minuti; alla scadenza ne chiedi uno nuovo. Non esistono chiavi API statiche.
Una organizzazione per credenziale
Un token legge e scrive solo nell’organizzazione che ha emesso la sua credenziale. L’organizzazione deriva dalla credenziale, mai dalla richiesta.
Solo gli scope concessi
Ogni credenziale porta gli scope scelti alla creazione, come scrivere dipendenti o leggere annunci. Una chiamata al di fuori viene rifiutata.
Create e revocate nell’app
L’Owner o un Admin dell’organizzazione crea le credenziali in Impostazioni → Integrazioni. Il secret viene mostrato una sola volta e conservato solo come hash. Revocare una credenziale blocca subito i suoi token.
Ottieni un token, poi invia un lotto
POST https://app.paritir.com/v1/oauth/token
Content-Type: application/json
{ "grant_type": "client_credentials",
"client_id": "ptir_…", "client_secret": "…" }
→ { "access_token": "…", "token_type": "Bearer",
"expires_in": 900, "scope": "workforce:write" }POST https://app.paritir.com/v1/employees:batch
Authorization: Bearer …
Idempotency-Key: …
Content-Type: application/json
{ "employees": [
{ "external_id": "E-1042", "full_name": "…", "email": "…" }
] }
→ { "sync_run_id": "…", "inserted": 1, "updated": 0,
"unchanged": 0, "errors": 0, … }Riferimento
Gli endpoint attivi oggi
Richieste e risposte sono in JSON. Ogni chiamata viene registrata per la tua organizzazione.
URL di base https://app.paritir.com/v1
| Metodo | Percorso | Scope | A cosa serve |
|---|---|---|---|
| POST | /oauth/token | — | Scambiare le client credentials con un token di accesso da 15 minuti. |
| POST | /employees:batch | workforce:write | Creare o aggiornare dipendenti in un lotto. |
| POST | /employees:map-preview | workforce:write | Proporre una mappatura dei campi da righe di esempio. Non scrive nulla. |
| POST | /postings:batch | postings:write | Creare o aggiornare annunci di lavoro in un lotto. |
| GET | /postings | postings:read | Elencare gli annunci con il risultato di conformità, dai più recenti. |
| GET | /postings/{posting_reference} | postings:read | Leggere un annuncio tramite il tuo riferimento. |
Reinvio sicuro
Invia un header Idempotency-Key con ogni lotto. La stessa chiave restituisce il primo risultato senza scrivere di nuovo; se l’elaborazione è ancora in corso, la risposta è HTTP 409.
Paginazione e filtri
L’elenco degli annunci si pagina con limit e un cursor opaco e si filtra per status e per updated_since.
Errori e limiti
Gli errori arrivano in JSON con un messaggio. La validazione indica i campi in errore e non ripete mai i valori inviati. Le chiamate sono limitate per organizzazione; oltre il limite la risposta è HTTP 429.
Stato
Cosa l’API non fa ancora
L’API porta dentro i dati e fuori gli annunci di lavoro. Risultati sul divario retributivo, relazioni e valutazioni congiunte delle retribuzioni restano per ora nell’app. Non ci sono ancora webhook né un ambiente sandbox: una nuova integrazione si configura quindi su un’organizzazione reale, con il nostro aiuto.
L’accesso all’API arriva con un account
Paritir è accessibile solo su invito mentre lavoriamo con i primi clienti e le prime società di consulenza. Una volta configurata la tua organizzazione, l’Owner o un Admin può creare le credenziali API.