Candidate Onboarding
Endpoints to search candidates and retrieve onboarding information.
post
copied!# You can also use wgetcurl -X POST https://api-qa.phenompro.com/candidates-api/onboarding/v1/candidates/search
-H 'Content-type: application/json'
-H 'Accept: application/json'
-H 'Authorization: string'POST /candidates-api/onboarding/v1/candidates/search
Search onboarding candidates by firstName, lastName, and/or emailId with pagination.
Headers
| Name | In | Type | Required |
|---|---|---|---|
| Authorization | header | string | true |
Body Parameter
copied![
{
"type": "object",
"required": {
"0": "filters"
},
"description": "Search request with structured filters and pagination.",
"properties": {
"filters": {
"CandidateSearchFilters": {
"type": "object",
"description": "At least one non-blank filter is required. Multiple filters are combined with AND. Each filter uses exact case-insensitive match.",
"properties": {
"firstName": {
"type": "string",
"description": "Candidate first name (exact, case-insensitive)."
},
"lastName": {
"type": "string",
"description": "Candidate last name (exact, case-insensitive)."
},
"emailId": {
"type": "string",
"description": "Candidate email (exact, case-insensitive)."
}
}
}
},
"from": {
"type": "integer",
"description": "Starting point from which the data should be retrieved (zero-based offset)."
},
"size": {
"type": "integer",
"description": "Maximum number of candidates to return in this response."
}
}
}
]Request Parameters
| Type | Name |
|---|---|
| application/json | CandidateSearchRequest |
Response
Candidates matching the filters. Results may be empty; when no candidates match.
copied![
{
"type": "object",
"description": "Successful paginated candidate search response.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success."
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Candidates fetched successfully"
},
"data": {
"type": "array",
"description": "Matching candidates for the current page.",
"items": {
"CandidateSearchResultItem": {
"type": "object",
"description": "Object shape for each entry in the data array.",
"properties": {
"candidateId": {
"type": "string",
"description": "Candidate identifier."
},
"onboardingCaseId": {
"type": "string",
"description": "Onboarding case identifier."
},
"firstName": {
"type": "string",
"description": "Candidate first name."
},
"middleName": {
"type": "string",
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"description": "Candidate last name."
},
"emailId": {
"type": "string",
"description": "Candidate email address."
}
}
}
}
},
"totalCount": {
"type": "integer",
"format": "int64",
"description": "Total number of candidates matching the search criteria."
},
"startIndex": {
"type": "integer",
"description": "Zero-based starting index of the returned candidates (same as request from)."
},
"paginationSize": {
"type": "integer",
"description": "Maximum number of candidates returned per page (same as request size)."
}
}
}
]Invalid request (missing/blank filters or invalid pagination).
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]An unexpected server error occurred while processing the request.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Candidates matching the filters. Results may be empty; when no candidates match. | CandidateSearchSuccessResponse |
| 400 | Invalid request (missing/blank filters or invalid pagination). | Error |
| 500 | An unexpected server error occurred while processing the request. | Error |
get
copied!# You can also use wgetcurl -X GET https://api-qa.phenompro.com/candidates-api/onboarding/v1/candidates/{candidateId}
-H 'Content-type: application/json'
-H 'Accept: application/json'
-H 'Authorization: string'GET /candidates-api/onboarding/v1/candidates/{candidateId}
Fetches onboarding data for a candidate. The path identifier may be candidateId or onboardingCaseId.
Headers
| Name | In | Type | Required |
|---|---|---|---|
| Authorization | header | string | true |
Parameters
| Name | In | Type | Required |
|---|---|---|---|
| candidateId | path | string | true |
Response
Successfully fetched the onboarding details for the given candidate.
copied![
{
"type": "object",
"description": "Successful API response with status, message, and onboarding payload.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success."
},
"message": {
"type": "string",
"description": "Outcome message for the client (e.g. confirmation that candidate data was fetched).",
"example": "Candidate data fetched successfully"
},
"data": {
"type": "object",
"description": "Onboarding data for the requested candidate.",
"allOf": {
"0": {
"OnboardingData": {
"type": "object",
"description": "Payload returned for a successful candidate onboarding fetch: profile and contact data under candidateDetails, and requisition or job context under jobDetails.",
"properties": {
"candidateDetails": {
"type": "object",
"description": "Candidate details and additional fields for the candidate.",
"allOf": {
"0": {
"CandidateDetails": {
"type": "object",
"description": "Candidate profile: emails, phone contacts, identification, education, work history, address, and tenant-specific custom fields.",
"properties": {
"firstName": {
"type": "string",
"description": "Candidate given name."
},
"middleName": {
"type": "string",
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"description": "Candidate family name."
},
"gender": {
"type": "string",
"description": "Gender or gender identity as stored for the candidate."
},
"primaryEmailId": {
"type": "string",
"description": "Primary email address used for onboarding communications."
},
"secondaryEmailId": {
"type": "string",
"description": "Secondary or alternate email address."
},
"officialEmailId": {
"type": "string",
"description": "Work or official email address when provided."
},
"dateOfBirth": {
"type": "string",
"format": "date",
"description": "Date of birth as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"joiningDate": {
"type": "string",
"format": "date",
"description": "Expected or planned joining date as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"contacts": {
"type": "array",
"description": "Ordered list of phone contact entries (e.g. primary and secondary); each item may include type, dial code, and number.",
"items": {
"CandidateContact": {
"type": "object",
"description": "A single phone contact line, distinguished by type (for example primary vs secondary).",
"properties": {
"type": {
"type": "string",
"description": "Contact slot or role, such as primary or secondary."
},
"phoneNumber": {
"type": "string",
"description": "Local phone number without country prefix (when present)."
},
"countryCode": {
"type": "string",
"description": "Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91)."
}
}
}
}
},
"identificationDetails": {
"type": "array",
"description": "Government or employer identification documents associated with the candidate.",
"items": {
"CandidateIdentification": {
"type": "object",
"description": "One identification document or credential record.",
"properties": {
"type": {
"type": "string",
"description": "Kind of identification (e.g. aadhaar, passport)."
},
"number": {
"type": "string",
"description": "Document or identification number."
},
"location": {
"type": "string",
"description": "Issuing location or jurisdiction, if applicable."
},
"issuedDate": {
"type": "string",
"description": "Issue date as returned by the source (empty string if unknown)."
},
"expiryDate": {
"type": "string",
"description": "Expiry date as returned by the source (empty string if unknown or not applicable)."
},
"status": {
"type": "string",
"description": "Verification or document status when provided."
}
}
}
}
},
"education": {
"type": "array",
"description": "Education history entries.",
"items": {
"CandidateEducation": {
"type": "object",
"description": "A single education record.",
"properties": {
"degree": {
"type": "string",
"description": "Degree or qualification title."
},
"fieldOfStudy": {
"type": "string",
"description": "Major or field of study."
},
"schoolName": {
"type": "string",
"description": "School or institute name."
},
"schoolAndUniversity": {
"type": "string",
"description": "Combined campus, university, or location label when provided."
},
"startDate": {
"type": "string",
"description": "Program start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"description": "Program end date (format as returned by the source)."
},
"isHighEducation": {
"type": "boolean",
"description": "Whether this entry is marked as the highest level of education."
},
"state": {
"type": "string",
"description": "State or region for the institution."
},
"country": {
"type": "string",
"description": "Country for the institution."
}
}
}
}
},
"experience": {
"type": "array",
"description": "Employment history entries.",
"items": {
"CandidateExperience": {
"type": "object",
"description": "A single employment history record.",
"properties": {
"company": {
"type": "string",
"description": "Employer or organization name."
},
"jobTitle": {
"type": "string",
"description": "Job title at the employer."
},
"role": {
"type": "string",
"description": "Role or function (may mirror job title)."
},
"jobLocation": {
"type": "string",
"description": "Work location for this role."
},
"isCurrent": {
"type": "string",
"description": "Whether this is the current employer (e.g. yes or no as stored in source data)."
},
"industry": {
"type": "string",
"description": "Industry sector when captured."
},
"startDate": {
"type": "string",
"description": "Employment start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"description": "Employment end date (format as returned by the source); empty if current."
}
}
}
}
},
"address": {
"type": "object",
"description": "Current and permanent address details.",
"allOf": {
"0": {
"CandidateAddressBlock": {
"type": "object",
"description": "Current and permanent address lines. Both keys are always present; each value is always a StructuredAddress (never null at this level).",
"properties": {
"currentAddress": {
"description": "Current address of the candidate.",
"allOf": {
"0": {
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"description": "Second line of the street address."
},
"city": {
"type": "string",
"description": "City."
},
"zipCode": {
"type": "string",
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"description": "Country."
},
"state": {
"type": "string",
"description": "State or region."
},
"startDate": {
"type": "string",
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
}
},
"permanentAddress": {
"description": "Permanent address of the candidate.",
"allOf": {
"0": {
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"description": "Second line of the street address."
},
"city": {
"type": "string",
"description": "City."
},
"zipCode": {
"type": "string",
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"description": "Country."
},
"state": {
"type": "string",
"description": "State or region."
},
"startDate": {
"type": "string",
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
}
}
}
}
}
}
},
"additionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom attributes for the candidate; keys and value types depend on configuration.",
"allOf": {
"0": {
"AdditionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration)."
}
}
}
}
}
}
}
}
},
"jobDetails": {
"type": "object",
"description": "Job details and job additional fields for the candidate's job.",
"allOf": {
"0": {
"JobDetails": {
"type": "object",
"description": "Job or requisition context: top-level fields for common attributes, plus additionalFields for ATS, recruiter or hiring-manager contacts, department, and other tenant-specific job metadata.",
"properties": {
"jobTitle": {
"type": "string",
"description": "Title of the job or requisition."
},
"jobId": {
"type": "string",
"description": "Internal or external job identifier."
},
"jobLocation": {
"type": "string",
"description": "Primary job location label or free text."
},
"jobCategory": {
"type": "string",
"description": "Category or family of the role."
},
"positionCode": {
"type": "string",
"description": "Position or requisition code when used by the tenant."
},
"positionTitle": {
"type": "string",
"description": "Position title as distinct from job title when both are maintained."
},
"department": {
"type": "string",
"description": "Hiring department or cost center name."
},
"additionalFields": {
"type": "object",
"description": "Tenant specific custom fields.",
"allOf": {
"0": {
"AdditionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration)."
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
}
]The candidate does not exist or was not found.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]An unexpected server error occurred while processing the request.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successfully fetched the onboarding details for the given candidate. | OnboardingSuccessResponse |
| 404 | The candidate does not exist or was not found. | Error |
| 500 | An unexpected server error occurred while processing the request. | Error |
Onboarding Attachments
Endpoints to retrieve candidate attachments and signed URLs.
get
copied!# You can also use wgetcurl -X GET https://api-qa.phenompro.com/candidates-api/onboarding/v1/candidates/{candidateId}/attachments
-H 'Content-type: application/json'
-H 'Accept: application/json'
-H 'Authorization: string'GET /candidates-api/onboarding/v1/candidates/{candidateId}/attachments
Fetches attachments metadata list for a candidate. The path identifier may be candidateId or onboardingCaseId.
Headers
| Name | In | Type | Required |
|---|---|---|---|
| Authorization | header | string | true |
Parameters
| Name | In | Type | Required |
|---|---|---|---|
| candidateId | path | string | true |
Response
Successfully fetched candidate attachments list.
copied![
{
"type": "object",
"description": "Successful response for candidate attachments list. The data field is a JSON array of attachment items.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success."
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Attachments list fetched successfully"
},
"data": {
"type": "array",
"description": "List of files attached to the candidate for onboarding.",
"items": {
"CandidateAttachment": {
"type": "object",
"description": "Metadata for a single file attached to the candidate.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Unique attachment identifier."
},
"attachmentFileName": {
"type": "string",
"description": "Stored or display file name for the document."
},
"attachmentType": {
"type": "string",
"description": "Document type."
},
"attachmentUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Uploaded date."
}
}
}
}
}
}
}
]The candidate does not exist or was not found.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]An unexpected server error occurred while processing the request.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successfully fetched candidate attachments list. | CandidateAttachmentsSuccessResponse |
| 404 | The candidate does not exist or was not found. | Error |
| 500 | An unexpected server error occurred while processing the request. | Error |
get
copied!# You can also use wgetcurl -X GET https://api-qa.phenompro.com/candidates-api/onboarding/v1/candidates/{candidateId}/attachments/{attachmentId}
-H 'Content-type: application/json'
-H 'Accept: application/json'
-H 'Authorization: string'GET /candidates-api/onboarding/v1/candidates/{candidateId}/attachments/{attachmentId}
Fetches signed URL for a candidate attachment using 5-minute expiry. The path identifier may be candidateId or onboardingCaseId.
Headers
| Name | In | Type | Required |
|---|---|---|---|
| Authorization | header | string | true |
Parameters
| Name | In | Type | Required |
|---|---|---|---|
| candidateId | path | string | true |
| attachmentId | path | string | true |
Response
Successfully generated signed URL for the attachment.
copied![
{
"type": "object",
"description": "Successful response for attachment signed URL.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success."
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Attachment fetched successfully"
},
"data": {
"type": "object",
"description": "Download details for the requested attachment.",
"allOf": {
"0": {
"CandidateAttachmentSignedUrlData": {
"type": "object",
"description": "Signed download details for a single attachment.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Attachment identifier."
},
"attachmentUrl": {
"type": "string",
"format": "uri",
"description": "Time-limited signed URL to download the file; the URL expires after 5 minutes."
},
"attachmentContentType": {
"type": "string",
"description": "MIME type stored with the document (e.g. application/pdf)."
},
"attachmentSize": {
"type": "integer",
"format": "int64",
"description": "File size in bytes."
}
}
}
}
}
}
}
}
]Not found: either the candidate does not exist, or the attachment does not exist for that candidate (invalid or unknown attachmentId).
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]An unexpected server error occurred while processing the request.
copied![
{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}
]Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successfully generated signed URL for the attachment. | CandidateAttachmentSignedUrlSuccessResponse |
| 404 | Not found: either the candidate does not exist, or the attachment does not exist for that candidate (invalid or unknown attachmentId). | Error |
| 500 | An unexpected server error occurred while processing the request. | Error |
Schemas
copied!{
"type": "object",
"required": [
"filters"
],
"description": "Search request with structured filters and pagination.",
"properties": {
"filters": {
"CandidateSearchFilters": {
"type": "object",
"description": "At least one non-blank filter is required. Multiple filters are combined with AND. Each filter uses exact case-insensitive match.",
"properties": {
"firstName": {
"type": "string",
"description": "Candidate first name (exact, case-insensitive)."
},
"lastName": {
"type": "string",
"description": "Candidate last name (exact, case-insensitive)."
},
"emailId": {
"type": "string",
"description": "Candidate email (exact, case-insensitive)."
}
}
}
},
"from": {
"type": "integer",
"description": "Starting point from which the data should be retrieved (zero-based offset).",
"minimum": 0,
"default": 0,
"example": 0
},
"size": {
"type": "integer",
"description": "Maximum number of candidates to return in this response.",
"minimum": 1,
"maximum": 100,
"default": 20,
"example": 20
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| filters | object | CandidateSearchFilters |
| from | integer | Starting point from which the data should be retrieved (zero-based offset). |
| size | integer | Maximum number of candidates to return in this response. |
copied!{
"type": "object",
"description": "At least one non-blank filter is required. Multiple filters are combined with AND. Each filter uses exact case-insensitive match.",
"properties": {
"firstName": {
"type": "string",
"description": "Candidate first name (exact, case-insensitive)."
},
"lastName": {
"type": "string",
"description": "Candidate last name (exact, case-insensitive)."
},
"emailId": {
"type": "string",
"description": "Candidate email (exact, case-insensitive)."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| firstName | string | Candidate first name (exact, case-insensitive). |
| lastName | string | Candidate last name (exact, case-insensitive). |
| emailId | string | Candidate email (exact, case-insensitive). |
copied!{
"type": "object",
"description": "Successful paginated candidate search response.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success.",
"example": 200
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Candidates fetched successfully"
},
"data": {
"type": "array",
"description": "Matching candidates for the current page.",
"items": {
"CandidateSearchResultItem": {
"type": "object",
"description": "Object shape for each entry in the data array.",
"properties": {
"candidateId": {
"type": "string",
"nullable": true,
"description": "Candidate identifier."
},
"onboardingCaseId": {
"type": "string",
"description": "Onboarding case identifier."
},
"firstName": {
"type": "string",
"nullable": true,
"description": "Candidate first name."
},
"middleName": {
"type": "string",
"nullable": true,
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "Candidate last name."
},
"emailId": {
"type": "string",
"nullable": true,
"description": "Candidate email address."
}
}
}
}
},
"totalCount": {
"type": "integer",
"format": "int64",
"description": "Total number of candidates matching the search criteria.",
"example": 238
},
"startIndex": {
"type": "integer",
"description": "Zero-based starting index of the returned candidates (same as request from).",
"example": 0
},
"paginationSize": {
"type": "integer",
"description": "Maximum number of candidates returned per page (same as request size).",
"example": 20
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| status | integer | HTTP status code indicating success. |
| message | string | Outcome message for the client. |
| data | array | CandidateSearchResultItem |
| totalCount | integer | Total number of candidates matching the search criteria. |
| startIndex | integer | Zero-based starting index of the returned candidates (same as request from). |
| paginationSize | integer | Maximum number of candidates returned per page (same as request size). |
copied!{
"type": "object",
"description": "Object shape for each entry in the data array.",
"properties": {
"candidateId": {
"type": "string",
"nullable": true,
"description": "Candidate identifier."
},
"onboardingCaseId": {
"type": "string",
"description": "Onboarding case identifier."
},
"firstName": {
"type": "string",
"nullable": true,
"description": "Candidate first name."
},
"middleName": {
"type": "string",
"nullable": true,
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "Candidate last name."
},
"emailId": {
"type": "string",
"nullable": true,
"description": "Candidate email address."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| candidateId | string | Candidate identifier. |
| onboardingCaseId | string | Onboarding case identifier. |
| firstName | string | Candidate first name. |
| middleName | string | Candidate middle name. |
| lastName | string | Candidate last name. |
| emailId | string | Candidate email address. |
copied!{
"type": "object",
"description": "Successful API response with status, message, and onboarding payload.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success.",
"example": 200
},
"message": {
"type": "string",
"description": "Outcome message for the client (e.g. confirmation that candidate data was fetched).",
"example": "Candidate data fetched successfully"
},
"data": {
"type": "object",
"description": "Onboarding data for the requested candidate.",
"allOf": [
{
"OnboardingData": {
"type": "object",
"description": "Payload returned for a successful candidate onboarding fetch: profile and contact data under candidateDetails, and requisition or job context under jobDetails.",
"properties": {
"candidateDetails": {
"type": "object",
"description": "Candidate details and additional fields for the candidate.",
"allOf": [
{
"CandidateDetails": {
"type": "object",
"description": "Candidate profile: emails, phone contacts, identification, education, work history, address, and tenant-specific custom fields.",
"properties": {
"firstName": {
"type": "string",
"nullable": true,
"description": "Candidate given name."
},
"middleName": {
"type": "string",
"nullable": true,
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "Candidate family name."
},
"gender": {
"type": "string",
"nullable": true,
"description": "Gender or gender identity as stored for the candidate."
},
"primaryEmailId": {
"type": "string",
"nullable": true,
"description": "Primary email address used for onboarding communications."
},
"secondaryEmailId": {
"type": "string",
"nullable": true,
"description": "Secondary or alternate email address."
},
"officialEmailId": {
"type": "string",
"nullable": true,
"description": "Work or official email address when provided."
},
"dateOfBirth": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Date of birth as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"joiningDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Expected or planned joining date as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"contacts": {
"type": "array",
"description": "Ordered list of phone contact entries (e.g. primary and secondary); each item may include type, dial code, and number.",
"items": {
"CandidateContact": {
"type": "object",
"description": "A single phone contact line, distinguished by type (for example primary vs secondary).",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Contact slot or role, such as primary or secondary."
},
"phoneNumber": {
"type": "string",
"nullable": true,
"description": "Local phone number without country prefix (when present)."
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91)."
}
}
}
}
},
"identificationDetails": {
"type": "array",
"description": "Government or employer identification documents associated with the candidate.",
"items": {
"CandidateIdentification": {
"type": "object",
"description": "One identification document or credential record.",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Kind of identification (e.g. aadhaar, passport)."
},
"number": {
"type": "string",
"nullable": true,
"description": "Document or identification number."
},
"location": {
"type": "string",
"nullable": true,
"description": "Issuing location or jurisdiction, if applicable."
},
"issuedDate": {
"type": "string",
"nullable": true,
"description": "Issue date as returned by the source (empty string if unknown)."
},
"expiryDate": {
"type": "string",
"nullable": true,
"description": "Expiry date as returned by the source (empty string if unknown or not applicable)."
},
"status": {
"type": "string",
"nullable": true,
"description": "Verification or document status when provided."
}
}
}
}
},
"education": {
"type": "array",
"description": "Education history entries.",
"items": {
"CandidateEducation": {
"type": "object",
"description": "A single education record.",
"properties": {
"degree": {
"type": "string",
"nullable": true,
"description": "Degree or qualification title."
},
"fieldOfStudy": {
"type": "string",
"nullable": true,
"description": "Major or field of study."
},
"schoolName": {
"type": "string",
"nullable": true,
"description": "School or institute name."
},
"schoolAndUniversity": {
"type": "string",
"nullable": true,
"description": "Combined campus, university, or location label when provided."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Program start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Program end date (format as returned by the source)."
},
"isHighEducation": {
"type": "boolean",
"nullable": true,
"description": "Whether this entry is marked as the highest level of education."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region for the institution."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country for the institution."
}
}
}
}
},
"experience": {
"type": "array",
"description": "Employment history entries.",
"items": {
"CandidateExperience": {
"type": "object",
"description": "A single employment history record.",
"properties": {
"company": {
"type": "string",
"nullable": true,
"description": "Employer or organization name."
},
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Job title at the employer."
},
"role": {
"type": "string",
"nullable": true,
"description": "Role or function (may mirror job title)."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Work location for this role."
},
"isCurrent": {
"type": "string",
"nullable": true,
"description": "Whether this is the current employer (e.g. yes or no as stored in source data)."
},
"industry": {
"type": "string",
"nullable": true,
"description": "Industry sector when captured."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Employment start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Employment end date (format as returned by the source); empty if current."
}
}
}
}
},
"address": {
"type": "object",
"description": "Current and permanent address details.",
"allOf": [
{
"CandidateAddressBlock": {
"type": "object",
"description": "Current and permanent address lines. Both keys are always present; each value is always a StructuredAddress (never null at this level).",
"properties": {
"currentAddress": {
"description": "Current address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
},
"permanentAddress": {
"description": "Permanent address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
}
}
}
}
]
},
"additionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom attributes for the candidate; keys and value types depend on configuration.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}
}
]
},
"jobDetails": {
"type": "object",
"description": "Job details and job additional fields for the candidate's job.",
"allOf": [
{
"JobDetails": {
"type": "object",
"description": "Job or requisition context: top-level fields for common attributes, plus additionalFields for ATS, recruiter or hiring-manager contacts, department, and other tenant-specific job metadata.",
"properties": {
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Title of the job or requisition."
},
"jobId": {
"type": "string",
"nullable": true,
"description": "Internal or external job identifier."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Primary job location label or free text."
},
"jobCategory": {
"type": "string",
"nullable": true,
"description": "Category or family of the role."
},
"positionCode": {
"type": "string",
"nullable": true,
"description": "Position or requisition code when used by the tenant."
},
"positionTitle": {
"type": "string",
"nullable": true,
"description": "Position title as distinct from job title when both are maintained."
},
"department": {
"type": "string",
"nullable": true,
"description": "Hiring department or cost center name."
},
"additionalFields": {
"type": "object",
"description": "Tenant specific custom fields.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}
}
]
}
}
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| status | integer | HTTP status code indicating success. |
| message | string | Outcome message for the client (e.g. confirmation that candidate data was fetched). |
| data | object | Onboarding data for the requested candidate. |
| 0 | object | OnboardingData |
copied!{
"type": "object",
"description": "Payload returned for a successful candidate onboarding fetch: profile and contact data under candidateDetails, and requisition or job context under jobDetails.",
"properties": {
"candidateDetails": {
"type": "object",
"description": "Candidate details and additional fields for the candidate.",
"allOf": [
{
"CandidateDetails": {
"type": "object",
"description": "Candidate profile: emails, phone contacts, identification, education, work history, address, and tenant-specific custom fields.",
"properties": {
"firstName": {
"type": "string",
"nullable": true,
"description": "Candidate given name."
},
"middleName": {
"type": "string",
"nullable": true,
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "Candidate family name."
},
"gender": {
"type": "string",
"nullable": true,
"description": "Gender or gender identity as stored for the candidate."
},
"primaryEmailId": {
"type": "string",
"nullable": true,
"description": "Primary email address used for onboarding communications."
},
"secondaryEmailId": {
"type": "string",
"nullable": true,
"description": "Secondary or alternate email address."
},
"officialEmailId": {
"type": "string",
"nullable": true,
"description": "Work or official email address when provided."
},
"dateOfBirth": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Date of birth as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"joiningDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Expected or planned joining date as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"contacts": {
"type": "array",
"description": "Ordered list of phone contact entries (e.g. primary and secondary); each item may include type, dial code, and number.",
"items": {
"CandidateContact": {
"type": "object",
"description": "A single phone contact line, distinguished by type (for example primary vs secondary).",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Contact slot or role, such as primary or secondary."
},
"phoneNumber": {
"type": "string",
"nullable": true,
"description": "Local phone number without country prefix (when present)."
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91)."
}
}
}
}
},
"identificationDetails": {
"type": "array",
"description": "Government or employer identification documents associated with the candidate.",
"items": {
"CandidateIdentification": {
"type": "object",
"description": "One identification document or credential record.",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Kind of identification (e.g. aadhaar, passport)."
},
"number": {
"type": "string",
"nullable": true,
"description": "Document or identification number."
},
"location": {
"type": "string",
"nullable": true,
"description": "Issuing location or jurisdiction, if applicable."
},
"issuedDate": {
"type": "string",
"nullable": true,
"description": "Issue date as returned by the source (empty string if unknown)."
},
"expiryDate": {
"type": "string",
"nullable": true,
"description": "Expiry date as returned by the source (empty string if unknown or not applicable)."
},
"status": {
"type": "string",
"nullable": true,
"description": "Verification or document status when provided."
}
}
}
}
},
"education": {
"type": "array",
"description": "Education history entries.",
"items": {
"CandidateEducation": {
"type": "object",
"description": "A single education record.",
"properties": {
"degree": {
"type": "string",
"nullable": true,
"description": "Degree or qualification title."
},
"fieldOfStudy": {
"type": "string",
"nullable": true,
"description": "Major or field of study."
},
"schoolName": {
"type": "string",
"nullable": true,
"description": "School or institute name."
},
"schoolAndUniversity": {
"type": "string",
"nullable": true,
"description": "Combined campus, university, or location label when provided."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Program start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Program end date (format as returned by the source)."
},
"isHighEducation": {
"type": "boolean",
"nullable": true,
"description": "Whether this entry is marked as the highest level of education."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region for the institution."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country for the institution."
}
}
}
}
},
"experience": {
"type": "array",
"description": "Employment history entries.",
"items": {
"CandidateExperience": {
"type": "object",
"description": "A single employment history record.",
"properties": {
"company": {
"type": "string",
"nullable": true,
"description": "Employer or organization name."
},
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Job title at the employer."
},
"role": {
"type": "string",
"nullable": true,
"description": "Role or function (may mirror job title)."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Work location for this role."
},
"isCurrent": {
"type": "string",
"nullable": true,
"description": "Whether this is the current employer (e.g. yes or no as stored in source data)."
},
"industry": {
"type": "string",
"nullable": true,
"description": "Industry sector when captured."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Employment start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Employment end date (format as returned by the source); empty if current."
}
}
}
}
},
"address": {
"type": "object",
"description": "Current and permanent address details.",
"allOf": [
{
"CandidateAddressBlock": {
"type": "object",
"description": "Current and permanent address lines. Both keys are always present; each value is always a StructuredAddress (never null at this level).",
"properties": {
"currentAddress": {
"description": "Current address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
},
"permanentAddress": {
"description": "Permanent address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
}
}
}
}
]
},
"additionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom attributes for the candidate; keys and value types depend on configuration.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}
}
]
},
"jobDetails": {
"type": "object",
"description": "Job details and job additional fields for the candidate's job.",
"allOf": [
{
"JobDetails": {
"type": "object",
"description": "Job or requisition context: top-level fields for common attributes, plus additionalFields for ATS, recruiter or hiring-manager contacts, department, and other tenant-specific job metadata.",
"properties": {
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Title of the job or requisition."
},
"jobId": {
"type": "string",
"nullable": true,
"description": "Internal or external job identifier."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Primary job location label or free text."
},
"jobCategory": {
"type": "string",
"nullable": true,
"description": "Category or family of the role."
},
"positionCode": {
"type": "string",
"nullable": true,
"description": "Position or requisition code when used by the tenant."
},
"positionTitle": {
"type": "string",
"nullable": true,
"description": "Position title as distinct from job title when both are maintained."
},
"department": {
"type": "string",
"nullable": true,
"description": "Hiring department or cost center name."
},
"additionalFields": {
"type": "object",
"description": "Tenant specific custom fields.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| candidateDetails | object | Candidate details and additional fields for the candidate. |
| 0 | object | CandidateDetails |
| jobDetails | object | Job details and job additional fields for the candidate's job. |
| 0 | object | JobDetails |
copied!{
"type": "object",
"description": "Candidate profile: emails, phone contacts, identification, education, work history, address, and tenant-specific custom fields.",
"properties": {
"firstName": {
"type": "string",
"nullable": true,
"description": "Candidate given name."
},
"middleName": {
"type": "string",
"nullable": true,
"description": "Candidate middle name."
},
"lastName": {
"type": "string",
"nullable": true,
"description": "Candidate family name."
},
"gender": {
"type": "string",
"nullable": true,
"description": "Gender or gender identity as stored for the candidate."
},
"primaryEmailId": {
"type": "string",
"nullable": true,
"description": "Primary email address used for onboarding communications."
},
"secondaryEmailId": {
"type": "string",
"nullable": true,
"description": "Secondary or alternate email address."
},
"officialEmailId": {
"type": "string",
"nullable": true,
"description": "Work or official email address when provided."
},
"dateOfBirth": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Date of birth as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"joiningDate": {
"type": "string",
"format": "date",
"nullable": true,
"description": "Expected or planned joining date as an ISO 8601 calendar date (YYYY-MM-DD)."
},
"contacts": {
"type": "array",
"description": "Ordered list of phone contact entries (e.g. primary and secondary); each item may include type, dial code, and number.",
"items": {
"CandidateContact": {
"type": "object",
"description": "A single phone contact line, distinguished by type (for example primary vs secondary).",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Contact slot or role, such as primary or secondary."
},
"phoneNumber": {
"type": "string",
"nullable": true,
"description": "Local phone number without country prefix (when present)."
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91)."
}
}
}
}
},
"identificationDetails": {
"type": "array",
"description": "Government or employer identification documents associated with the candidate.",
"items": {
"CandidateIdentification": {
"type": "object",
"description": "One identification document or credential record.",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Kind of identification (e.g. aadhaar, passport)."
},
"number": {
"type": "string",
"nullable": true,
"description": "Document or identification number."
},
"location": {
"type": "string",
"nullable": true,
"description": "Issuing location or jurisdiction, if applicable."
},
"issuedDate": {
"type": "string",
"nullable": true,
"description": "Issue date as returned by the source (empty string if unknown)."
},
"expiryDate": {
"type": "string",
"nullable": true,
"description": "Expiry date as returned by the source (empty string if unknown or not applicable)."
},
"status": {
"type": "string",
"nullable": true,
"description": "Verification or document status when provided."
}
}
}
}
},
"education": {
"type": "array",
"description": "Education history entries.",
"items": {
"CandidateEducation": {
"type": "object",
"description": "A single education record.",
"properties": {
"degree": {
"type": "string",
"nullable": true,
"description": "Degree or qualification title."
},
"fieldOfStudy": {
"type": "string",
"nullable": true,
"description": "Major or field of study."
},
"schoolName": {
"type": "string",
"nullable": true,
"description": "School or institute name."
},
"schoolAndUniversity": {
"type": "string",
"nullable": true,
"description": "Combined campus, university, or location label when provided."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Program start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Program end date (format as returned by the source)."
},
"isHighEducation": {
"type": "boolean",
"nullable": true,
"description": "Whether this entry is marked as the highest level of education."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region for the institution."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country for the institution."
}
}
}
}
},
"experience": {
"type": "array",
"description": "Employment history entries.",
"items": {
"CandidateExperience": {
"type": "object",
"description": "A single employment history record.",
"properties": {
"company": {
"type": "string",
"nullable": true,
"description": "Employer or organization name."
},
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Job title at the employer."
},
"role": {
"type": "string",
"nullable": true,
"description": "Role or function (may mirror job title)."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Work location for this role."
},
"isCurrent": {
"type": "string",
"nullable": true,
"description": "Whether this is the current employer (e.g. yes or no as stored in source data)."
},
"industry": {
"type": "string",
"nullable": true,
"description": "Industry sector when captured."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Employment start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Employment end date (format as returned by the source); empty if current."
}
}
}
}
},
"address": {
"type": "object",
"description": "Current and permanent address details.",
"allOf": [
{
"CandidateAddressBlock": {
"type": "object",
"description": "Current and permanent address lines. Both keys are always present; each value is always a StructuredAddress (never null at this level).",
"properties": {
"currentAddress": {
"description": "Current address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
},
"permanentAddress": {
"description": "Permanent address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
}
}
}
}
]
},
"additionalFields": {
"type": "object",
"description": "Tenant- or form-specific custom attributes for the candidate; keys and value types depend on configuration.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| firstName | string | Candidate given name. |
| middleName | string | Candidate middle name. |
| lastName | string | Candidate family name. |
| gender | string | Gender or gender identity as stored for the candidate. |
| primaryEmailId | string | Primary email address used for onboarding communications. |
| secondaryEmailId | string | Secondary or alternate email address. |
| officialEmailId | string | Work or official email address when provided. |
| dateOfBirth | string | Date of birth as an ISO 8601 calendar date (YYYY-MM-DD). |
| joiningDate | string | Expected or planned joining date as an ISO 8601 calendar date (YYYY-MM-DD). |
| contacts | array | CandidateContact |
| identificationDetails | array | CandidateIdentification |
| education | array | CandidateEducation |
| experience | array | CandidateExperience |
| address | object | Current and permanent address details. |
| 0 | object | CandidateAddressBlock |
| additionalFields | object | Tenant- or form-specific custom attributes for the candidate; keys and value types depend on configuration. |
| 0 | object | AdditionalFields |
copied!{
"type": "object",
"description": "A single phone contact line, distinguished by type (for example primary vs secondary).",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Contact slot or role, such as primary or secondary."
},
"phoneNumber": {
"type": "string",
"nullable": true,
"description": "Local phone number without country prefix (when present)."
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91)."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| type | string | Contact slot or role, such as primary or secondary. |
| phoneNumber | string | Local phone number without country prefix (when present). |
| countryCode | string | Country or dialing code identifier for the number (format may be tenant-specific, e.g. IND_91). |
copied!{
"type": "object",
"description": "One identification document or credential record.",
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Kind of identification (e.g. aadhaar, passport)."
},
"number": {
"type": "string",
"nullable": true,
"description": "Document or identification number."
},
"location": {
"type": "string",
"nullable": true,
"description": "Issuing location or jurisdiction, if applicable."
},
"issuedDate": {
"type": "string",
"nullable": true,
"description": "Issue date as returned by the source (empty string if unknown)."
},
"expiryDate": {
"type": "string",
"nullable": true,
"description": "Expiry date as returned by the source (empty string if unknown or not applicable)."
},
"status": {
"type": "string",
"nullable": true,
"description": "Verification or document status when provided."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| type | string | Kind of identification (e.g. aadhaar, passport). |
| number | string | Document or identification number. |
| location | string | Issuing location or jurisdiction, if applicable. |
| issuedDate | string | Issue date as returned by the source (empty string if unknown). |
| expiryDate | string | Expiry date as returned by the source (empty string if unknown or not applicable). |
| status | string | Verification or document status when provided. |
copied!{
"type": "object",
"description": "A single education record.",
"properties": {
"degree": {
"type": "string",
"nullable": true,
"description": "Degree or qualification title."
},
"fieldOfStudy": {
"type": "string",
"nullable": true,
"description": "Major or field of study."
},
"schoolName": {
"type": "string",
"nullable": true,
"description": "School or institute name."
},
"schoolAndUniversity": {
"type": "string",
"nullable": true,
"description": "Combined campus, university, or location label when provided."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Program start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Program end date (format as returned by the source)."
},
"isHighEducation": {
"type": "boolean",
"nullable": true,
"description": "Whether this entry is marked as the highest level of education."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region for the institution."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country for the institution."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| degree | string | Degree or qualification title. |
| fieldOfStudy | string | Major or field of study. |
| schoolName | string | School or institute name. |
| schoolAndUniversity | string | Combined campus, university, or location label when provided. |
| startDate | string | Program start date (format as returned by the source). |
| endDate | string | Program end date (format as returned by the source). |
| isHighEducation | boolean | Whether this entry is marked as the highest level of education. |
| state | string | State or region for the institution. |
| country | string | Country for the institution. |
copied!{
"type": "object",
"description": "A single employment history record.",
"properties": {
"company": {
"type": "string",
"nullable": true,
"description": "Employer or organization name."
},
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Job title at the employer."
},
"role": {
"type": "string",
"nullable": true,
"description": "Role or function (may mirror job title)."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Work location for this role."
},
"isCurrent": {
"type": "string",
"nullable": true,
"description": "Whether this is the current employer (e.g. yes or no as stored in source data)."
},
"industry": {
"type": "string",
"nullable": true,
"description": "Industry sector when captured."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Employment start date (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "Employment end date (format as returned by the source); empty if current."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| company | string | Employer or organization name. |
| jobTitle | string | Job title at the employer. |
| role | string | Role or function (may mirror job title). |
| jobLocation | string | Work location for this role. |
| isCurrent | string | Whether this is the current employer (e.g. yes or no as stored in source data). |
| industry | string | Industry sector when captured. |
| startDate | string | Employment start date (format as returned by the source). |
| endDate | string | Employment end date (format as returned by the source); empty if current. |
copied!{
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| addressLine1 | string | First line of the street address. |
| addressLine2 | string | Second line of the street address. |
| city | string | City. |
| zipCode | string | Postal or ZIP code. |
| country | string | Country. |
| state | string | State or region. |
| startDate | string | Start date associated with this address (format as returned by the source). |
| endDate | string | End date associated with this address (format as returned by the source). |
copied!{
"type": "object",
"description": "Current and permanent address lines. Both keys are always present; each value is always a StructuredAddress (never null at this level).",
"properties": {
"currentAddress": {
"description": "Current address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
},
"permanentAddress": {
"description": "Permanent address of the candidate.",
"allOf": [
{
"StructuredAddress": {
"type": "object",
"description": "Structured postal address, including optional validity dates for that address.",
"properties": {
"addressLine1": {
"type": "string",
"nullable": true,
"description": "First line of the street address."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Second line of the street address."
},
"city": {
"type": "string",
"nullable": true,
"description": "City."
},
"zipCode": {
"type": "string",
"nullable": true,
"description": "Postal or ZIP code."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country."
},
"state": {
"type": "string",
"nullable": true,
"description": "State or region."
},
"startDate": {
"type": "string",
"nullable": true,
"description": "Start date associated with this address (format as returned by the source)."
},
"endDate": {
"type": "string",
"nullable": true,
"description": "End date associated with this address (format as returned by the source)."
}
}
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| 0 | object | StructuredAddress |
copied!{
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}Properties
| Name | Type |
|---|
copied!{
"type": "object",
"description": "Job or requisition context: top-level fields for common attributes, plus additionalFields for ATS, recruiter or hiring-manager contacts, department, and other tenant-specific job metadata.",
"properties": {
"jobTitle": {
"type": "string",
"nullable": true,
"description": "Title of the job or requisition."
},
"jobId": {
"type": "string",
"nullable": true,
"description": "Internal or external job identifier."
},
"jobLocation": {
"type": "string",
"nullable": true,
"description": "Primary job location label or free text."
},
"jobCategory": {
"type": "string",
"nullable": true,
"description": "Category or family of the role."
},
"positionCode": {
"type": "string",
"nullable": true,
"description": "Position or requisition code when used by the tenant."
},
"positionTitle": {
"type": "string",
"nullable": true,
"description": "Position title as distinct from job title when both are maintained."
},
"department": {
"type": "string",
"nullable": true,
"description": "Hiring department or cost center name."
},
"additionalFields": {
"type": "object",
"description": "Tenant specific custom fields.",
"allOf": [
{
"AdditionalFields": {
"type": "object",
"nullable": true,
"description": "Tenant- or form-specific custom fields (keys and value types vary by configuration).",
"additionalProperties": true
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| jobTitle | string | Title of the job or requisition. |
| jobId | string | Internal or external job identifier. |
| jobLocation | string | Primary job location label or free text. |
| jobCategory | string | Category or family of the role. |
| positionCode | string | Position or requisition code when used by the tenant. |
| positionTitle | string | Position title as distinct from job title when both are maintained. |
| department | string | Hiring department or cost center name. |
| additionalFields | object | Tenant specific custom fields. |
| 0 | object | AdditionalFields |
copied!{
"type": "object",
"description": "Successful response for candidate attachments list. The data field is a JSON array of attachment items.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success.",
"example": 200
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Attachments list fetched successfully"
},
"data": {
"type": "array",
"description": "List of files attached to the candidate for onboarding.",
"items": {
"CandidateAttachment": {
"type": "object",
"description": "Metadata for a single file attached to the candidate.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Unique attachment identifier."
},
"attachmentFileName": {
"type": "string",
"description": "Stored or display file name for the document."
},
"attachmentType": {
"type": "string",
"description": "Document type."
},
"attachmentUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Uploaded date."
}
}
}
}
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| status | integer | HTTP status code indicating success. |
| message | string | Outcome message for the client. |
| data | array | CandidateAttachment |
copied!{
"type": "object",
"description": "Metadata for a single file attached to the candidate.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Unique attachment identifier."
},
"attachmentFileName": {
"type": "string",
"description": "Stored or display file name for the document."
},
"attachmentType": {
"type": "string",
"description": "Document type."
},
"attachmentUploadedAt": {
"type": "string",
"format": "date-time",
"description": "Uploaded date."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| attachmentId | string | Unique attachment identifier. |
| attachmentFileName | string | Stored or display file name for the document. |
| attachmentType | string | Document type. |
| attachmentUploadedAt | string | Uploaded date. |
copied!{
"type": "object",
"description": "Successful response for attachment signed URL.",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code indicating success.",
"example": 200
},
"message": {
"type": "string",
"description": "Outcome message for the client.",
"example": "Attachment fetched successfully"
},
"data": {
"type": "object",
"description": "Download details for the requested attachment.",
"allOf": [
{
"CandidateAttachmentSignedUrlData": {
"type": "object",
"description": "Signed download details for a single attachment.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Attachment identifier."
},
"attachmentUrl": {
"type": "string",
"format": "uri",
"description": "Time-limited signed URL to download the file; the URL expires after 5 minutes."
},
"attachmentContentType": {
"type": "string",
"description": "MIME type stored with the document (e.g. application/pdf)."
},
"attachmentSize": {
"type": "integer",
"format": "int64",
"description": "File size in bytes."
}
}
}
}
]
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| status | integer | HTTP status code indicating success. |
| message | string | Outcome message for the client. |
| data | object | Download details for the requested attachment. |
| 0 | object | CandidateAttachmentSignedUrlData |
copied!{
"type": "object",
"description": "Signed download details for a single attachment.",
"properties": {
"attachmentId": {
"type": "string",
"description": "Attachment identifier."
},
"attachmentUrl": {
"type": "string",
"format": "uri",
"description": "Time-limited signed URL to download the file; the URL expires after 5 minutes."
},
"attachmentContentType": {
"type": "string",
"description": "MIME type stored with the document (e.g. application/pdf)."
},
"attachmentSize": {
"type": "integer",
"format": "int64",
"description": "File size in bytes."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| attachmentId | string | Attachment identifier. |
| attachmentUrl | string | Time-limited signed URL to download the file; the URL expires after 5 minutes. |
| attachmentContentType | string | MIME type stored with the document (e.g. application/pdf). |
| attachmentSize | integer | File size in bytes. |
copied!{
"type": "object",
"description": "Error payload for failed requests (e.g. 400, 404, 500).",
"properties": {
"status": {
"type": "integer",
"description": "HTTP status code for the error."
},
"message": {
"type": "string",
"description": "Description of the error."
}
}
}Properties
| Name | Type | Description |
|---|---|---|
| status | integer | HTTP status code for the error. |
| message | string | Description of the error. |