Documentazione API Trimoji Resume

Ultimo aggiornamento: 22 Maggio 2024

Questa API consente di analizzare (parsing) CV, creare profili di candidati ideali (chiamati "Personi") e valutare i CV rispetto a questi profili per ottimizzare il Suo processo di recruiting.

Configurazione

Configurazione delle Sue variabili

Prima di utilizzare questa API, La preghiamo di configurare le seguenti variabili:

base_url : L'URL di base dell'API (es: https://integration.trimoji.fr/api/v1/resume).
partner_token : Il Suo token di autenticazione partner unico.
customer_token : La Sua chiave API specifica per il cliente. La può ottenere dal Panel Trimoji cliccando sul pulsante "copia la mia chiave API".

Sicurezza

Autenticazione

Tutte le richieste API devono includere un header Authorization contenente il Suo partner_token.

Authorization: il_tuo_partner_token_qui

Asincrono

Meccanismo di Callback (Webhook)

Diverse operazioni, come l'upload di CV, sono asincrone. Al termine dell'elaborazione, Trimoji invierà i risultati all'URL callback_url da Lei fornito.

Callback in caso di Successo

I dati inviati al Suo callback_url durante un parsing riuscito seguiranno questa struttura JSON:


{
  "metadatas": {
    "la_tua_chiave": "valore_personalizzato"
  },
  "resumeData": {
    "firstname": "string",
    "lastname": "string",
    "email": "string",
    "phone": "string",
    "sex": "string ('f', 'm', o 'other')",
    "age": "integer | null",
    "introduction": "string | null",
    "address": "string | null",
    "lat": "number | null",
    "lon": "number | null",
    "processed_at": "datetime_string"
  },
  "experiences": [
    {
      "poste": "string",
      "company": "string",
      "size": "string | null ('AE', 'MIE', 'TPE', ...)",
      "start_date": "integer | null",
      "end_date": "integer | null",
      "duration": "integer | null",
      "tasks": ["string"]
    }
  ],
  "diplomas": [
    { "name": "string", "date": "integer | null" }
  ],
  "licenses": [
    { "name": "string", "desc": "string" }
  ],
  "languages": [
    { "name": "string (iso_code)", "level": "string" }
  ],
  "hobbies": ["string"],
  "telework": "string | null ('Flexible', 'Full time', ...)"
}

Callback in caso di Fallimento

Se l'elaborazione del CV fallisce, verrà inviato un callback contenente i dettagli dell'errore e i log di elaborazione.


{
  "metadatas": {
    "uid": "user123",
    "source": "webapp"
  },
  "error": {
    "code": "PROCESSING_FAILED",
    "message": "Estrazione dati dal file fornito fallita a causa di formato non valido."
  },
  "logs": [
    "[2024-05-21T10:00:05.123Z] [FILE_UPLOAD] [OK] File uploaded successfully.",
    "[2024-05-21T10:00:06.456Z] [PROCESS_STARTED] [OK] Processing started.",
    "[2024-05-21T10:00:15.789Z] [DATA_STRUCTURE_GENERATION] [ERROR] AI model returned an invalid structure."
  ]
}

Parsing CV

API Parsing CV

1. Caricare un CV

Invia un file CV per un parsing asincrono. I risultati verranno inviati al callback_url.

POST /upload

Parametri del Body (form-data)

Chiave	Tipo	Descrizione
`customer_token` *	Testo	La Sua chiave API cliente.
`uploaded_file` *	File	File del CV. Dimensione massima: 5MB. Estensioni consentite: pdf, docx, png, jpg, jpeg, txt, webp, doc, rtf, pptx, otp, odp, odt.
`callback_url`	Testo	URL per ricevere i risultati asincroni.
`metadatas`	Testo	Stringa JSON personalizzata per il tracciamento.
`personi_id`	Testo	ID opzionale di un Personi per collegare il CV.

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": {
        "resume_id": "6ff7d7fe-8e53-4ddf-b68a-f9d4658f5bc8"
    }
}

