Candidates (sub-entities): Managing Candidate Companies, Project Experience, Candidate Pools, Dialogue Emails, and CV Parsing via the API

In this article, you can read about how to link and unlink companies on a candidate, manage a candidate's project experience entries, add or remove candidates from candidate pools, bulk actions with candidate attributes, log or queue candidate emails via candidate dialogue, and trigger AI-based CV parsing on an uploaded candidate file.

Candidate Companies

You can link one or more companies to a candidate or remove that link using thecandidateCompany scope. To insert companies, use the POST method. The operation must be set to insert and scope to candidateCompany.

When inserting new companies, the field candidateId and the array of integers companyIds are required.

POST

https://api.recman.io/v2/post/

{
  "key": "{{api_key}}",
  "scope": "candidateCompany",
  "operation": "insert",
  "data": {
    "candidateId": 2030141,
    "companyIds": [423645, 423646]
  }
}

To remove companies, use the same field structure with "operation": "delete".

PARAMS

Candidate Project Experience

Project experience entries (separate from work experience) can be inserted, updated or deleted individually using the candidateProjectExperience scope.

POST

{
  "key": "{{api_key}}",
  "scope": "candidateProjectExperience",
  "operation": "insert",
  "data": {
    "candidateId": 2856682,
    "name": "Project example",
    "url": "www.recman.no",
    "description": "Project description",
    "fromDate": "2012-05-01",
    "toDate": "2022-11-16"
  }
}

To update/delete an entry, use:"operation": "update" or "operation": "delete". You must provide a projectExperienceId.

PARAMS

Candidate Pools

Candidate pools group candidates together (e.g., "New candidates for job post"). 

Use the candidatePool scope to retrieve a pool's contents or manage its members.

Retrieve a Candidate Pool

Retrieving data about candidate pools is done through the GET method.

You can request a list of all candidate pools or retrieve a specific candidate pool.

To get candidate IDs within a pool, specify the candidatePoolId parameter. This means that you can get candidate IDs only within a specific pool, not with a pool list.

GET

https://api.recman.io/v2/get/?key={{api_key}}
&scope=candidatePool&candidatePoolId=436235

PARAMS

Add or Remove Candidates

POST

{
  "key": "{{api_key}}",
  "scope": "candidatePool",
  "operation": "insert",
  "data": {
    "candidatePoolId": 436235,
    "candidateIds": [123456, 321435, 442214]
  }
}

To remove candidates from a pool, use the same structure with "operation": "delete".

PARAMS

Candidate Attributes

The candidateAttribute scope lets you insert, update, and delete candidate attributes in bulk. Each request operates on a single candidateId and processes up to 50 attributes in one call.

Attribute values are validated dynamically based on the attribute configuration stored in the system settings. The API supports multiple attribute types, including boolean, rating, text, single-line text, dropdown, date, and checkbox (with an optional per-checkbox rating).

Root Body

Attributes

Rating Checkbox

POST Bulk Insert

{
  "key": "{{api_key}}",
  "scope": "candidateAttribute",
  "operation": "insert",
  "data": {
    "candidateId": 2053160,
    "attributes": [
      {
        "attributeId": 6174,
        "checkboxIds": [
          {"id": 7421, "rating": 1},
          {"id": 7420, "rating": 1}
        ]
      },
      {
        "attributeId": 6358,
        "boolean": 1,
        "rating": 5,
        "checkboxIds": [7821, 7822],
        "text": "test data",
        "singleLineText": "test to single line",
        "date": "2025-01-01"
      }
    ]
  }
}

POST Bulk Update/Delete

Use "operation": "update" or "operation": "delete" with the same body structure as insert. 

Candidate Dialogue (Logging Candidate Emails)

The candidateDialogue scope lets you insert one or more candidate email records in a single request – either just storing them for record-keeping or queuing them to be sent. Each row is validated independently: valid rows are inserted, invalid rows are skipped and reported back with per-field errors.

POST

{
  "key": "{{api_key}}",
  "scope": "candidateDialogue",
  "operation": "insert",
  "dialogueType": "candidateEmail",
  "data": [
    {
      "candidateId": 2061435,
      "fromEmail": "recruiter@example.com",
      "toEmail": "candidate@example.com",
      "ccEmail": "audit@example.com",
      "send": 0,
      "emailSubject": "Interview confirmation",
      "emailMessage": "<p>Looking forward to speaking with you.</p>",
      "created": "2026-05-11 18:30:00"
    }
  ]
}

Top-level fields

CV Parsing

You can send an already-uploaded candidate file to the AI CV parser for asynchronous processing using the candidateCvParse scope. The parsed results are written back to the candidate's profile once processing completes; the endpoint itself only confirms that parsing has started.

POST

{
  "key": "{{api_key}}",
  "scope": "candidateCvParse",
  "operation": "insert",
  "data": {
    "fileId": 2606675
  }
}

PARAMS

What's next

Continue with Candidates: Creating Candidates and Nested Data via the API to see how these sub-objects fit into the full candidate record, or Candidates: Updating, Deleting, and Managing Files via the API to modify or remove existing candidate data.