![Crosschq Logo 534x115.png]](https://support.crosschq.com/hs-fs/hubfs/Crosschq%20Logo%20534x115.png?height=40&name=Crosschq%20Logo%20534x115.png){kind=small}
Crosschq’s Partner APIs 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
Read the following sections to start setting up the Crosschq Partner API:
Authentication
Navigate to Settings > Connectors and enable the Crosschq Partner API toggle. Once enabled, the API Settings panel will expand.
General
The Partner API Key is the token that must be sent on an AUTHORIZATION header with each API request.
Webhook Configuration
The API Settings panel includes webhook configuration for both the 360 app and the Interview app. Each app has the following fields:
- Webhook URL — the endpoint URL where Crosschq will send event notifications.
- Request method —
POST(default) orPUT. UsePOSTto create a new record andPUTto update an existing one. - Auth method (optional) — the authentication method used to call your endpoint. Available options:
- No Auth (default) — no authentication is required.
- Basic — HTTP Basic authentication.
- Token — token-based authentication.
- Token (optional) — required only when Auth method is set to Basic or Token.
Configure both apps independently, then click Save Changes.
Configure app settings
Once your API settings are saved, you can configure additional settings for specific Crosschq Apps.
.png?width=670&height=149&name=image%20(10).png)
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);
- The team_id field must be provided only if your organization is using different teams. Reach out to support@crosschq.com to ask for your team's IDs. If you do not provide a team ID, the request will be assigned to the default team.
- 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.
- (optional) skip_first_communication: flag to suppress the invitation Crosschq would otherwise send the candidate when the request is created. Defaults to false; when set to true, neither the email nor the SMS is sent and reaching the candidate is up to you — see welcome_url in the Response below for the link to send them.
- 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": {
"team_id": "12206020-dccb-4859-8f3e-8dc55d2d08f1"
"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
A successful call returns the request_id of the new reference request, together with the candidate’s welcome_url. The request_id is the id every other endpoint in this article takes in its path, and the same id the webhook reports as id.
welcome_url is an empty string unless the request was sent with skip_first_communication: true and your account has the return welcome URL setting enabled; with both, it is the link the candidate would otherwise receive by email, and sending it is then up to you. Contact support@crosschq.com to have the setting enabled.
{
"request_id": "cd9447e1450c446a9d97c7b67ad1587f",
"welcome_url": "https://app.crosschq.com/p/cd9447e1450c446a9d97c7b67ad1587f/welcome?source=api"
}
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.
Create Reference Request in Bulk
/api/v2/reference-request/bulk/ [POST]Creates up to 25 reference requests in one call. Every item is validated and created on its own terms: one item failing does not stop the others, and it does not roll back the ones that succeeded. The operation is not atomic. To retry, resubmit only the items whose slots failed — resubmitting the whole batch creates the successful ones a second time.
Request Body
- requests a list of 1 to 25 items. Each item is the same body the Create Reference Request endpoint accepts.
- provisional_id optional, on each item: a string of 1 to 100 characters that is your own correlation key. Crosschq does not interpret it and does not generate it; it is echoed back verbatim on that item’s result slot. It must be unique within the batch.
{
"requests": [
{
"provisional_id": "your-own-key-001",
"candidate": {
"first_name": "Mike",
"last_name": "Fitz",
"email": "mike@yourcompany.com",
"mobile_phone": "+13239393939"
},
"jobrole": "business-consultant",
"requestor": "hiring@yourcompany.com",
"use_sms": false,
"flex_params": {
"relationships": [
{"rel": "any", "required": 2}
]
}
},
{
"candidate": {
"first_name": "Sam",
"last_name": "Reyes",
"email": "sam@yourcompany.com",
"mobile_phone": "+13239393940"
},
"jobrole": "business-consultant",
"requestor": "hiring@yourcompany.com",
"use_sms": false,
"flex_params": {
"relationships": [
{"rel": "any", "required": 2}
]
}
}
]
}
Response
A batch that ran answers 207, whatever the individual items did:
{
"batch_id": "0f7c1b4a9e2f43c0b6d1f5a8c3e79b21",
"created": 1,
"failed": 2,
"results": [
{
"index": 0,
"status": 201,
"request_id": "cd9447e1450c446a9d97c7b67ad1587f",
"welcome_url": "https://app.crosschq.com/p/cd9447e1450c446a9d97c7b67ad1587f/welcome?source=api",
"provisional_id": "your-own-key-001"
},
{
"index": 1,
"status": 400,
"errors": {
"candidate": {
"email": ["This field is required."]
}
}
},
{
"index": 2,
"status": 409,
"errors": {
"non_field_errors": ["Candidate already have ongoing reference requests"]
}
}
]
}
- batch_id identifies this call. Crosschq mints it and returns it on every outcome, including the whole-batch rejections below. It is the value to quote when reporting a problem with a batch, and for a batch that was rejected whole it is the only handle there is.
- created and failed count the slots. They always add up to the length of results.
- results holds one slot per submitted item, in the order they were submitted:
results[i]is the outcome ofrequests[i]. The array is never shortened and never reordered, so the index is always meaningful.
Each slot carries:
- index the position of the item in the requests array you sent.
- status that item’s own status, listed below.
- request_id the id of the created reference request. Always present on a 201. On a 409 it is present only if your account has the setting that returns the id of an existing ongoing request, so treat it as optional.
- welcome_url on a 201: the candidate’s welcome link when the item was sent with
skip_first_communication: trueand your account has the return welcome URL setting enabled, an empty string otherwise. - errors on a failed slot: either a map of field names to messages, or
{"non_field_errors": [...]}. - provisional_id echoed on every outcome for an item that sent one. On an item that did not, the key is absent — not
null.
The statuses a slot can carry:
- 201 the item was accepted for creation.
- 400 the item did not validate. Validation runs before the seat check, so an invalid item is refused on its own terms and never consumes a seat.
- 409 the item is valid but could not be created: your organization has no open seat available or has reached its monthly number of requests, the candidate already has an ongoing reference request, or the same candidate appears more than once in this batch — in which case the first occurrence is created and the later ones fail.
- 500 an unexpected failure affecting that item alone. The rest of the batch is unaffected and the response is still a 207.
- 502 Crosschq returned no result for that item. Nothing is known about it: it may or may not have been created.
A 201 means accepted for creation, not created. The reference request itself is created asynchronously a short time after the response, and the candidate’s email/SMS is sent then — not while you are waiting. In the ordinary case this takes seconds, and until it completes the request_id is not yet retrievable.
Whole-batch failures
Some failures stop the batch before any item is created. They answer with a batch_id and errors, and — the part worth branching on — no results key at all. Its absence is how you tell “the batch never ran” from “some items failed” without reading any message.
{
"batch_id": "0f7c1b4a9e2f43c0b6d1f5a8c3e79b21",
"errors": {
"requests": ["requests must hold between 1 and 25 items"]
}
}
- 400 requests is missing, is not a list, is empty, or holds more than 25 items; or the same provisional_id appears on more than one item.
- 408 the request took longer than Crosschq’s 90-second budget. The batch may still be being processed, so poll before resending it.
- 502 Crosschq could not be reached, or answered with something that could not be read.
- 404 the bulk endpoint is not available. The message says so explicitly.
Bulk calls are rate limited to 180 batches per hour, counted separately from the limit on single creates.
Using what the batch created
A request created in bulk is an ordinary reference request. Its request_id works with every endpoint in this article — retrieve, cancel, conclude, edit, send reminder and download report — and it reports through the same 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.
If no references are required to conclude the request, the relationships field in flex_params should be sent as an empty list. Here's a valid example:
{
"candidate": {
"team_id": "12206020-dccb-4859-8f3e-8dc55d2d08f1"
"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": []
},
"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"
}
}
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 accepts the request and accesses 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 submits 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 provides 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"
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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 provides 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"
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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 provides 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"
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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 provide 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"
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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"
"tags": [],You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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"
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
}
],
"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"
}
Failure Webhooks
In addition to success webhooks, the API also sends a webhook notification when a request cannot be processed. These events allow you to capture and handle failures programmatically (e.g., logging, retrying, or notifying end users).
{ "request_id": "05bae09667e34acf92c0c7d771f968a4",
"message": "Candidate already has an ongoing reference request"
"ongoing_request_id": "ffb8481ed4eb44fb91f5bd2873a89f6c",
}
{
"request_id": "dae9488896d24565bcdcc095ff2c6342",
"message": "The org is not active",
}
{
"request_id": "8aee3e14af4740d8bc8428bdbd13082c",
"message": "Candidate does not exist.",
}
{
"request_id": "4f4a34bfff134caeb7fc2f308e87f3e1",
"message": "Missing or invalid job role.",
}
{
"request_id": "e4da6618f2e841e8be7813d1d9f3de6f",
"message": "Missing key -required | rel- in flex_params",
}
{
"request_id": "d59a004f590f479ca00d0d32ae057397",
"message": "Relationship(XXX) is invalid",
}
Webhooks with Survey Answers
You can also receive candidates and references' answers within the webhooks.
Below you can see a sample payload. The information provided in the payloads may differ depending on the survey chosen.
You will receive the candidate's answers within the "Assigning" webhook, and references' answers within the "Collecting" webhook.
To activate webhooks containing survey responses, please contact support@crosschq.com.
{
"id": "31618d85bb4146788422eb014950b5de",
"candidate": {
"first_name": "Sam",
"last_name": "Smith",
"mobile_phone": "+13234441234",
"email": "samsmith@crosschq.com",
"answers": [
{
"type": "radiogroup",
"answer": "Somewhat",
"section": "General Questions",
"codename": "ethics",
"question": "Would you say you are an honest person with a strong code of ethics?"
},
{
"type": "checkbox",
"answer": [
"Written skills"
],
"section": "Key Skills and Areas for Improvement",
"codename": "strengths",
"question": "Which of these skills do you think you've mastered?"
},
{
"type": "checkbox",
"answer": [
"Listening to others"
],
"section": "Key Skills and Areas for Improvement",
"codename": "weaknesses",
"question": "Which of these skills do you need to work on?"
},
{
"type": "rating",
"answer": 3,
"section": "Candidate Comparison",
"codename": "performance",
"question": "Using the following 1-5 scale, how would you assess your overall job performance when compared to others that you’ve worked with?"
},
{
"type": "radiogroup",
"answer": "No",
"section": "Workplace Safety",
"codename": "was_unethical",
"question": "Workplace Safety"
},
{
"type": "text",
"answer": "I am a great colleague and a committed worker",
"section": "Open Ended Questions",
"codename": "possitive_things",
"question": "What are the most positive things about your working style?"
},
{
"type": "text",
"answer": "",
"section": "Open Ended Questions",
"codename": "any_other_comment",
"question": "Do you have any additional comments to add?"
},
{
"type": "matrix",
"answer": {
"Optimism": 3,
"Intelligence": 4,
"Attention to detail": 2,
"Handles stress well": 1,
"Takes feedback well": 3,
"Communication skills": 2,
"Enjoyable to work with": 5,
"Consistent delivery of quality work": 4,
"Willingness to go above and beyond for the job": 4
},
"section": "Candidate Comparison",
"codename": "compared_to_others",
"question": "How would you rate yourself on these attributes?"
},
{
"type": "text",
"answer": "I should improve for future projects",
"section": "Open Ended Questions",
"codename": "areas_for_improvement",
"question": "What feedback do you remember receiving about your possible areas for improvement?"
},
{
"type": "matrix",
"answer": {
"General expertise as a statistician": 3,
"Collecting, managing and analyzing data": 4,
"Working with and advising clinical investigators": 2,
"Developing new innovative statistical analytical processes": 4,
"Facilitating design of research projects and publication of results": 5
},
"section": "Job Competencies",
"codename": "biostatistician_compare_others",
"question": "On a 1-5 scale (1 = Okay and 5 = Best), how would you rank your skills in comparison to others you've worked with?"
},
{
"type": "radiogroup",
"answer": "Working remotely would not have an impact on performance",
"section": "General Questions",
"codename": "remote_working_productivity_impact",
"question": "If you were asked to work from home for an extended period of time, do you think it would significantly impact your productivity?"
}
]
},
"job_position": "Business Manager",
"status": "assigning",
"status_message": "Assigning",
"status_updated_on": "2023-05-31T15:59:04.911Z",
"progress": 50,
"references": [
{
"first_name": "mike",
"last_name": "harrison",
"mobile_phone": "+13234441234",
"email": "mikeharrison@crosschq.com",
"status": "completed",
"relationship": "peers",
"workplace_name": "evergreen",
"job_title": "dev",
"tags": [], You can add tags to your candidate's references. Reach out to support@crosschq.com to provide the labels.
"opted_in": false,
"answers": [
{
"type": "radiogroup",
"answer": "Somewhat",
"section": "General Questions",
"codename": "ethics",
"question": "Would you say Sam Smith is an honest person with a strong code of ethics?"
},
{
"answer": "no"
},
{
"type": "checkbox",
"answer": [
"Listening to others"
],
"section": "Key Skills and Areas for Improvement",
"codename": "strengths",
"question": "Which of these skills has Sam Smith mastered?"
},
{
"type": "checkbox",
"answer": [
"Working within a team"
],
"section": "Key Skills and Areas for Improvement",
"codename": "weaknesses",
"question": "Which of these skills should Sam Smith focus on improving?"
},
{
"type": "rating",
"answer": 4,
"section": "Candidate Comparison",
"codename": "performance",
"question": "Based on your experience working with Sam Smith, how would you assess their overall performance on a scale of 1-5?"
},
{
"type": "radiogroup",
"answer": "Yes, more than once",
"section": "General Questions",
"codename": "was_promoted",
"question": "Was Sam Smith ever promoted when you worked together at COMPANY?"
},
{
"type": "radiogroup",
"answer": "No",
"section": "Workplace Safety",
"codename": "was_unethical",
"question": "Workplace Safety"
},
{
"type": "text",
"answer": "He is an excellent colleague and team member. He is super empathetic and attentive to details.",
"section": "Open Ended Questions",
"codename": "possitive_things",
"question": "What were the most positive things you remember about Sam Smith?"
},
{
"type": "text",
"answer": "None",
"section": "Open Ended Questions",
"codename": "any_other_comment",
"question": "Do you have any additional comments to add about Sam Smith?"
},
{
"type": "radiogroup",
"answer": "No",
"section": "General Questions",
"codename": "leave_the_company",
"question": "Did Sam Smith leave their job at COMPANY?"
},
{
"type": "matrix",
"answer": {
"Optimism": 5,
"Intelligence": 5,
"Attention to detail": 5,
"Handles stress well": 2,
"Takes feedback well": 4,
"Communication skills": 2,
"Enjoyable to work with": 4,
"Consistent delivery of quality work": 3,
"Willingness to go above and beyond for the job": null
},
"section": "Candidate Comparison",
"codename": "compared_to_others",
"question": "How would you rate Sam Smith on these attributes as compared to others you’ve worked with?"
},
{
"type": "radiogroup",
"answer": "Maybe, depending on the job’s requirements",
"section": "General Questions",
"codename": "would_you_recommend",
"question": "If you had the opportunity, would you recommend Sam Smith for hire at your current company?"
},
{
"type": "text",
"answer": "Improve soft skills",
"section": "Open Ended Questions",
"codename": "areas_for_improvement",
"question": "What feedback do you remember sharing with Sam Smith about areas for improvement?"
},
{
"type": "matrix",
"answer": {
"General expertise as a statistician": 3,
"Collecting, managing and analyzing data": 5,
"Working with and advising clinical investigators": 4,
"Developing new innovative statistical analytical processes": null,
"Facilitating design of research projects and publication of results": 4
},
"section": "Job Competencies",
"codename": "biostatistician_compare_others",
"question": "On a 1-5 scale (1 = Okay and 5 = Best), how would you rank Sam Smith's skills as compared to others you've worked with?"
},
{
"type": "radiogroup",
"answer": "Working remotely would negatively affect performance",
"section": "General Questions",
"codename": "remote_working_productivity_impact",
"question": "If Sam Smith were required to work from home for an extended period of time, do you think it would significantly impact their productivity?"
}
]
}
],
"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"
}