Enabling Crosschq Partner API v2
Crosschq’s Partner API are REST APIs that allow third parties:
- Trigger a Crosschq request for references;
- Monitor and manage the progress of the request;
- Return an online or PDF version of the complete 360 Report. This document describes the API endpoints, webhooks, and common use cases. The Postman collection is provided for reference.
Crosschq provides partners with access to a sandbox account for testing, reach out to support@crosschq.com to get access to this account.
When you have fully tested your API in your Sandbox account, please contact Crosschq’s support team at support@crosschq.com to enable the final account.
The base URL for both the sandbox and production account's API is:
- https://partner.crosschq.com/
Swagger is available: https://partner.crosschq.com/swagger-ui
This is the documentation for version 2.0.0 of the API. Last update on March. 27, 2021.
Read the following sections to start setting up the Crosschq Partner API:
Authentication
Crosschq will provide you with a token that must be sent on an AUTHORIZATION header with each request.
Endpoints: JobRoles
/api/v2/settings/jobrole/
Each JobRole (also called “survey”) represents a survey that can be used for the Crosschq reference request. JobRoles can be enabled/disabled by an account administrator within the Crosschq application under the survey settings section.
id
name
relationships
- codename is the identifier of the survey and is required to trigger the reference request process.
- name is the label that is used in Crosschq to identify this JobRole.
- relationships are a list of the available relationships for the JobRole.
[
{
"codename": "brand-marketer-manager",
"name": "Brand Marketer - Manager",
"relationships": {
"business": {
"default": 2,
"label": "Customers/Suppliers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"employees": {
"default": 2,
"label": "Direct Reports",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"managers": {
"default": 2,
"label": "Managers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"peers": {
"default": 2,
"label": "Coworkers/Peers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"social": {
"default": 2,
"label": "Mentors",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
}
}
},
{
"codename": "brand-marketer-team-member",
"name": "Brand Marketer - Team Member",
"relationships": {
"business": {
"default": 2,
"label": "Customers/Suppliers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"employees": {
"default": 2,
"label": "Direct Reports",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"managers": {
"default": 2,
"label": "Managers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"peers": {
"default": 2,
"label": "Coworkers/Peers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"social": {
"default": 2,
"label": "Mentors",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
}
}
},
{
"codename": "consulting-services-manager",
"name": "Consulting Services - Manager",
"relationships": {
"business": {
"default": 2,
"label": "Customers/Suppliers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"employees": {
"default": 2,
"label": "Direct Reports",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"managers": {
"default": 2,
"label": "Managers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"peers": {
"default": 2,
"label": "Coworkers/Peers",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
},
"social": {
"default": 2,
"label": "Mentors",
"max": 10,
"min": 0,
"skip_reference_optin": false,
"whv_mode": "default"
}
}
}
]
Create Reference Request
/api/v2/reference-request/ [POST]
This endpoint starts the reference request process. After calling this endpoint successfully, Crosschq will send an email/SMS to the candidate asking them to provide their references.
Request Body
- candidate: dictionary with the basic candidate information (first_name, last_name, email, mobile_phone);
- jobrole: jobrole codename obtained with the jobroles endpoint;
- requestor: email for request owner in Crosschq, if there is no such user in Crosschq, an invite will automatically be sent to the user;
- (optional) requestor_first_name: the name for the requestor, it will be used only if Crosschq needs to create the user.
- (optional) requestor_last_name: the last name for the requestor, it will be used only if Crosschq needs to create the user.
- use_sms: flag to send or not an SMS to the candidate.
- flex_params: a dictionary of the configuration for the reference request. The key relationships should include a list of the required references for the reference request. Any relationships detailed on the JobRole selected can be used. In addition, the relationship codename 'any' can be used, letting the candidate select the relationship.
- rel: the key for the relationship to be used (detailed in the JobRole endpoint) or the special key “any”.
- required: the number of references of this type that the candidate must provide.
- notes: an optional note that will be sent to the candidate for the specific relationship.
- send_past_due_notification: a flag to set if Crosschq should remind the candidate to complete the reference process if it has not been completed.
- send_completed_notification: a flag to set if Crosschq should send a notification to the hiring manager when the reference process has been completed.
- job_position: the job position that the candidate is being considered for.
- hiring_manager: a dictionary with the basic information for the hiring manager (first_name, last_name, email).
{
"candidate": {
"first_name": "Jane",
"last_name": "Candidate",
"email": "janecandidate@example.com",
"mobile_phone": "+15550199"
},
"jobrole": "consulting-services-manager",
"requestor": "recruiter@yourcompany.com",
"use_sms": true,
"flex_params": {
"relationships": [
{
"rel": "any",
"required": 2,
"notes": "A relevant comment about the references required."
},
{
"rel": "managers",
"required": 1,
"notes": "A relevant comment about the references required."
}
]
},
"send_past_due_notification": false,
"send_completed_notification": false,
"job_position": "Business Consultant",
"hiring_manager": {
"first_name": "Mary",
"last_name": "Hiring",
"email": "maryhiring@yourcompany.com"
}
}
Response
The successful response from this endpoint is a request_id that can be used to retrieve information about the process.
{
"request_id": "cd9447e1450c446a9d97c7b67ad1587f"
}
In case there are errors, the response will be status 400 with a response similar to the one below:
{
"errors": {
"candidate": {
"email": [
"This field is required."
]
}
}
}
Also if we later found errors during the processing of the data, the user will be informed via webhook.
Retrieve Reference Request
/api/v2/reference-request/{request_id}/
This endpoint returns information for a specific reference request. If the request does not exist the endpoint will return a 404 status. The following is an example of a successful call to this endpoint:
{
"asmt_score": null,
"can_send_reminder": false,
"candidate": {
"avatar": "",
"created_on": "2021-03-28T02:24:49.801546Z",
"email": "soler+kajsndajns@crosschq.com",
"first_name": "tewewewewerron",
"id": "7ceaf8b169ab440b89113357ae5b8fe7",
"last_name": "Pietro",
"mobile_phone": "+542234565018"
},
"comments_count": 0,
"completed_on": null,
"created_on": "2021-03-28T02:24:50.062333Z",
"elapsed_level": "0",
"elapsed_time": 803,
"flex_params": {
"relationships": [
{
"id": "b9a5cbc3-1a74-46f3-8181-3a56648a8873",
"notes": "people older than 40 years old",
"rel": "any",
"required": 2
}
]
},
"hire_status": "unknown",
"hiring_manager": {
"email": "soler+hiringman@crosschq.com",
"first_name": "Tito",
"last_name": "Hiring",
"title": ""
},
"id": "2325078e34a34f8d8be9875fc1de23e8",
"is_past_due": false,
"job_position": "Business Manager",
"jobrole": {
"id": "in-home-nannysitter",
"name": "In Home Nanny/Sitter"
},
"ref_score": null,
"references": [],
"request_detail_url": "https://org.crosschq.com/request/references/9b746bf588884f1f94bb7b45c0bd5422/",
"requestor": {
"avatar": "",
"email": "santiagomdq@gmail.com",
"first_name": "Santiago",
"id": "5bb689f8-ef7e-4b98-af64-3d413f225567",
"last_name": "Morrone",
"mobile_phone": "+12029999663",
"org": {
"id": "2d4a97c0-4e5c-48c2-b7d3-d4413d1bd5f7",
"logo": "https://media.glassdoor.com/o/43129/tesla-squarelogo-1512420729170.jpg",
"name": "Tenergy Inc."
}
},
"status_description": "The request was sent to the candidate, but it has not yet been accepted.",
"status_message": "Sent"
}
Edit Reference Request
/api/v2/reference-request/{req_uid}/edit/ [PATCH]
Allows editing of the information for a reference request.
Params
- req_uid: the id for the reference request.
The following is an example of a valid request:
{
"sms_message": "hello there",
"flex_params": {
"relationships": [
{
"rel": "any",
"required": 2,
"notes": "Please provide your two best references."
}
]
},
"hiring_manager": {
"first_name": "Joe",
"last_name": "Doe",
"email": "joe.doe@example.com"
},
"candidate_message": "hello there 2",
"use_sms": true
}
Cancel Reference Request
/api/v2/reference-request/{req_uid}/cancel/ [POST]
This endpoint can be used to cancel an in-progress reference request.
Params
- req_uid: the id for the reference request.
Conclude Reference Request
/api/v2/reference-request/{req_uid}/conclude/ [POST]
This endpoint concludes a reference request, providing that at least one reference has completed their survey.
Params
- req_uid: the id for the reference request.
Send Reminder to a Candidate
/api/v2/reference-request/{req_uid}/send-reminder/ [POST]
This endpoint can be used to send a reminder to the candidate.
Params
- req_uid: the id for the reference request.
Retrieve a Reference Request (Download Report)
/api/v2/reference-request/{req_uid}/download-report/ [GET]
This endpoint can be used to download a PDF report for a completed reference request. It will return the pdf file directly. It will return a 400 error if the request is not completed or concluded.
Params
- req_uid: the id for the reference request.
Arguments
- (optional) report: query string parameter, can be either summary or full, defaults to summary. Selects what report to download.
Webhooks
Crosschq’s Partner API includes a webhook that is called each time:
- The reference request changes status (sent, accepted, assigning, collecting, canceled, declined, completed, concluded)
- A reference is added by the candidate.
- A reference declines to provide feedback.
- A reference completes the survey.
{
"id": "603a2d8f801a4799ab4eb3b40040587c",
"candidate": {
"first_name": "Mike",
"last_name": "Fitz",
"mobile_phone": "+13239393939",
"email": "soler+mike@crosschq.com"
},
"job_position": "",
"status": "completed",
"status_updated_on": "2018-07-26T15:44:21.907327Z",
"progress": 100,
"references": [
{
"first_name": "Stacy",
"last_name": "Sommer",
"mobile_phone": "+13239393939",
"email": "soler+stacy@crosschq.com",
"status": "completed"
},
{
"first_name": "Pete",
"last_name": "Goettner",
"mobile_phone": "+13239383484",
"email": "santiago+pete@crosschq.com",
"status": "completed"
},
{
"first_name": "Christian",
"last_name": "Borcher",
"mobile_phone": "+13233838388",
"email": "santiago+christian@crosschq.com",
"status": "completed"
},
{
"first_name": "Ryan",
"last_name": "Collins",
"mobile_phone": "+13235848484",
"email": "santiago+ryan@crosschq.com",
"status": "completed"
}
],
"report_url": "https://sandbox-org.crosschq.com/request/references/603a2d8f801a4799ab4eb3b40040587c/",
"created_at": "2018-07-26T15:34:21.982332Z",
"updated_on": "2018-07-26T15:44:21.907327Z"
}
Webhooks
Crosschq uses webhooks to send updates on every request status change. Provide the URL to which Crosschq will send the webhooks to support@crosschq.com.
Below you can find all the webhooks that Crosschq triggers for each status change:
Sent
This webhook will be triggered when the request is sent but the candidate has not accessed it yet
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "sent",
"status_message": "Sent",
"status_updated_on": "2023-05-31T15:56:45.695Z",
"progress": 0,
"references": [],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T15:56:45.695981Z",
"event_name": "reference_request_status_updated"
}
Accepted
This webhook will be triggered right after the candidate accepted the request and accessed the candidate's locker.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "accepted",
"status_message": "Accepted",
"status_updated_on": "2023-05-31T15:57:52.265Z",
"progress": 0,
"references": [],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T15:57:52.265324Z",
"event_name": "reference_request_status_updated"
}
Assigning
This webhook will be triggered right after the candidate submitted the self-assessment, but has not yet provided references.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "assigning",
"status_message": "Assigning",
"status_updated_on": "2023-05-31T15:59:04.911Z",
"progress": 50,
"references": [],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T15:59:04.911558Z",
"event_name": "reference_request_status_updated"
}
Collecting > First Reference Added
This webhook will be triggered once the candidate provided their first reference.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "collecting",
"status_message": "Collecting",
"status_updated_on": "2023-05-31T16:00:21.519Z",
"progress": 75,
"references": [
{
"first_name": "mike",
"last_name": "harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T16:00:22.181784Z",
"event_name": "reference_request_status_updated"
}
Collecting > All References Added
This webhook will be triggered once the candidate provided all references required.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "collecting",
"status_message": "Collecting",
"status_updated_on": "2023-05-31T16:00:21.519Z",
"progress": 75,
"references": [
{
"first_name": "mike",
"last_name": "harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T16:00:22.181784Z",
"event_name": "reference_request_reference_added"
}
Collecting > One of the References provided their answers
This webhook will be triggered after one of the references provided their answers.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "collecting",
"status_message": "Collecting",
"status_updated_on": "2023-05-31T16:00:21.519Z",
"progress": 100,
"references": [
{
"first_name": "Mike",
"last_name": "Harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T16:00:22.181784Z",
"event_name": "reference_request_reference_completed"
}
Completed > All references provided their answers
This webhook will be triggered after all references provided their answers. This means that the 360 requests have been completed but the report is not yet ready. It usually takes a few seconds to generate the report so you should receive this webhook instantly before the following.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "completed",
"status_message": "Completed",
"status_updated_on": "2023-05-31T16:00:21.519Z",
"progress": 100,
"references": [
{
"first_name": "Mike",
"last_name": "Harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T16:00:22.181784Z",
"event_name": "reference_request_reference_completed"
"score": 3.21, // this is an optional field, please reach out to support@crosschq.com to activate it
}
Completed > Crosschq report is ready
This webhook will be triggered after the report has been generated. It usually takes a few seconds to generate the report so you should receive this webhook instantly after the previous one.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "completed",
"status_message": "Completed",
"status_updated_on": "2023-05-31T16:06:39.744Z",
"progress": 100,
"references": [
{
"first_name": "Mike",
"last_name": "Harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.com/request/references/31618d85bb4146788422eb014950b5de/",
"created_at": "2023-05-31T15:56:45.513060Z",
"updated_on": "2023-05-31T16:06:40.231582Z",
"event_name": "reference_request_full_completed"
"score": 3.21, // this is an optional field, please reach out to support@crosschq.com to activate it
}
Auto-Concluded
This webhook will be triggered when the request is auto-concluded according to the auto-conclude rules you have set up within the request settings. Read this article to learn more about the auto-conclude rule: https://support.crosschq.com/knowledge/report-auto-conclude
{
"id": "0b6cc6392d4c4b2c99fd807fe038208c",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "auto-concluded",
"status_message": "Auto-concluded",
"status_updated_on": "2023-06-08T17:59:11.591Z",
"progress": 100,
"references": [
{
"first_name": "Mike",
"last_name": "Harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev"
}
],
"report_url": "https://org.crosschq.dev/request/references/0b6cc6392d4c4b2c99fd807fe038208c/",
"created_at": "2023-06-08T17:17:14.933286Z",
"updated_on": "2023-06-08T17:59:12.273661Z",
"event_name": "reference_request_full_completed"
"score": 3.21, // this is an optional field, please reach out to support@crosschq.com to activate it
}
Canceled by Candidate
This webhook will be triggered when the candidate cancels the request.
{
"id": "04b6233d0f6f4a9bbfddc32eaf4a3660",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position": "Business Manager",
"status": "canceled-by-candidate",
"status_message": "Canceled",
"status_updated_on": "2023-05-31T16:07:54.868Z",
"progress": 0,
"references": [],
"report_url": "https://org.crosschq.com/request/references/04b6233d0f6f4a9bbfddc32eaf4a3660/",
"created_at": "2023-05-31T15:54:48.198245Z",
"updated_on": "2023-05-31T16:07:54.868511Z",
"event_name": "reference_request_status_updated"
}
Auto-Canceled
This webhook will be triggered when the request is auto-canceled according to the auto-cancel rules you have set up within the request settings. Read the following article to learn more about this rule:
https://support.crosschq.com/knowledge/managing-crosschq-360-settings#autocancel
{
"id": "04b6233d0f6f4a9bbfddc32eaf4a3660",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com"
},
"job_position":"Business Manager",
"status":"auto-canceled",
"status_message":"Auto-canceled",
"status_updated_on":"2023-06-23T19:20:23.996Z",
"progress":33,
"references":[],
"report_url":"https://org.crosschq.com/request/references/04b6233d0f6f4a9bbfddc32eaf4a3660/",
"report_summary_pdf":"",
"report_full_pdf":"",
"created_at":"2023-06-22T18:37:34.609672Z",
"updated_on":"2023-06-23T19:20:23.994873Z",
"event_name":"reference_request_status_updated"
}