1. Help Center
  2. Setting Up Connectors

Crosschq Partner API v2

Enabling Crosschq Partner API v2

Introduction

Crosschq’s Partner API are REST APIs that let third parties 1) trigger a Crosschq request for references; 2) monitor and manage the progress of the request; and 3) 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 environment for testing, located at https://sandbox-partner.crosschq.com/ and Swagger is available in the sandbox environment.

The base URL for the production API is https://partner.crosschq.com/. When you have fully tested your API in our Sandbox environment, please contact Crosschq’s support team at support@crosschq.com to enable the production environment for your account.

Get postman collection

This is the documentation for version 2.0.0 of the API. Last update on March. 27, 2021.

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 a “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 a dictionary with the basic candidate information (first_name, last_name, email, mobile_phone).
  • jobrole the jobrole codename obtained with the jobroles endpoint
  • requestor the email for the owner of the request in Crosschq, if there is no such user in Crosschq, the request will be owned by the Organization Owner
  • 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 a 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": [],
"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_message": "Sent",
}

Reference Request Edit /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
}

Reference Request Cancel /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.

Reference Request Conclude /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 /api/v2/reference-request/{req_uid}/send-reminder/ [POST]

This enpoint can be used to send a reminder to the candidate.

Params

  • req_uid the id for the reference request.

Download Report /api/v2/reference-request/{req_uid}/download-report/ [GET]

This enpoint 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

  • report [optional] 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.
To receive webhook notifications you must provide a URL to Crosschq support during API setup that will be called with a POST request. The data sent via this POST request is the same as that provided by the Reference Request Retrieve endpoint:
{
"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"
}