2. Recuperare le informazioni del CV

Recupera le informazioni analizzate di un CV utilizzando il suo resume_id.

GET /get/{customer_token}/{resume_id}

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": {
        "resumeData": {
            "firstname": "Lou",
            "lastname": "Pagès",
            "email": "[email protected]",
            "age": 22
        },
        "experiences": [ ... ],
        "diplomas": [ ... ]
    }
}

3. Recuperare i Log del processo

Recupera i log di elaborazione per un CV specifico, utile per il debug dei problemi di parsing.

GET /get/{customer_token}/{resume_id}/logs

4. Eliminare un CV

Marca un CV come eliminato (eliminazione logica / soft delete).

DELETE /delete/{customer_token}/{resume_id}

Personi & Scoring

API Personi & Scoring

Un "Personi" è un profilo di candidato ideale, definito in formato JSON, rispetto al quale i CV possono essere valutati.

1. Creare un Personi

Crea un nuovo profilo di candidato ideale. Può fornire criteri dettagliati manualmente, o utilizzare le flag auto_weights e auto_keywords per lasciare che la nostra IA li generi in base alla descrizione della posizione.

POST /personi/create

Parametri del Body (JSON)

Chiave	Tipo	Descrizione
`customer_token` *	String	La Sua chiave API cliente.
`custom_id` *	String	Un ID unico per il Personi nel Suo sistema.
`position` *	String	Il titolo della posizione.
`position_description` *	String	Descrizione dettagliata del ruolo.
`company_description` *	String	Descrizione dell'azienda.
`sector` *	String	Il settore di attività della posizione.
`company`	String	Il nome dell'azienda.
`diploma`	String	Livello di diploma minimo richiesto.
`telework`	String	Politica di smart working. Valori: `FLEXIBLE`, `FULLTIME`, `HYBRID`, `NEVER`, `OCCASIONAL`, `ONDEMAND`, `PARTTIME`, `ROTATION`.
`education_weight`	Number	Peso per il punteggio di istruzione (0-100).
`experience_weight`	Number	Peso per il punteggio di esperienza (0-100).
`skills_weight`	Number	Peso per il punteggio di competenze (0-100).
`knowledge_weight`	Number	Peso per il punteggio di conoscenze (0-100).
`keywords_weight`	Number	Peso per il punteggio di parole chiave (0-100).
`geolocation`	Object	Criteri di luogo: `{"address": "string", "radius": number}`. Raggio in km (default 10).
`keywords`	Array	Parole chiave manuali: `[{"word": "string", "is_mandatory": boolean}]`.
`languages`	Array	Requisiti linguistici: `[{"id": "iso_code", "level": "A1-C2"}]`. Livelli: `A1, A2, B1, B2, C1, C2`.
`driving_licenses`	Array	Patenti di guida richieste, es: `["B", "C1"]`.
`auto_keywords`	Boolean	Impostare a `true` per generare automaticamente le parole chiave.
`auto_weights`	Boolean	Impostare a `true` per definire automaticamente i pesi.

Nota sui Pesi: Se si utilizzano pesi manuali, la somma di tutti i campi *_weight deve essere esattamente 100. Se non vengono forniti pesi e auto_weights è falso, viene utilizzata una distribuzione predefinita.

Esempi di Richieste

Generazione Automatica (IA)


{
    "custom_id": "MKT_ASSIST_001",
    "customer_token": "il_tuo_token",
    "position": "Junior Marketing Assistant",
    "position_description": "We are looking for...",
    "company_description": "Innovate Corp...",
    "sector": "Marketing",
    "auto_keywords": true,
    "auto_weights": true
}

Configurazione Manuale


