In this article, you can read about how to create a new candidate and attach nested data such as education, experience, employment, skills, files, attributes, and pipeline entries via the API.
Insert Candidate
Inserting candidates is done through the POST method. The operation must be set to insert and scope to candidate. The fields corporationId, firstName, and lastName are required. If the insert is validated and successful, a standard response is returned containing the new
candidateId.
POST
https://api.recman.io/v2/post/Insert of Nested Objects
Segments like education, certifications, skills, employee data, and so on are inserted through nested objects. To insert one, you must provide a candidateId along with the nested object under its own field name. The API only allows 1 insert per request. On a successful insert, the response returns the new ID of the nested object (e.g., inserting education returns an educationId).
Notice
The correct method for adding nested objects (education, experience, skills, and so on) to a candidate is the insert operation — not update. The update operation is only used to modify data that has already been inserted. See Candidates: Updating, Deleting, and Managing Files via the API for details.
Education
Field: education — object
| Sub Fields | Description |
|---|---|
| educationId integer | Required on operation: update, delete |
| schoolName string | Name of the school |
| type string | Type of school |
| startDate / endDate date | Format: Y-m-d (e.g. 2025-10-31) |
| description string | Description |
| degree string | Degree |
| location string | Location |
Experience
Field: experience — object
| Sub Fields | Description |
|---|---|
| experienceId string | Required on operation: update, delete |
| companyName string | Name of company |
| title string | Title |
| location string | Location |
| startDate / endDate date | Format: Y-m-d |
| current integer | 1 = Yes, 0 = No. Valid values: 0, 1 |
| description string | Description |
Certification
Field: certification — object
| Sub Fields | Description |
|---|---|
| id string | Certification ID. Required on operation: update, delete |
| name string | Name of certification |
| description string | Description |
| endDate date | Date of certification expiration. Format: Y-m-d |
| candidateAccess integer | 1 = Yes, 0 = No. Valid values: 0, 1 |
Language
Field: language — object
| Sub Fields | Description |
|---|---|
| languageId string | Required on operation: update, delete |
| name string | Name of language. Valid values: ISO_3166-1 standard — Alpha-code 2 |
| level string | Valid values: elementary, limitedWorking, professionalWorking, fullProfessional, nativeOrBilingual |
Employee
Inserting any field into the employee object approves the candidate for staffing and, unless provided, an employee number will be assigned automatically.
Note
Fields shared between employee and the primary employment object are synced automatically when either is inserted or updated. Shared fields: socialSecurityNo, bankAccount, bic, iban, startDate, endDate, employment, salary, occupationCode, employmentPercent, dnumber, number, customerId. If an employee object already exists on the candidate, its data will be updated instead of duplicated.
Field: employee — object (all sub-fields optional unless noted)
| Sub Fields | Description |
|---|---|
| socialSecurityNo / bankAccount / bic / iban string | Banking / ID details |
| startDate / endDate date | Format: Y-m-d |
| employment string | Employment condition. Valid values: fullTime, partTime, extra, onDemand, fullTimeOutplacement, partTimeOutplacement, onDemandOutplacement |
| salary double | Salary |
| occupationCode string | Occupation code ID |
| employmentPercent double | Employment percent |
| status string | Valid values: active, quit, unpaidSickLeave, paidSickLeave, paidLeave, unpaidLeave, laidOff |
| active string | 0 or 1. Default: 1 |
| dnumber / number string / integer | D-number / employee number |
| notes string | Notes |
| companyId string | Company ID |
| substituteType integer | Valid values: 0, 1, 2 |
| seniority integer | Seniority |
| hogiaEmploymentStatus string | Valid values: warrantyEmpWithoutLeave, warrantyEmpWithLeave, warrantyUnion, internalEmp, ongoing, endedNoRenewal, endedRenewalPossible, onDemand, hourlyEmployed, gamGuarantee, weeklyPaid, monthGuarantee, newGuarantee |
| paymentType string | Valid values: fixed, hourly, commission, piecework, remuneration |
| workType string | Valid values: noShift, offshore, continuous, rotation, shift365 |
| paymentInterval string | Valid values: monthly, fortnight, weekly, monthly125, monthly13, hourly, commission |
| workConditionType string | Valid values: other, pension, ordinary, maritime |
| shift string | Valid values: offshore, noShift, continuous, rotation, 2shift, piecework |
| foreignSocialSecurityNo / offshoreBankAccount string | Foreign SSN / offshore bank account |
| salaryInterval string | Valid values: weekly, fortnight, monthly |
| hoursWeekly double | Hours per week |
| paymentMethod string | Valid values: cash, bank, offshore, ledger |
| tableType string | Valid values: monthly, week4, week3, fortnight, weekly, daily4, daily3, daily2, daily |
| tableNumber integer | Table number |
| taxPercent double | Tax percent |
| municipalityCode integer | Municipality code |
| emailPaycheck / aaRegister integer | 1 or 0 (enabled/disabled) |
| clearingNumber string | Clearing number |
| employmentForm string | Valid values: ongoing, trial, limitedPeriod, substitution, substitutionVacancy, someTime, student, workStop, after65, otherWork, onDemandEmployment |
Dependents
Dependents will only be visible in RecMan for candidates that are approved for staffing.
Field: dependents — object
| Sub Fields | Description |
|---|---|
| dependentsId string | Required on operation: update, delete |
| name string | Name |
| relation string | Relation |
| email string | |
| mobilePhone / officePhone / homePhone string | Phone numbers |
| notes string | Notes |
Skills
Field: skills — object
| Sub Fields | Description |
|---|---|
| skillsId string | Required on operation: update, delete |
| name string | Skill name |
| rating string | Valid values: 1, 2, 3, 4, 5 |
Reference
Field: reference — object
| Sub Fields | Description |
|---|---|
| referenceId string / integer | Required on operation: update, delete |
| name / companyName string | Reference person name and company |
| email / officePhone / mobilePhone string | Contact details |
| description / internalNote / notes string | Free-text fields |
Files
If you're inserting a candidate and want to add files, the candidate must be created first — this is a two-step process: 1) insert the candidate, 2) upload files on the inserted candidate.
Field: file — object
| Sub Fields | Description |
|---|---|
| name string | Name |
| jobApplicationId int | Optional — link the file to a job application |
| extension string | Valid values: pdf, docx, etc. |
| base64 string | Base64-encoded file content |
| created date-time | Format: Y-m-d H:i:s |
| candidateAccess integer | 0 = default (no access); 1 = candidate can access the file when logged in |
| url string | Optional — upload a file by URL instead of base64 |
Profile Picture
Field: profilePicture — object
| Sub Fields | Description |
|---|---|
| extension string | Required on operation: insert |
| base64 string | Required on operation: insert |
| name string | Name + extension (optional) |
Attribute(s)
If you want to create a new candidate with an attribute, the candidate must be created first, then the attribute is added to the candidate. To find the attributeId you need, see Retrieving Attribute IDs for Candidates, Companies, Contact Persons, and Projects.
Use the singular attribute field to insert one attribute at a time, or attributes (array of objects) to insert several in one request.
| Sub Fields | Description |
|---|---|
| attributeId integer | The ID of the attribute. Required on operation: insert |
| candidateAttributeId integer | The ID of the attribute on the candidate. Required on insert, when adding checkboxes to an existing attribute |
| text string | Free-text value |
| bool integer | 0 = false, 1 = true |
| rating integer | Valid values: 1, 2, 3, 4, 5 |
| checkboxIds array of integer | List of checkbox IDs. To add a rating, provide a sub-object with "id" and "rating" |
| dropdownId integer | The ID of the dropdown value |
Pipeline
Field: pipeline — object
| Sub Fields | Description |
|---|---|
| categoryId integer | Pipeline stage / category ID |
| userId integer | Responsible user ID |
| projectId integer | Project ID |
| jobPostId integer | Job post ID |
Job Applications
Field: jobApplication — object
| Sub Fields | Description |
|---|---|
| jobApplicationId integer | Required on operation: update, delete |
| jobPostId integer | Job post ID |
| text string | Application text |
| status string | Valid values: Declined, Untreated, Pipeline, Hired |
| created string | Date of application. Format: Y-m-d |
Interview
By adding the parameter interviewLastUpdated to a GET request, you can retrieve candidates and interviews updated after a given timestamp, e.g.:&interviewLastUpdated=2019-01-01 07:00:00.
Field: interview — object
| Sub Fields | Description |
|---|---|
| interviewId integer | Required on operation: update, delete |
| name string | Name |
| notes string | Notes. HTML is supported |
| rating integer | Valid values: 1, 2, 3, 4, 5 |
| startDateTime / endDateTime date-time | Format: Y-m-d H:i:s |
| created / updated date-time | Format: Y-m-d H:i:s |
| userId integer | The ID of the user |
HPR
Field: hpr — object
| Sub Fields | Description |
|---|---|
| number integer | HPR (Healthcare Personnel Register) number |
| approved string | Valid values: 0, 1 |
| notes string | Notes. HTML is supported |
Reference Check
Field: referenceCheck — object
| Sub Fields | Description |
|---|---|
| notes string | Notes. HTML is expected |
| status string | 0 = Not approved, 1 = Approved. Valid values: 0, 1 |
| created date-time | Format: Y-m-d H:i:s |
Work Location
Field: workLocation — object
| Sub Fields | Description |
|---|---|
| workLocationId integer | Required on operation: update, delete |
| countryId integer | Country ID |
| regionId integer | Region ID |
| cityId integer | City ID |
Driving Licence
Driving licences are inserted directly on the candidate's driversLicense field (see Get Candidate's Fields in the retrieving article) as an array of license type codes.
| Field | Description |
|---|---|
| driversLicense array of strings | Valid values: A, A1, B, BE, D, D1, D1E, DE, C, C1, C1E, CE, M, T, TRUCK |
Accept Terms
Accepting terms on behalf of a candidate is done using its own scope. The field candidateId is required; userId and created are optional.
| scope | candidateAcceptTerms required |
| candidateId | 2031411 required |
| userId | 7592 optional |
| created | 2023-11-05 09:00:00 optional. Format: Y-m-d H:i:s |
Phone List
Phone list numbers are added directly when inserting or updating the candidate entity. The field phoneList is optional and supports one, several, or all of the phone types below.
| Phone type | Sub Fields |
|---|---|
| mobile | prefix (string), number (string) |
| office | prefix (string), number (string) |
| home | prefix (string), number (string) |
Associated Users
Users are associated with a candidate through the userIds field — an array of user IDs — passed directly on the candidate entity, following the same insert pattern as the other fields above.
What's next
Continue with Candidates: Retrieving Candidate Data via the API for lookup and search options, or with Candidates: Updating, Deleting, and Managing Files via the API to modify or remove existing data.