Flow
Service used to query flows and manage candidates assigned to flows.
List flows
Returns the list of all active flows.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows
     -H "Authorization: API_KEY"
Response Information
id
Unique id of the flow.
name
Name of the flow.
Sample Response
{
  "status": 0,
  "data": [
    {
      "id": "rm2trc6e9wefypxcpkrfwwtdwq",
      "name": "Flow 01"
    },
    {
      "id": "4tx3hweu8v22wbzb83r2hb287w",
      "name": "Flow 02"
    }
  ]
}
Error Responses
Error messages can vary. More specific error information may be included.
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get flow
Returns the details of a flow.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
Unique id of the flow.
languageoptional
If the assessment and status names on the flow are multilingual, their names can be get according to the selected language. Default value is English.
Possible values
ValueText
0English
1Turkish
255Multilangual
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/54u4n7dlh354ybnmsse9lhg2mz
https://api-test.hrpeak.com/v2/flows/wr99bz89zev2wdv5fmvwtf9sp3/?language=0
Response Information
name
Name of the flow.
steps
There may be more than one step on the flow. List of steps in the flow. This property value is an array.
id
Unique id of the step.
name
Name of the step.
type
Type of the step. Data type is integer.
Possible values
ValueText
0Assessment Center
1Interview
2COmpensation Planning & Offer
3Upload Document & Control
4Recruitment & Onboarding
5Shortlisting
99Custom
assessments
If the step type is “Assessment Center”, list of assessments in the step. Other step types do not have this property. This property value is an array.
id
Unique id of the assessment. If the same assessment is attached to other steps or other flows, the id value is the same in all of them.
name
Name of the assessment.
type
Type of the assessments. Data type is integer.
Possible values
ValueText
0Test
1Survey
2Video Interview
3Inventory
4Gamification
5Role Play
6Case Study
7Project
8Presentation
9Situational Judgement Test
custom_status_list
If the step type is “Custom”, list of custom statuses in the step. Other step types do not have this property. This property value is an array.
id
Unique id of the custom status. If the same status is attached to other steps or other flows, the id value is the same in all of them.
name
Name of the custom status.
Sample Response
It's a 3 step flow.
{
  "status": 0,
  "data": {
    "name": "Flow 01",
    "steps": [
      {
        "id": "q7n3tp7w94nzwbzr4bv4cejmfs",
        "name": "Step 01",
        "type": 0,
        "assessments": [
          {
            "id": "yrmauv6d3kekwdx3ve6ce2lesq",
            "name": "English Proficiency Test",
            "type": 0
          }
        ]
      },
      {
        "id": "qy3jyb3wzleryjmbfwbyyf5efx",
        "name": "Step 02",
        "type": 99,
        "custom_status_list": [
          {
            "id": "us3rr3u2vathw2l893r7ftdhms",
            "name": "Status 01"
          },
          {
            "id": "byahgkvqduzdwbckhfj5rhmlu2",
            "name": "Status 02"
          }
        ]
      },
      {
        "id": "cblqznvww8wgydcdzqqfjksz5w",
        "name": "Step 03",
        "type": 1
      }
    ]
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Add candidate to step assessment
Invite candidate for assessments.
Request Information
POSThttps://api-test.hrpeak.com/v2/flows/add_candidate_to_step_assessment
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl -X POST https://api-test.hrpeak.com/v2/flows/add_candidate_to_step_assessment
     -H "Authorization: API_KEY"
     -d {JSON body}
JSON body object
flow_idrequired
Unique id of the flow.
step_idoptional
Unique id of the step. If the candidate does not want to be invited to the first step on the flow, you can specify the step to which the candidate will be added. This property value can be left blank if there is only one step on the flow or if the candidate will be added to the first step.
full_namerequired
Full name of the candidate. Max length is 100.
email_addressoptional
The candidate's email address. The invitation e-mail will be sent to this e-mail address. Max length is 50.
mobile_phone_numberoptional
The candidate's mobile phone number. The invitation SMS will be sent to this phone number. It is recommended that you also add the country code to the beginning of the phone number. Max length is 50.
external_idoptional
A unique string to associate the candidate to an external record. If there is a candidate you invited with the same external id before, a new candidate record is not created, and assessments are assigned to the current candidate. Max length is 50.
send_messageoptional
Send invitation email and SMS to candidate? Data type is boolean. Default value is true.
email_subjectoptional
Customize the invitation email subject. If no value is specified, the email is sent with the default subject. Max length is 255.
email_contentoptional
Customize the invitation email content. Access code, access link and access dates are automatically added under the email content. If no value is specified, the email is sent with the default content. Max length is 1024.
sms_contentoptional
Customize the invitation SMS content. Access code and access link are automatically added after the SMS content. If no value is specified, the SMS is sent with the default content. Max length is 128.
languageoptional
Candidate language. Invitation messages are sent in this language and the candidate uses the system with this language. The language value can be left blank if you are using the application monolingual. Data type is integer.
Possible values
ValueText
0English
1Turkish
start_dateoptional
The candidate's access time to assessments. If a value is specified, the candidate can begin assessments after the specified date. Data type is datetime.
end_dateoptional
The end date of the candidate's access to assessments. If a value is specified, the candidate cannot start a new assessment after the specified date. Data type is datetime.
requisition_idoptional
Assign the candidate to a requisition. Requisitions can be listed with the API.
job_idoptional
Assign the candidate to a job posting. Job postings can be listed with the API.
dataoptional
Store additional data about the candidate. This data is sent back when candidate data is received via the "Get candidate data" method. Max length is 4096.
generate_report_linkoptional
Create link to access candidate flow report? The generated link is attached in the response. Data type is boolean. Default value is false.
report_link_anonymous_accessoptional
Provide anonymous access to the candidate report via the created link? Data type is boolean. Default value is false.
report_link_durationoptional
If anonymous access is granted, you can specify how many days the link will be valid. Data type is integer. Default value is 30 days.
Request Body Sample
{
  "flow_id": "yqnyrn3dgcd8ywmzm63x2tt9kw",
  "full_name": "Maria Simith",
  "email_address": "[email protected]",
  "mobile_phone_number": "+14155552671"
}
{
  "flow_id": "v9dbrdsunl4gyhvhupwqfv8m4q",
  "full_name": "Maria Simith",
  "external_id": "A0001",
  "send_message": false,
  "language": 0,
  "end_date": "2026-07-15T21:59:00Z",
  "generate_report_link": true,
  "report_link_anonymous_access": true,
  "report_link_duration": 14
}
Response Information
tracking_number
Candidate tracking number. By storing the tracking number, you can access the candidate's flow details later with this number.
access_code
The access code that the candidate will use to access the assessments. The access code is automatically added to the sent message.
access_link
The access link that the candidate will use to access assessments. The access link is automatically added to the sent message. The candidate can access the assessments via the website using the access code or by following the access link.
report_link
The link to use to access the candidate report. If link generation property is set in the request, this value is included in the response.
Sample Response
{
  "status": 0,
  "data": {
    "tracking_number": "uev6wrr8rec5y6czc6vnwy7vms",
    "access_code": "ABCDEF",
    "access_link": "https://..."
  }
}
Response with report link
{
  "status": 0,
  "data": {
    "tracking_number": "y598r8u4tqkxwfxnqdymuqdwqz",
    "access_code": "ABCDEF",
    "access_link": "https://...",
    "report_link": "https://..."
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Flow not found
{
  "status": 1,
  "error_message": "Flow is not found."
}
Flow is empty
{
  "status": 2,
  "error_message": "Flow is empty."
}
Flow step is not found
{
  "status": 3,
  "error_message": "Step is not found."
}
Flow candidate add only assessment
{
  "status": 4,
  "error_message": "Candidate can add only to assessment step."
}
Flow step is empty
{
  "status": 5,
  "error_message": "Step is empty."
}
Flow credit expired
{
  "status": 6,
  "error_message": "Credit expired."
}
Requisition not found
{
  "status": 7,
  "error_message": "Requisition item is not found."
}
Job not found
{
  "status": 8,
  "error_message": "Job posting is not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get candidate status
Get the current status of the candidate.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/candidate_status/{tracking_number}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/candidate_status/{tracking_number}
     -H "Authorization: API_KEY"
URI parameters
tracking_numberrequired
Candidate tracking number. The candidate tracking number is included in the response of the candidate invitation method.
languageoptional
If the status names on the flow are multilingual, their names can be get according to the selected language. Data type is integer. Default value is English.
Possible values
ValueText
0English
1Turkish
255Multilangual
generate_report_linkoptional
Create link to access candidate flow report? The generated link is attached in the response. Data type is boolean. Default value is false.
report_link_anonymous_accessoptional
Provide anonymous access to the candidate report via the created link? Data type is boolean. Default value is false.
report_link_durationoptional
If anonymous access is granted, you can specify how many days the link will be valid. Data type is integer. Default value is 30 days.
report_languageoptional
The report accessed via the generated link and JSON data may be in different languages. "report_language" is the language of the report to be accessed via the generated link. If the language is not specified, the report link is created by looking at the value sent with the "language" parameter. Data type is integer.
Possible values
ValueText
0English
1Turkish
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/candidate_status/dksmfcfv6m5gy8zqwgtv8yapkq
Generate anonymous access report link.
https://api-test.hrpeak.com/v2/flows/candidate_status/f3n66fw4ab9twevgcd7guwuct2/?generate_report_link=true&report_link_anonymous_access=true
Response Information
flow
The flow the candidate is in.
id
Unique id of the flow.
name
Name of the flow.
step
The flow step the candidate is in.
id
Unique id of the step.
name
Name of the step.
type
Type of the step. Data type is integer.
Possible values
ValueText
0Assessment Center
1Interview
2COmpensation Planning & Offer
3Upload Document & Control
4Recruitment & Onboarding
5Shortlisting
99Custom
status
Candidata status information.
id
Unique id of the status.
name
Name of the status.
code
Candidata status information. The status code can be empty if the candidate is in the custom step.
Possible values
ValueText
assesstment_invitedCandidate in the assessment step.
assesstment_ongoingCandidate in the assessment step.
assesstment_completedCandidate in the assessment step.
assesstment_positiveCandidate in the assessment step.
assesstment_negativeCandidate in the assessment step.
interview_invitedCandidate in the interview step.
interview_completedCandidate in the interview step.
interview_positiveCandidate in the interview step.
interview_negativeCandidate in the interview step.
interview_cancelledCandidate in the interview step.
interview_candidate_did_not_comeCandidate in the interview step.
interview_appointment_inviteCandidate in the interview step.
interview_appointment_cancelled_candidateCandidate in the interview step.
offer_will_sentCandidate in the offer step.
offer_sentCandidate in the offer step.
offer_acceptedCandidate in the offer step.
offer_rejectedCandidate in the offer step.
document_sentCandidate in the document control step.
document_uploadedCandidate in the document control step.
document_checkedCandidate in the document control step.
document_incompleteCandidate in the document control step.
document_negativeCandidate in the document control step.
recruitment_hiredCandidate in the recruitment step.
recruitment_quitCandidate in the recruitment step.
recruitment_yet_to_startCandidate in the recruitment step.
long_short_list_to_be_sharedCandidate in the Shortlisting step.
long_short_list_sharedCandidate in the Shortlisting step.
long_short_list_positiveCandidate in the Shortlisting step.
long_short_list_negativeCandidate in the Shortlisting step.
report_link
The link to use to access the candidate report. If link generation property is set in the request, this value is included in the response.
Sample Response
{
  "status": 0,
  "data": {
    "flow": {
      "id": "uta2zbxu9xbwykmb6nayqbm6gq",
      "name": "Flow 01"
    },
    "step": {
      "id": "hrq6tm5sfef8yul26d6a4qbrgz",
      "type": 0,
      "name": "Step 01"
    },
    "status": {
      "id": "e2wmgme3ug7bwlnwjxss4vv3jq",
      "name": "Completed",
      "code": "assesstment_completed"
    }
  }
}
Candidate in the custom step.
{
  "status": 0,
  "data": {
    "flow": {
      "id": "3xl3b6rkk5zdwsbm7xfvycv5yq",
      "name": "Flow 02"
    },
    "step": {
      "id": "7p4quvrqc4wjyxmeg2c7ysu7v3",
      "type": 99,
      "name": "Step 02"
    },
    "status": {
      "id": "xkdsvxpfccuzymxaagkrbbjvf2",
      "name": "Status 01"
    },
    "report_link": "https://..."
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get candidate data
Get candidate flow data.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/candidate_data/{tracking_number}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/candidate_data/{tracking_number}
     -H "Authorization: API_KEY"
URI parameters
tracking_numberrequired
Candidate tracking number. The candidate tracking number is included in the response of the candidate invitation method.
languageoptional
If the assessment and status names on the flow are multilingual, their names can be get according to the selected language. Data type is integer. Default value is English.
Possible values
ValueText
0English
1Turkish
255Multilangual
generate_report_linkoptional
Create access links to candidate assessments and candidate flow report? The generated links are attached in the response. Data type is boolean. Default value is false.
report_link_anonymous_accessoptional
Provide anonymous access to the candidate report via the created link? Data type is boolean. Default value is false.
report_link_durationoptional
If anonymous access is granted, you can specify how many days the link will be valid. Data type is integer. Default value is 30 days.
report_languageoptional
The report accessed via the generated link and JSON data may be in different languages. "report_language" is the language of the report to be accessed via the generated link. If the language is not specified, the report link is created by looking at the value sent with the "language" parameter. Data type is integer.
Possible values
ValueText
0English
1Turkish
pit_position_idoptional
If the candidate has taken the PiT assessment, the PiT position definition required for calculating the candidate's position fit score. If any, response data contains PiT position score. PiT position list can be retrieved via API.
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/candidate_data/3z5v9ny3zj27ygl39khxmcqfl3
Generate report links with anonymous access.
https://api-test.hrpeak.com/v2/flows/candidate_data/8pt8ukmgh2u6wrzsft3w7yqnjs/?generate_report_link=true&report_link_anonymous_access=true
Response Information
candidate
Candidate information
full_name
Name of the candidate.
email_address
The candidate's email address.
mobile_phone_number
The candidate's mobile phone number.
access_code
The access code that the candidate will use to access the assessments.
external_id
A unique string to associate the candidate to an external record.
flow
The flow the candidate is in.
id
Unique id of the flow.
name
Name of the flow.
current
The step the candidate is on and the status on the step.
step_id
Unique id of the step.
status_code
Candidata status information. The status code can be empty if the candidate is in the custom step.
Possible values
ValueText
assesstment_invitedCandidate in the assessment step.
assesstment_ongoingCandidate in the assessment step.
assesstment_completedCandidate in the assessment step.
assesstment_positiveCandidate in the assessment step.
assesstment_negativeCandidate in the assessment step.
interview_invitedCandidate in the interview step.
interview_completedCandidate in the interview step.
interview_positiveCandidate in the interview step.
interview_negativeCandidate in the interview step.
interview_cancelledCandidate in the interview step.
interview_candidate_did_not_comeCandidate in the interview step.
interview_appointment_inviteCandidate in the interview step.
interview_appointment_cancelled_candidateCandidate in the interview step.
offer_will_sentCandidate in the offer step.
offer_sentCandidate in the offer step.
offer_acceptedCandidate in the offer step.
offer_rejectedCandidate in the offer step.
document_sentCandidate in the document control step.
document_uploadedCandidate in the document control step.
document_checkedCandidate in the document control step.
document_incompleteCandidate in the document control step.
document_negativeCandidate in the document control step.
recruitment_hiredCandidate in the recruitment step.
recruitment_quitCandidate in the recruitment step.
recruitment_yet_to_startCandidate in the recruitment step.
long_short_list_to_be_sharedCandidate in the Shortlisting step.
long_short_list_sharedCandidate in the Shortlisting step.
long_short_list_positiveCandidate in the Shortlisting step.
long_short_list_negativeCandidate in the Shortlisting step.
status_name
Name of the status.
steps
There may be more than one step on the flow. List of steps in the flow. This property value is an array.
id
Unique id of the step.
name
Name of the step.
type
Type of the step. Data type is integer.
Possible values
ValueText
0Assessment Center
1Interview
2COmpensation Planning & Offer
3Upload Document & Control
4Recruitment & Onboarding
5Shortlisting
99Custom
assessments
If the step type is “Assessment Center”, list of assessments in the step. Other step types do not have this property. This property value is an array.
id
Unique id of the candidate assessment. If the candidate take the assessment, the unique id of the assessment assigned to the candidate. Otherwise is blank. You can use this value to retrieve detailed candidate assessment reports with the following API methods. For example, the candidate test report.
assessment_id
Unique id of the assessment. If the same assessment is attached to other steps or other flows, the id value is the same in all of them.
name
Name of the assessment.
type
Type of the assessments. Data type is integer.
Possible values
ValueText
0Test
1Survey
2Video Interview
3Inventory
4Gamification
5Role Play
6Case Study
7Project
8Presentation
9Situational Judgement Test
score
If the candidate has completed the assessment, the assessment score. The score can be test score, gamification score or PiT score depending on the assessment type. For some types of assessments, scores may not be available. Data type is integer.
level
If any, level by the score. For example, English Proficiency Test level.
evaluation
The candidate's evaluation result if marked as positive or negative. Otherwise is blank. Data type is boolean.
date
The date the candidate taken the assessment. Otherwise is blank.
report_link
The link to use to access the candidate assessment report. If link generation property is set in the request, this value is included in the response.
interview
If the step type is “Interview”, details of the scheduled interview.
scheduled
Interview scheduled. Data type is boolean.
done
The interview done. Data type is boolean.
score
The interview score. Data type is integer.
evaluation
Positive or negative, the result of the interview. Data type is boolean.
date
The date of the interview, if scheduled.
data
Additional data stored on the candidate at the time of candidate invitation.
report_link
The link to use to access the candidate report. If link generation property is set in the request, this value is included in the response.
Sample Response
{
  "status": 0,
  "data": {
    "candidate": {
      "full_name": "Maria Simith",
      "email_address": "[email protected]",
      "mobile_phone_number": "+14155552671",
      "access_code": "ABCDEF"
    },
    "flow": {
      "id": "nyxur5m7zz5lwkv2xx6qwweq3w",
      "name": "Flow 01"
    },
    "current": {
      "step_id": "rswqsbxa6zjfwexg5f8e2rwtsq",
      "status_code": "assesstment_ongoing",
      "status_name": "Step 01"
    },
    "steps": [
      {
        "id": "cm5wpvjezmmuyqxlad6hlchsua",
        "type": 0,
        "name": "Step 01",
        "assessments": [
          {
            "id": "fauf6hz6xgjew6ms8pvpl3d4z3",
            "type": 0,
            "name": "English Proficiency Test",
            "used": true,
            "score": 60,
            "date": "2026-07-27T12:54:00Z",
            "report_link": "https://..."
          }
        ]
      },
      {
        "id": "k6jhhxuz5mp6y6zvashkzhnhy2",
        "type": 1,
        "name": "Step 02",
        "interview": {
          "scheduled": true,
          "done": true,
          "date": "2026-07-22T01:49:00Z"
        }
      }
    ],
    "report_link": "https://..."
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get candidate test report
Get candidate detailed test report.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/candidate_test_report/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/candidate_test_report/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
The unique id of the test assigned to the candidate. Test id can be obtained from the candidate flow data with the “Get candidate data” method.
languageoptional
Get test data with this language. Data type is integer. Default value is English.
Possible values
ValueText
0English
1Turkish
255Multilangual
get_candidate_dataoptional
Add candidate data to the response JSON. Candidate data fields can be viewed from the response document below. Data type is boolean. Default value is false.
generate_report_linkoptional
Create access links to candidate assessment report? The generated link is attached in the response. Data type is boolean. Default value is false.
report_link_anonymous_accessoptional
Provide anonymous access to the candidate report via the created link? Data type is boolean. Default value is false.
report_link_durationoptional
If anonymous access is granted, you can specify how many days the link will be valid. Data type is integer. Default value is 30 days.
report_languageoptional
The report accessed via the generated link and JSON data may be in different languages. "report_language" is the language of the report to be accessed via the generated link. If the language is not specified, the report link is created by looking at the value sent with the "language" parameter. Data type is integer.
Possible values
ValueText
0English
1Turkish
generate_pdf_fileoptional
Create PDF report? PDF report content can be downloaded from the specified link within 10 minutes. Data type is boolean. Default value is false.
get_dimensionsoptional
Get dimensions and scores of dimensions. Data type is boolean. Default value is false.
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/candidate_test_report/a3l3gw38vrb7wlxqgtu8zbzghw
Generate report link with anonymous access and get dimensions.
https://api-test.hrpeak.com/v2/flows/candidate_test_report/vnlx4gqt8ebpy2c5chl6jcmpxa/?generate_report_link=true&report_link_anonymous_access=true&get_dimensions=true
Response Information
tracking_number
Candidate tracking number. All flow data of the candidate can be retrieve with the tracking number.
candidate
Candidate information. This JSON property is only available when the “get_candidate_data” parameter is sent from the request.
full_name
Name of the candidate.
email_address
The candidate's email address.
mobile_phone_number
The candidate's mobile phone number.
access_code
The access code that the candidate will use to access the assessments.
external_id
A unique string to associate the candidate to an external record.
assessment
Assessment information.
id
Unique id of the assessment.
name
Name of the assessment.
score
Test score. Data type is integer.
level
If any, level by the score. For example, English Proficiency Test level.
question_count_correct
Number of correct answers. Data type is integer.
question_count_wrong
Number of wrong answers. Data type is integer.
question_count_blank
Number of blank answers. Data type is integer.
start_time
Candidate start time. Data type is datetime.
end_time
Candidate end time. Data type is datetime.
time_taken
How many seconds did the candidate spend on the assessment? Data type is integer.
dimensions
Dimensions of the test, if requested.
id
Unique id of the dimension.
name
Name of the dimension.
score
Dimension score. Data type is integer.
question_count_correct
Number of correct answers. Data type is integer.
question_count_wrong
Number of wrong answers. Data type is integer.
question_count_blank
Number of blank answers. Data type is integer.
description
If it is a general aptitude test, description of the dimension based on the candidate's score.
pdf_address
Link to access the PDF report if the “generate_pdf_file” property is set in the request. The PDF report can be accessed for 10 minutes via this link and the report content can be downloaded from the link within this period.
report_link
The link to use to access the candidate assessment report. If link generation property is set in the request, this value is included in the response.
Sample Response
{
  "status": 0,
  "data": {
    "tracking_number": "qfgxha4fqxpwydxzwlqcds4qmz",
    "candidate": {
      "full_name": "Maria Simith",
      "email_address": "[email protected]",
      "mobile_phone_number": "+14155552671",
      "access_code": "ABCDEF"
    },
    "assessment": {
      "id": "2tnnzycrl8jmwummwmzfkrxmz3",
      "name": "English Proficiency Test"
    },
    "score": 60,
    "level": "A2",
    "question_count_correct": 24,
    "question_count_wrong": 12,
    "question_count_blank": 4,
    "start_time": "2026-07-16T17:54:00Z",
    "end_time": "2026-07-27T14:43:00Z",
    "time_taken": 1200,
    "dimensions": [
      {
        "id": "suekkyztn8lvwznfk29cnb6zqz",
        "name": "Reading",
        "score": 78,
        "question_count_correct": 12,
        "question_count_wrong": 7,
        "question_count_blank": 0
      },
      {
        "id": "88fvvghnsv3syxzxawl3h8jkg2",
        "name": "Grammar",
        "score": 55,
        "question_count_correct": 12,
        "question_count_wrong": 5,
        "question_count_blank": 4
      }
    ],
    "pdf_address": "https://pdf.hrpeak.com/...",
    "report_link": "https://..."
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Candidate assessment report is not ready
{
  "status": 1,
  "error_message": "Candidate assessment report is not ready."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
Get candidate PiT report
Get candidate PiT report.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/candidate_pit_report/{id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/candidate_pit_report/{id}
     -H "Authorization: API_KEY"
URI parameters
idrequired
The unique id of the PiT assigned to the candidate. Candidate PiT id can be obtained from the candidate flow data with the “Get candidate data” method.
languageoptional
Get PiT data with this language. Data type is integer. Default value is English.
Possible values
ValueText
0English
1Turkish
255Multilangual
get_candidate_dataoptional
Add candidate data to the response JSON. Candidate data fields can be viewed from the response document below. Data type is boolean. Default value is false.
generate_report_linkoptional
Create access links to candidate assessment report? The generated link is attached in the response. Data type is boolean. Default value is false.
report_link_anonymous_accessoptional
Provide anonymous access to the candidate report via the created link? Data type is boolean. Default value is false.
report_link_durationoptional
If anonymous access is granted, you can specify how many days the link will be valid. Data type is integer. Default value is 30 days.
report_languageoptional
The report accessed via the generated link and JSON data may be in different languages. "report_language" is the language of the report to be accessed via the generated link. If the language is not specified, the report link is created by looking at the value sent with the "language" parameter. Data type is integer.
Possible values
ValueText
0English
1Turkish
generate_pdf_fileoptional
Create PDF report? PDF report content can be downloaded from the specified link within 10 minutes. Data type is boolean. Default value is false.
get_position_scoresoptional
Include all PiT position scores to the response. Data type is boolean. Default value is false.
get_detailed_reportoptional
Get detailed PiT report. Otherwise, only the summary report is generated. Data type is boolean. Default value is false.
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/candidate_pit_report/l5gczwflrdn2ytxtjdycvyjnys
Generate report link and get the detailed report.
https://api-test.hrpeak.com/v2/flows/candidate_pit_report/dhgxsh3f4qw5ypxqmqu4jgcea2/?generate_report_link=true&get_detailed_report=true
Response Information
tracking_number
Candidate tracking number. All flow data of the candidate can be retrieve with the tracking number.
candidate
Candidate information. This JSON property is only available when the “get_candidate_data” parameter is sent from the request.
full_name
Name of the candidate.
email_address
The candidate's email address.
mobile_phone_number
The candidate's mobile phone number.
access_code
The access code that the candidate will use to access the assessments.
external_id
A unique string to associate the candidate to an external record.
personality_factors
Personality factors. This property value is an array.
code
Unique code of the personality factor. Data type is integer.
Possible values
ValueText
1Challenger
2Perfectionist
3Observer
4Decisive
5Flexible
6Creative
7Helper
8Process-Oriented
9Rational Thinker
10Peacemaker
11Achiever
12Extrovert
13Entrepreneur
14Concrete Thinker
15Enthusiastic
16Cautious
17Result-Oriented
18Emotional Thinker
19Introvert
20Abstract Thinker
name
Name of the personality factor.
description
Description of the personality factor. This JSON property is only available when the “get_detailed_report” parameter is sent from the request.
self_perception_profile_strengths
Self-perception profile strengths. This property value is an array.
code
Unique code of the personality factor. Data type is integer.
name
Name of the personality factor.
self_perception_profile_weaknesses
Self-perception profile weaknesses. This property value is an array.
code
Unique code of the personality factor. Data type is integer.
name
Name of the personality factor.
competencies
Competencies. This property value is an array.
code
Unique code of the competency. Data type is integer.
Possible values
ValueText
1Collaboration and Team Work
2Customer-Orientation
3Effective Communication
4Detail-Orientation
5Continuous Learning and Development
6Planning
7Agility
8Strategic Thinking
9Effective Delegation
10Team Development and Coaching
name
Name of the competency.
primary_characteristics
Primary characteristics. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
potential_improvement_areas
Potential improvement areas. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
shadow_areas
Shadow areas. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
potential_competency_profile
Potential competency report. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. This property value is an array.
competency
code
Unique code of the competency. Data type is integer.
name
Name of the competency.
description
Sentences. Data type is string. This property value is an array.
training_needs_analysis
Training needs analysis. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. This property value is an array.
competency
code
Unique code of the competency. Data type is integer.
name
Name of the competency.
trainings
Trainings. Data type is string. This property value is an array.
effective_management_tips
Effective management tips. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
coaching_mentorship_tips
Coaching and mentorship tips. This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
strengths
Strengths This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
weaknesses
Weaknesses This JSON property is only available when the “get_detailed_report” parameter is sent from the request. Data type is string. This property value is an array.
interview_tips
Interview tips. This JSON property is only available when the “get_detailed_report” parameter is sent from the request.
primary_characteristics
Primary characteristics. Data type is string. This property value is an array.
potential_improvement_areas
Potential improvement areas. Data type is string. This property value is an array.
shadow_areas
Shadow areas. Data type is string. This property value is an array.
position_score
The PiT position score selected by the company when viewing the candidate report.
code
Unique code of the PiT position.
name
Name of the PiT position.
score
Data type is integer. Max value is 10.
position_scores
PiT position scores. This JSON property is only available when the “get_position_scores” parameter is sent from the request. This property value is an array.
code
Unique code of the PiT position.
name
Name of the PiT position.
score
Data type is integer. Max value is 10.
values
Value profile. Data type is string. This property value is an array.
ai_summary
AI summary of the PiT report.
personality_factors
Personality factors.
value_profile
Value profile.
potential_competency_profile
Potential competency report.
training_needs_analysis
Training needs analysis.
effective_management_tips
Effective management tips.
coaching_mentorship_tips
Coaching and mentorship tips.
consistency
Consistency of the candidate answers.
value
Data type is integer.
Possible values
ValueText
4Very Good
3Good
2Average
1Low
0Very Low
255Invalid
description
Description of the consistency.
date
Completion date.
pdf_address
Link to access the PDF report if the “generate_pdf_file” property is set in the request. The PDF report can be accessed for 10 minutes via this link and the report content can be downloaded from the link within this period.
report_link
The link to use to access the candidate assessment report. If link generation property is set in the request, this value is included in the response.
Sample Response
{
  "status": 0,
  "data": {
    "tracking_number": "7umwnxbcm27ayax4lameha52mz",
    "personality_factors": [
      {
        "code": 2,
        "name": "Perfectionist"
      },
      {
        "code": 1,
        "name": "Challenger"
      }
    ],
    "self_perception_profile_strengths": [
      {
        "code": 3,
        "name": "Observer"
      },
      {
        "code": 4,
        "name": "Decisive"
      }
    ],
    "self_perception_profile_weaknesses": [
      {
        "code": 5,
        "name": "Flexible"
      },
      {
        "code": 6,
        "name": "Creative"
      }
    ],
    "competencies": [
      {
        "code": 2,
        "name": "Customer-Orientation"
      },
      {
        "code": 1,
        "name": "Collaboration and Team Work"
      }
    ],
    "values": [
      "...",
      "..."
    ],
    "consistency": {
      "value": 4,
      "description": "Very Good"
    },
    "date": "2026-07-15T13:45:00Z"
  }
}
JSON generated with full options.
{
  "status": 0,
  "data": {
    "tracking_number": "83ffj4uq3c65wccumm6zhmgtes",
    "candidate": {
      "full_name": "Maria Simith",
      "email_address": "[email protected]",
      "mobile_phone_number": "+14155552671",
      "access_code": "ABCDEF"
    },
    "personality_factors": [
      {
        "code": 2,
        "name": "Perfectionist",
        "description": "Straightforward, pushes the limits, dominant, self-confident"
      },
      {
        "code": 1,
        "name": "Challenger",
        "description": "Disciplined, principled, serious, self-controlled"
      }
    ],
    "self_perception_profile_strengths": [
      {
        "code": 3,
        "name": "Observer"
      },
      {
        "code": 4,
        "name": "Decisive"
      }
    ],
    "self_perception_profile_weaknesses": [
      {
        "code": 5,
        "name": "Flexible"
      },
      {
        "code": 6,
        "name": "Creative"
      }
    ],
    "competencies": [
      {
        "code": 2,
        "name": "Customer-Orientation"
      },
      {
        "code": 1,
        "name": "Collaboration and Team Work"
      }
    ],
    "primary_characteristics": [
      "...",
      "..."
    ],
    "potential_improvement_areas": [
      "...",
      "..."
    ],
    "shadow_areas": [
      "...",
      "..."
    ],
    "potential_competency_profile": [
      {
        "competency": {
          "code": 3,
          "name": "Effective Communication"
        },
        "description": [
          "...",
          "..."
        ]
      }
    ],
    "training_needs_analysis": [
      {
        "competency": {
          "code": 3,
          "name": "Effective Communication"
        },
        "trainings": [
          "...",
          "..."
        ]
      }
    ],
    "effective_management_tips": [
      "...",
      "..."
    ],
    "coaching_mentorship_tips": [
      "...",
      "..."
    ],
    "strengths": [
      "...",
      "..."
    ],
    "weaknesses": [
      "...",
      "..."
    ],
    "interview_tips": [
      {
        "primary_characteristics": [
          "...",
          "..."
        ],
        "potential_improvement_areas": [
          "...",
          "..."
        ],
        "shadow_areas": [
          "...",
          "..."
        ]
      }
    ],
    "position_score": {
      "code": "48m64hd6a2zdwlc96kbfcpppr2",
      "name": "Position 01",
      "score": 7
    },
    "position_scores": [
      {
        "code": "ksd9kqn8fdqkytndwpnacahn72",
        "name": "Position 01",
        "score": 7
      },
      {
        "code": "dehnbr422sjeybba3myyjap8z2",
        "name": "Position 02",
        "score": 9
      }
    ],
    "values": [
      "...",
      "..."
    ],
    "ai_summary": {
      "personality_factors": "...",
      "value_profile": "...",
      "potential_competency_profile": "...",
      "training_needs_analysis": "...",
      "effective_management_tips": "...",
      "coaching_mentorship_tips": "..."
    },
    "consistency": {
      "value": 4,
      "description": "Very Good"
    },
    "date": "2026-08-01T02:11:00Z",
    "pdf_address": "https://pdf.hrpeak.com/...",
    "report_link": "https://..."
  }
}
Error Responses
Error messages can vary. More specific error information may be included.
Bad request
{
  "status": 400,
  "error_message": "Invalid request."
}
Not found
{
  "status": 404,
  "error_message": "Record not found."
}
Candidate assessment report is not ready
{
  "status": 1,
  "error_message": "Candidate assessment report is not ready."
}
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
List candidate tracking numbers
Gets the list of candidate tracking numbers. Candidate flow data can be retrieved using the tracking number.
Request Information
GEThttps://api-test.hrpeak.com/v2/flows/tracking_numbers
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/flows/tracking_numbers
     -H "Authorization: API_KEY"
Candidate tracking numbers can be filtered using the following parameters.
URI parameters
flow_idoptional
Unique id of the flow.
step_idoptional
Unique id of the step.
status_codeoptional
Unique code of the candidate status.
Possible values
ValueText
assesstment_invitedCandidate in the assessment step.
assesstment_ongoingCandidate in the assessment step.
assesstment_completedCandidate in the assessment step.
assesstment_positiveCandidate in the assessment step.
assesstment_negativeCandidate in the assessment step.
interview_invitedCandidate in the interview step.
interview_completedCandidate in the interview step.
interview_positiveCandidate in the interview step.
interview_negativeCandidate in the interview step.
interview_cancelledCandidate in the interview step.
interview_candidate_did_not_comeCandidate in the interview step.
interview_appointment_inviteCandidate in the interview step.
interview_appointment_cancelled_candidateCandidate in the interview step.
offer_will_sentCandidate in the offer step.
offer_sentCandidate in the offer step.
offer_acceptedCandidate in the offer step.
offer_rejectedCandidate in the offer step.
document_sentCandidate in the document control step.
document_uploadedCandidate in the document control step.
document_checkedCandidate in the document control step.
document_incompleteCandidate in the document control step.
document_negativeCandidate in the document control step.
recruitment_hiredCandidate in the recruitment step.
recruitment_quitCandidate in the recruitment step.
recruitment_yet_to_startCandidate in the recruitment step.
long_short_list_to_be_sharedCandidate in the Shortlisting step.
long_short_list_sharedCandidate in the Shortlisting step.
long_short_list_positiveCandidate in the Shortlisting step.
long_short_list_negativeCandidate in the Shortlisting step.
candidate_external_idoptional
A unique string to associate the candidate to an external record.
candidate_tag_idoptional
Unique id of the tag.
company_employeeoptional
Filter the company employees. To retrieve all candidates, you should not provide a parameter. Data type is boolean.
Possible values
ValueText
trueOnly company employees
falseDo not include the company employees
start_dateoptional
The date the candidate is assigned to the flow. Data type is datetime.
end_dateoptional
The date the candidate is assigned to the flow. Data type is datetime.
filter_extraoptional
Additional filters. You can contact technical customer support to determine the filter value.
pageoptional
The zero-based page number. Data type is integer. Default value is 0.
per_pageoptional
The number of items per page. Maximum value is 1000. Data type is integer. Default value is 100.
Request Uri Sample
https://api-test.hrpeak.com/v2/flows/tracking_numbers/?status_code=assesstment_completed
https://api-test.hrpeak.com/v2/flows/tracking_numbers/?company_employee=true
https://api-test.hrpeak.com/v2/flows/tracking_numbers/?flow_id=ermqswu6jqgnw9nkc7tyhgzkdx&status_code=assesstment_completed&page=0&per_page=20
Response Information
tracking_number
Candidate tracking number. The candidate's flow details can be accessed using this id.
flow_id
Unique id of the flow.
step_id
Unique id of the step.
status_code
Candidata status information. The status code can be empty if the candidate is in the custom step.
Possible values
ValueText
assesstment_invitedCandidate in the assessment step.
assesstment_ongoingCandidate in the assessment step.
assesstment_completedCandidate in the assessment step.
assesstment_positiveCandidate in the assessment step.
assesstment_negativeCandidate in the assessment step.
interview_invitedCandidate in the interview step.
interview_completedCandidate in the interview step.
interview_positiveCandidate in the interview step.
interview_negativeCandidate in the interview step.
interview_cancelledCandidate in the interview step.
interview_candidate_did_not_comeCandidate in the interview step.
interview_appointment_inviteCandidate in the interview step.
interview_appointment_cancelled_candidateCandidate in the interview step.
offer_will_sentCandidate in the offer step.
offer_sentCandidate in the offer step.
offer_acceptedCandidate in the offer step.
offer_rejectedCandidate in the offer step.
document_sentCandidate in the document control step.
document_uploadedCandidate in the document control step.
document_checkedCandidate in the document control step.
document_incompleteCandidate in the document control step.
document_negativeCandidate in the document control step.
recruitment_hiredCandidate in the recruitment step.
recruitment_quitCandidate in the recruitment step.
recruitment_yet_to_startCandidate in the recruitment step.
long_short_list_to_be_sharedCandidate in the Shortlisting step.
long_short_list_sharedCandidate in the Shortlisting step.
long_short_list_positiveCandidate in the Shortlisting step.
long_short_list_negativeCandidate in the Shortlisting step.
candidate_external_id
A unique string to associate the candidate to an external record.
assigned_at
The date the candidate is assigned to the flow.
Sample Response
{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "tracking_number": "w4kgevcda5nky4m3agp5putmkw",
      "flow_id": "zkbd4xfy8q7eymb852s77zmvd3",
      "step_id": "zjwmzclcnn8sylmdjbhkfhn5vs",
      "status_code": "assesstment_completed",
      "candidate_external_id": "A0001",
      "assigned_at": "2026-07-23T10:53:00+03:00"
    },
    {
      "tracking_number": "cel8qhmasrxwy4vbaufzyjmyzw",
      "flow_id": "33f54gmskn3wy4ncud8wlegk52",
      "step_id": "sj3mdu9ekjbyy5zumvhgnm2fhw",
      "status_code": "assesstment_ongoing",
      "assigned_at": "2026-07-30T05:44:00+03:00"
    }
  ]
}
Error Responses
Error messages can vary. More specific error information may be included.
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
List candidate assessment ids
Gets the list of candidate assessment ids. Candidate assessment data can be retrieved using the assessment id.
Request Information
GEThttps://api-test.hrpeak.com/v2/assessments/{assesstment_id}
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/assessments/{assesstment_id}
     -H "Authorization: API_KEY"
Candidate assessment ids can be filtered using the following parameters.
URI parameters
assesstment_idrequired
Unique id of the assessment.

Some possible values ​​are listed below. The full list is available on the assessment library page.
m6u4qp9sjabnyhcsy8s8nx6cnz for PiT - Personality Item Test
rafkn6buv865yezmsgv6pvsmlx for Aptitude Test
zc9xny7akcejy6csxam86u2wlq for English Proficiency Test
flow_idoptional
Unique id of the flow.
status_codeoptional
Unique code of the candidate status.
Possible values
ValueText
assesstment_invitedCandidate in the assessment step.
assesstment_ongoingCandidate in the assessment step.
assesstment_completedCandidate in the assessment step.
assesstment_positiveCandidate in the assessment step.
assesstment_negativeCandidate in the assessment step.
interview_invitedCandidate in the interview step.
interview_completedCandidate in the interview step.
interview_positiveCandidate in the interview step.
interview_negativeCandidate in the interview step.
interview_cancelledCandidate in the interview step.
interview_candidate_did_not_comeCandidate in the interview step.
interview_appointment_inviteCandidate in the interview step.
interview_appointment_cancelled_candidateCandidate in the interview step.
offer_will_sentCandidate in the offer step.
offer_sentCandidate in the offer step.
offer_acceptedCandidate in the offer step.
offer_rejectedCandidate in the offer step.
document_sentCandidate in the document control step.
document_uploadedCandidate in the document control step.
document_checkedCandidate in the document control step.
document_incompleteCandidate in the document control step.
document_negativeCandidate in the document control step.
recruitment_hiredCandidate in the recruitment step.
recruitment_quitCandidate in the recruitment step.
recruitment_yet_to_startCandidate in the recruitment step.
long_short_list_to_be_sharedCandidate in the Shortlisting step.
long_short_list_sharedCandidate in the Shortlisting step.
long_short_list_positiveCandidate in the Shortlisting step.
long_short_list_negativeCandidate in the Shortlisting step.
candidate_external_idoptional
A unique string to associate the candidate to an external record.
candidate_tag_idoptional
Unique id of the tag.
company_employeeoptional
Filter the company employees. To retrieve all candidates, you should not provide a parameter. Data type is boolean.
Possible values
ValueText
trueOnly company employees
falseDo not include the company employees
start_dateoptional
Candidate's assessment usage time. Data type is datetime.
end_dateoptional
Candidate's assessment usage time. Data type is datetime.
filter_extraoptional
Additional filters. You can contact technical customer support to determine the filter value.
pageoptional
The zero-based page number. Data type is integer. Default value is 0.
per_pageoptional
The number of items per page. Maximum value is 1000. Data type is integer. Default value is 100.
Request Uri Sample
https://api-test.hrpeak.com/v2/assessments/{assesstment_id}/?status_code=assesstment_completed
https://api-test.hrpeak.com/v2/assessments/{assesstment_id}/?company_employee=true
https://api-test.hrpeak.com/v2/assessments/{assesstment_id}/?flow_id=qsq3tbba7742wqxv2bcbpmhp62&status_code=assesstment_completed&page=0&per_page=20
Response Information
id
The unique id of the assessment assigned to the candidate. The candidate's assessment details can be accessed using this id.
tracking_number
Candidate tracking number. The candidate's flow details can be accessed using this id.
flow_id
Unique id of the flow.
candidate_external_id
A unique string to associate the candidate to an external record.
date
Candidate's assessment usage time.
Sample Response
{
  "status": 0,
  "total_data_count": 1000,
  "data": [
    {
      "id": "bfxqbbu6c3naw2nwye73jh8nlx",
      "tracking_number": "57bwj6aptl6sy9v7mh8f7y7fg3",
      "flow_id": "dqf6k9tgkrq7y2cm633ujux6fz",
      "candidate_external_id": "A0001",
      "date": "2026-07-13T19:06:00Z"
    },
    {
      "id": "7wuj3lppxl2pybcvum849f6n7z",
      "tracking_number": "5ydehpukcvd2ywzw6pb8bthq62",
      "flow_id": "ysc8fjhjyabnw4mhgl4nqeljgw",
      "date": "2026-08-01T11:15:00Z"
    }
  ]
}
Error Responses
Error messages can vary. More specific error information may be included.
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}
List PiT positions
Gets the list of PiT positions used in calculating the candidate's position fit score.
Request Information
GEThttps://api-test.hrpeak.com/v2/pit_positions
The API uses basic authentication and the API key must be sent in the Authorization request header.
curl https://api-test.hrpeak.com/v2/pit_positions
     -H "Authorization: API_KEY"
URI parameters
languageoptional
Position names can be multilingual. The language of the position names. Default value is English.
Possible values
ValueText
0English
1Turkish
Response Information
id
Unique id of the position.
name
Name of the position.
Sample Response
{
  "status": 0,
  "data": [
    {
      "id": "anaezszjpblhwenyhc2sfd8e83",
      "name": "Position 01"
    },
    {
      "id": "q6rrdsasjf5cwfmtwayzexq2ma",
      "name": "Position 02"
    }
  ]
}
Error Responses
Error messages can vary. More specific error information may be included.
Internal server error
{
  "status": 500,
  "error_message": "A generic error has occurred on the server."
}