---
title: "Add a candidate"
method: POST
path: "/candidates"
tags: ["Candidate API:Candidates"]
---

# Add a candidate

`POST /candidates`

## Headers

- `X-Allow-Duplicates` string

## Request body

- AddCandidateCommand
  - `firstName` string, nullable
  - `lastName` string, nullable
  - `email` string, nullable
  - `phone` string, nullable
  - `mobile` string, nullable
  - `salutation` string, nullable — Salutation/honorific/title
  - `statusId` integer, nullable — Candidate status
  - `rating` string, nullable
  - `source` string, nullable — Candidate source
  - `seeking` 'Yes' | 'Maybe' | 'No', string
  - `unsubscribed` boolean
  - `summary` string, nullable
  - `dateOfBirth` string, date, nullable
  - `emergencyContact` string, nullable
  - `emergencyPhone` string, nullable
  - `social` object, nullable
  - `address` SubmitAddressModel
    - `street` string[], nullable
    - `city` string, nullable
    - `state` string, nullable
    - `postalCode` string, nullable
    - `countryCode` string, nullable
  - `skillTags` string[], nullable
  - `employment` SubmitEmploymentModel
    - `current` SubmitCurrentEmploymentModel
      - `employer` string, nullable
      - `position` string, nullable
      - `workTypeId` integer, nullable
      - `salary` SubmitSalaryModel
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
        - `rate` number, double
        - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
    - `ideal` SubmitIdealEmploymentModel
      - `position` string, nullable
      - `workTypeId` integer, nullable
      - `salary` SubmitSalaryRangeModel
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
        - `rateLow` number, double
        - `rateHigh` number, double, nullable
        - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
      - `other` SubmitIdealSalaryModel[], nullable
        - `workTypeId` integer, nullable
        - `salary` SubmitSalaryRangeModel
          - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
          - `rateLow` number, double
          - `rateHigh` number, double, nullable
          - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
    - `history` CandidateEmploymentHistoryModel[], nullable
      - `employer` string, nullable — Name of the employer
      - `position` string, nullable
      - `start` string, nullable — Year, month or date employment started.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
      - `end` string, nullable — Year, month or date employment finished, or "Present" for a current role.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
      - `description` string, nullable — Description of responsibilities and achievements.
  - `availability` SubmitCandidateAvailabilityModel — The date the candidate is available to start. Specify ONE OF immediate, relative or date.
    - `immediate` boolean — The candidate is available for an immediate start
    - `relative` SubmitRelativeStartModel
      - `period` integer
      - `unit` 'Week' | 'Month', string
    - `date` string, date, nullable — The specific date that a job starts or a candidate is available
  - `education` SubmitCandidateEducationModel[], nullable
    - `institution` string, nullable
    - `course` string, nullable
    - `date` string, nullable — Year, month or date completed.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
  - `custom` SubmitCustomFieldValueModel[], nullable
    - `fieldId` integer, required
    - `value` unknown
  - `recruiterUserId` integer[], nullable
  - `customSkills` string[], nullable — A maximum of 500 custom skills can be submitted per request

## Response `201`

Created

