Logo trimoji
Try for free

Hardskills API

Trimoji Resume API Documentation

Last updated: May 22, 2024

This API allows you to parse CVs, create ideal candidate profiles (called "Personi"), and score CVs against these profiles to optimize your recruitment process.

Configuration

Configure Your Variables

Before using this API, please configure the following variables:

  • base_url: The base URL of the API (e.g., https://integration.trimoji.fr/api/v1/resume).
  • partner_token: Your unique partner authentication token.
  • customer_token: Your customer-specific API key. You can obtain it from the Trimoji Panel by clicking the "copy my API key" button.

Security

Authentication

All API requests must include an Authorization header containing your partner_token.

Authorization: your_partner_token_here

Asynchronous

Callback Mechanism (Webhook)

Several operations, such as CV uploads, are asynchronous. When processing is complete, Trimoji will send the results to the callback_url you provided.

Callback on Success

The data sent to your callback_url upon successful parsing will follow this JSON structure:


{
  "metadatas": {
    "your_key": "custom_value"
  },
  "resumeData": {
    "firstname": "string",
    "lastname": "string",
    "email": "string",
    "phone": "string",
    "sex": "string ('f', 'm', or '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 on Failure

If the CV processing fails, a callback will be sent containing error details and processing logs.


{
  "metadatas": {
    "uid": "user123",
    "source": "webapp"
  },
  "error": {
    "code": "PROCESSING_FAILED",
    "message": "Failed to extract data from the provided file due to invalid format."
  },
  "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."
  ]
}

CV Parsing

CV Parsing API

1. Upload a CV

Send a CV file for asynchronous parsing. Results will be sent to the callback_url.

POST /upload

Body Parameters (form-data)

Key Type Description
customer_token * Text Your customer API key.
uploaded_file * File CV file. Max size: 5MB. Allowed extensions: pdf, docx, png, jpg, jpeg, txt, webp, doc, rtf, pptx, otp, odp, odt.
callback_url Text URL to receive asynchronous results.
metadatas Text Custom JSON string for tracking.
personi_id Text Optional Personi ID to link the CV.
Example Response

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

2. Retrieve CV Info

Get the parsed information of a CV using its resume_id.

GET /get/{customer_token}/{resume_id}

Example Response

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

3. Retrieve Process Logs

Get the processing logs for a specific CV, useful for debugging parsing issues.

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

4. Delete a CV

Marks a CV as deleted (soft delete).

DELETE /delete/{customer_token}/{resume_id}

Personi & Scoring

Personi & Scoring API

A "Personi" is an ideal candidate profile, defined in JSON format, against which CVs can be scored.

1. Create a Personi

Creates a new ideal candidate profile. You can provide detailed criteria manually, or use the auto_weights and auto_keywords flags to let our AI generate them based on the job description.

POST /personi/create

Body Parameters (JSON)

Key Type Description
customer_token * String Your customer API key.
custom_id * String A unique ID for the Personi within your system.
position * String The job title.
position_description * String Detailed description of the role.
company_description * String Description of the company.
sector * String The industry sector of the position.
company String The company name.
diploma String Minimum required education level.
telework String Remote work policy. Values: FLEXIBLE, FULLTIME, HYBRID, NEVER, OCCASIONAL, ONDEMAND, PARTTIME, ROTATION.
education_weight Number Weight for education score (0-100).
experience_weight Number Weight for experience score (0-100).
skills_weight Number Weight for skills score (0-100).
knowledge_weight Number Weight for knowledge score (0-100).
keywords_weight Number Weight for keywords score (0-100).
geolocation Object Location criteria: {"address": "string", "radius": number}. Radius in km (defaults to 10).
keywords Array Manual keywords: [{"word": "string", "is_mandatory": boolean}].
languages Array Language requirements: [{"id": "iso_code", "level": "A1-C2"}]. Levels: A1, A2, B1, B2, C1, C2.
driving_licenses Array Required driver's licenses, e.g., ["B", "C1"].
auto_keywords Boolean Set to true to automatically generate keywords.
auto_weights Boolean Set to true to automatically set weights.

Note on Weights: If using manual weights, the sum of all *_weight fields must equal exactly 100. If no weights are provided and auto_weights is false, a default distribution will be used.

Request Examples

Automatic Generation (AI)


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

Manual Configuration


{
    "custom_id": "SENIOR_DEV_002",
    "customer_token": "your_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 }
}
Example Response

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

2. Retrieve All Personis

Get a list of all active Personis for your customer account. If multiple Personis share the same custom_id, only the most recently updated one is returned.

GET /get/{customer_token}/personi/all

Example Response

{
    "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. Retrieve Personi Details

Get the full configuration and details of a specific Personi.

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

Example Response

{
    "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": "English", "is_mandatory": true } ],
            "skills": [ { "skill": "active_listening", "value": 72 } ]
        }
    }
}

4. Score a CV against a Personi

Calculate the score of a specific CV against a specific Personi. Optionally returns an HTML explanation of the score.

POST /matching

Body Parameters (JSON)

Key Type Description
resume_id * String ID of the CV to score.
personi_id * String or Array ID of the Personi(s) to score against.
explainer String Returns the score explanation. Values: 'en', 'fr', 'es'.
Example Response (Standard)

{
    "success": true,
    "message": "Success",
    "data": {
        "score": 60,
        "personi_name": "Developer at Trimoji"
    }
}

5. Score a CV against all Personis

Calculates the score of a CV against all active Personis in your account, returning a sorted list of top matches.

POST /matchingAll

Body Parameters (JSON)

Key Type Description
resume_id * String ID of the CV to score.
customer_token * String Your customer API key.
limit Integer Maximum number of results (default 100).
Example Response

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

6. Score all CVs against a Personi

Calculates the score of all active CVs in your account against a single Personi.

POST /matchingAllResumes

Body Parameters (JSON)

Key Type Description
customer_token * String Your customer API key.
personi_id * String ID of the Personi to score against.
limit Integer Maximum number of CVs to score.
Example Response

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

7. Delete a Personi

Marks a Personi as deleted (soft delete).

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

Back to Integrations
Top