{
    "custom_id": "SENIOR_DEV_002",
    "customer_token": "il_tuo_token",
    "position": "Senior Software Engineer",
    "position_description": "Seeking experienced...",
    "company": "Tech Solutions",
    "telework": "HYBRID",
    "education_weight": 10,
    "experience_weight": 40,
    "skills_weight": 20,
    "knowledge_weight": 10,
    "keywords_weight": 20,
    "keywords": [
        {"word": "Spring Boot", "is_mandatory": true}
    ],
    "geolocation": { "address": "Paris", "radius": 20 }
}

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": {
        "personi_id": "f8e1e2c3-6337-4644-9fbf-7e382d089e3d"
    }
}

2. Recuperare tutti i Personi

Recupera l'elenco di tutti i Personi attivi per il Suo account cliente. Se più Personi condividono lo stesso custom_id, viene restituito solo quello aggiornato più di recente.

GET /get/{customer_token}/personi/all

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "id": "f8e1e2c3...",
            "custom_id": "SENIOR_DEV_002",
            "name": "Senior Software Engineer Profile",
            "created_at": "2024-05-15T10:00:00.000Z"
        }
    ]
}

3. Recuperare i dettagli di un Personi

Recupera la configurazione completa e i dettagli di un Personi specifico.

GET /get/{customer_token}/personi/details/{personi_id}

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": {
        "id": "5e0273f8-8cfd-4673-9a89-3f4c934d3391",
        "name": "Associate Product Manager | London",
        "matching_settings": {
            "weights": { "percent_experience": 44, "percent_hardskills": 19 },
            "languages": [ { "lang": "Inglese", "is_mandatory": true } ],
            "skills": [ { "skill": "active_listening", "value": 72 } ]
        }
    }
}

4. Valutare un CV rispetto a un Personi

Calcola il punteggio di un CV specifico rispetto a un Personi specifico. Restituisce opzionalmente una spiegazione HTML del punteggio.

POST /matching

Parametri del Body (JSON)

Chiave	Tipo	Descrizione
`resume_id` *	String	ID del CV da valutare.
`personi_id` *	String o Array	ID del/dei Personi rispetto al/ai quale/i valutare.
`explainer`	String	Restituisce la spiegazione del punteggio. Valori: 'en', 'fr', 'es'.

Esempio di Risposta (Standard)


{
    "success": true,
    "message": "Success",
    "data": {
        "score": 60,
        "personi_name": "Sviluppatore presso Trimoji"
    }
}

5. Valutare tutti i CV rispetto a un Personi

Calcola il punteggio di tutti i CV attivi nel Suo account rispetto a un unico Personi, restituendo un elenco ordinato delle migliori corrispondenze.

POST /matchingAll

Parametri del Body (JSON)

Chiave	Tipo	Descrizione
`resume_id` *	String	ID del CV da valutare.
`customer_token` *	String	La Sua chiave API cliente.
`limit`	Integer	Numero massimo di risultati (default 100).

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "personi_id": "839d2953...",
            "personi_name": "SENIOR HR BUSINESS PARTNER...",
            "score": 100
        }
    ]
}

6. Valutare tutti i CV contro un Personi

Calcola il punteggio di tutti i CV attivi nel Suo account rispetto a un unico Personi.

POST /matchingAllResumes

Parametri del Body (JSON)

Chiave	Tipo	Descrizione
`customer_token` *	String	La Sua chiave API cliente.
`personi_id` *	String	ID del Personi rispetto al quale valutare.
`limit`	Integer	Numero massimo di CV da valutare.

Esempio di Risposta


{
    "success": true,
    "message": "Success",
    "data": [
        {
            "resume_id": "ac4d685e-c8e4-474d-a92a-16758009fafe",
            "score": 100
        },
        {
            "resume_id": "602d7fc9-2b85-4064-9ae6-ad5be08d5bcb",
            "score": 95
        }
    ]
}

7. Eliminare un Personi

Marca un Personi come eliminato (eliminazione logica / soft delete).

DELETE /delete/{customer_token}/personi/{personi_id}