- CandidateRepresentation
  - `candidateId` integer, required — Candidate Id
  - `firstName` string, nullable — First name
  - `lastName` string, nullable — Last name
  - `email` string, nullable — Primary email address
  - `phone` string, nullable — Contact phone number
  - `mobile` string, nullable — Mobile/cell number
  - `mobileNormalized` string, nullable — Mobile/cell normalized number
  - `contactMethod` string, nullable — Preferred contact method
  - `salutation` string, nullable — Salutation/honorific/title
  - `unsubscribed` boolean
  - `address` AddressModel
    - `street` string[], nullable
    - `city` string, nullable
    - `state` string, nullable
    - `postalCode` string, nullable
    - `country` string, nullable
    - `countryCode` string, nullable
  - `status` StatusModel
    - `statusId` integer, required
    - `name` string, required
    - `active` boolean
    - `default` boolean
  - `rating` string, nullable — Internal rating of the candidate
  - `source` string, nullable — The source of the candidate
  - `seeking` 'Yes' | 'Maybe' | 'No', string
  - `dateOfBirth` string, date, nullable — Candidate date of birth available ([ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6))
  - `emergencyContact` string, nullable — The emergency contact of the candidate
  - `emergencyPhone` string, nullable — The emergency phone of the candidate
  - `otherEmail` string[], nullable — Other email addresses used by the candidate
  - `social` object, nullable — Candidate social profiles
  - `summary` string, nullable
  - `employment` CandidateEmploymentModel
    - `current` CurrentEmploymentModel
      - `employer` string, nullable
      - `position` string, nullable
      - `workType` WorkTypeModel
        - `workTypeId` integer, required
        - `name` string, required
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
      - `salary` SalaryModel
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
        - `rate` number, double, nullable
        - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
    - `ideal` CandidateIdealEmploymentModel
      - `position` string, nullable
      - `workType` WorkTypeModel
        - `workTypeId` integer, required
        - `name` string, required
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
      - `salary` SalaryRangeModel
        - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
        - `rateLow` number, double, nullable
        - `rateHigh` number, double, nullable
        - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
      - `other` CandidateIdealSalaryModel[], nullable
        - `workType` WorkTypeModel
          - `workTypeId` integer, required
          - `name` string, required
          - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
        - `salary` SalaryRangeModel
          - `ratePer` 'Hour' | 'Day' | 'Week' | 'Month' | 'Year', string
          - `rateLow` number, double, nullable
          - `rateHigh` number, double, nullable
          - `currency` string, nullable — Optional ISO 4217 3-letter alphabetic currency code
    - `history` CandidateEmploymentHistoryModel[], nullable
      - `employer` string, nullable — Name of the employer
      - `position` string, nullable
      - `start` string, nullable — Year, month or date employment started.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
      - `end` string, nullable — Year, month or date employment finished, or "Present" for a current role.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
      - `description` string, nullable — Description of responsibilities and achievements.
  - `availability` CandidateStartModel — The date the candidate is available to start. Specify ONE OF immediate, relative or date.
    - `immediate` boolean
    - `relative` RelativeStartModel
      - `period` integer
      - `unit` 'Week' | 'Month', string
    - `date` string, date, nullable — The specific date that a job starts or a candidate is available
  - `education` CandidateEducationModel[], nullable
    - `institution` string, nullable
    - `course` string, nullable
    - `date` string, nullable — Year, month or date completed.<br /> Year must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), the 4 digit year the course was completed, e.g. 2017<br /> Month must be formatted as [ISO date-fullyear](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) "-" [ISO date-month](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07<br /> Date must be formatted as [ISO full-date](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6), e.g. 2017-07-31
  - `skillTags` string[], nullable
  - `custom` CustomFieldValueModel[], nullable
    - `fieldId` integer, required
    - `name` string, required
    - `type` 'Text' | 'List' | 'Date' | 'Lookup' | 'Url', string, required — The type of value a custom field expects
    - `value` unknown
  - `recruiters` UserNameModel[], nullable
    - `userId` integer, required
    - `firstName` string, nullable
    - `lastName` string, nullable
    - `position` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `mobile` string, nullable
    - `inactive` boolean
    - `deleted` boolean
  - `createdBy` UserNameModel
    - `userId` integer, required
    - `firstName` string, nullable
    - `lastName` string, nullable
    - `position` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `mobile` string, nullable
    - `inactive` boolean
    - `deleted` boolean
  - `createdAt` string, date-time, nullable
  - `updatedBy` UserNameModel
    - `userId` integer, required
    - `firstName` string, nullable
    - `lastName` string, nullable
    - `position` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `mobile` string, nullable
    - `inactive` boolean
    - `deleted` boolean
  - `updatedAt` string, date-time, nullable
  - `partnerActions` PartnerActionStageModel[], nullable
    - `actionId` string, uuid
    - `actionName` string, nullable
    - `reference` string, nullable — Unique partner defined reference/identifier for the action
    - `stage` 'Submitted' | 'InProgress' | 'Completed' | 'Rejected' | 'Cancelled', string
    - `status` string, nullable — Partner defined progress status message for the action
    - `result` PartnerActionResultModel
      - `score` integer, nullable — Optional partner score for the action result
      - `url` string, uri, nullable — Optional partner defined URL for the action result
      - `urlType` 'Popup' | 'Page', string
    - `submittedAt` string, date-time
    - `submittedBy` UserNameModel
      - `userId` integer, required
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `position` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `mobile` string, nullable
      - `inactive` boolean
      - `deleted` boolean
    - `updatedAt` string, date-time
    - `updatedBy` UserNameModel
      - `userId` integer, required
      - `firstName` string, nullable
      - `lastName` string, nullable
      - `position` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `mobile` string, nullable
      - `inactive` boolean
      - `deleted` boolean
  - `statistics` CandidateStatisticsModel
    - `applications` CandidateJobApplicationStatisticsSummaryModel
      - `new` integer
      - `active` integer
      - `total` integer
    - `placements` CandidatePlacementStatisticsSummaryModel
      - `total` integer
  - `links` CandidateLinks
    - `self` string, uri, nullable
    - `contact` string, uri, nullable — Optional contact if candidate is also a contact
    - `photo` string, uri, nullable — Candidate photo
    - `resume` string, uri, nullable — Resume Attachment
    - `formattedResume` string, uri, nullable — Formated Attachment
    - `coverLetter` string, uri, nullable — CoverLetter Attachment
    - `skills` string, uri, nullable — Skills
    - `notes` string, uri, nullable — Notes
    - `attachments` string, uri, nullable — Attachments
    - `videos` string, uri, nullable — Videos
    - `floats` string, uri, nullable — Floats
    - `submissions` string, uri, nullable — Submissions
    - `applications` string, uri, nullable — Job Applications
    - `placements` string, uri, nullable — Placements

## Other responses

- `409` — Candidate with this email already exists
- `422` — Validation error

---

[API](https://skmtc.net/jobadder/apis/jobadder-api.md) · [All operations](https://skmtc.net/jobadder/apis/jobadder-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jobadder/jobadder-api/revisions/9f43f6a6ee6e/schema)