API: Candidates (sub-entities)

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".

Note

Both operations accept multiple company IDs in a single request.

PARAMS

candidateId 2030141
required – the candidate to link/unlink companies on
companyIds [423645, 423646]
required – array of company IDs to add or remove

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

candidateId 2856682
required on insert
projectExperienceId
required on delete and update
name Project example
required on insert
url www.recman.no
optional
description Project description
optional
fromDate 2012-05-01
optional. Format: Y-m-d
toDate 2022-11-16
optional. Format: Y-m-d

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

key {{api_key}} 
required
scope candidatePool
required
candidatePoolId 436235
optional

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

candidatePoolId 436235
required
candidateIds [123456, 321435, 442214]
required – candidate IDs to add (insert) or remove (delete)

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).

Note

Validation is performed per attribute. Invalid attributes do not stop the request – they are skipped and returned as warnings. Critical validation failures (e.g., invalid candidate, missing attributes) stop execution and return errors.

Root Body

Field Type Required Description
candidateId integer yes Candidate identifier
attributes array yes List of attributes

Attributes

Field Type Required Description
attributeId integer yes Attribute ID
boolean integer (0/1) no Boolean value
rating integer (1–5) no Rating value
text string no Multi-line text
singleLineText string no Single-line text
dropdownId integer no Dropdown option ID
date string (YYYY-MM-DD) no Date value
checkboxIds array no Checkbox values

Rating Checkbox

Field Type Required Description
id integer yes Checkbox option ID
rating integer (0–5) no Checkbox rating

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

Field Type Required Description
key string yes Your API key.
scope string yes Must be candidateDialogue.
operation string yes Must be insert.
dialogueType string yes Must be candidateEmail.
data array yes Array of candidate email objects. See below.
Field Type Required Description
candidateId integer yes The candidate the email belongs to. Must exist in your subscription and be active.
fromEmail string yes Sender email address. Must be a valid email.
toEmail string yes Recipient email address. Must be a valid email.
ccEmail string no CC recipient. If present, must be a valid email.
emailSubject string yes Subject line of the email.
emailMessage string yes Body of the email. HTML is allowed.
send integer no 0 = store without sending, 1 = queue for sending. Defaults to 0.
created date yes Date and time the email was created. Format: Y-m-d H:i:s (2026-05-11 18:30:00). Should be in UTC format.

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
  }
}

Note

  • The endpoint responds immediately with HTTP 200 – it does not wait for parsing to complete.
  • Parsing requires the subscription to have CV Parsing enabled in the Marketplace.
  • Supported file types depend on the file extension stored in CandidateFile.

PARAMS

Field Type Required Description
operation string yes Must be insert
fileId integer yes ID of the candidate file to parse. Must be a positive integer.

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.

Was this article helpful?
0 out of 0 found this helpful