1. Help Center
  2. Setting Up Connectors

Crosschq Partner API

Crosschq's Partner API lets you trigger reference requests, monitor their status, and access 360 Reports when they're completed.

Crosschq's Partner API provides the means to trigger a Crosschq reference request, continuously monitor the request's status via a webhook, and then retrieve the final Crosschq 360 report when it's complete. This document describes the API endpoints, webhooks and common use cases.

View a Postman collection using this link:

Get postman collection

Authentication

Contact Crosschq's support team at support@crosschq.com to request access to these Crosschq APIs. Upon approval, you'll be issued a token that must be sent on an AUTHORIZATION header with each request.

Endpoints

Config /partners/config/

This endpoint returns configuration parameters required for a reference request along with the relationships (for example, "Manager" or "Direct report") that can be used when creating a request for references.

  • min_reference_count indicates the minimum number of references required for a request.
  • relationships includes a dictionary for each available relationship.
    • id: the relationship to use in the config_params for the request.
    • name: the label used on the Crosschq Application to display this relationship.
    • minmax and default: the range of values for each relationship, and the default number shown within the Crosschq Application, for this account.
{
"relationships": [
{
"id": "managers",
"name": "Manager",
"min": "0",
"max": "10",
"default": "2"
},
{
"id": "employees",
"name": "Direct Report",
"min": "0",
"max": "10",
"default": "2"
},
{
"id": "peers",
"name": "Coworker/Peer",
"min": "0",
"max": "10",
"default": "2"
},
{
"id": "business",
"name": "Customer/Supplier",
"min": "0",
"max": "10",
"default": "2"
},
{
"id": "social",
"name": "Mentor",
"min": "0",
"max": "10",
"default": "2"
}
],
"min_reference_count": 2
}

JobRoles /partners/jobroles/

Each JobRole represents a survey that can be used for the Reference Request. JobRoles/Surveys are enabled/disabled for an account via a settings screen in the Crosschq Application.

  • id: the identification for the survey that must be used to trigger the Reference Request process.
  • name: the label that is used in the Crosschq Application to identify this JobRole
[
{
"id": "brand-marketer-manager",
"name": "Brand Marketer - Manager"
},
{
"id": "brand-marketer-team-member",
"name": "Brand Marketer - Team Member"
},
{
"id": "clinic-support-manager",
"name": "Clinic Support - Manager"
},
{
"id": "clinic-support-team-member",
"name": "Clinic Support - Team Member"
},
{
"id": "customer-service-manager",
"name": "Customer Service - Manager"
},
{
"id": "customer-service-member",
"name": "Customer Service - Team Member"
},
{
"id": "delivery-driver",
"name": "Delivery Driver"
},
{
"id": "digital-marketer-manager",
"name": "Digital Marketer - Manager"
},
{
"id": "digital-marketer-team-member",
"name": "Digital Marketer - Team Member"
},
{
"id": "engineer-manager",
"name": "Engineer – Manager"
},
{
"id": "engineer-team-member",
"name": "Engineer – Team Member"
},
{
"id": "general-clinician-manager",
"name": "General Clinician - Manager"
},
{
"id": "general-clinician-team-member",
"name": "General Clinician - Team Member"
},
{
"id": "general-manager",
"name": "General/Universal - Manager"
},
{
"id": "general-team-member-1",
"name": "General/Universal - Team Member"
}
]

Create Reference Request /partners/reference-request/ [POST]

This endpoint starts the Reference Request process and initiates a request for references from a candidate.

Request Body

  • candidate: a dictionary with the basic candidate information (first_name, last_name, email, mobile_phone)
  • jobrole: the jobrole id obtained with the jobroles endpoint
  • requestor:  the email address of the Crosschq team member that is the owner of the request. If there is no such team member in account, the request will be owned by the Organization Owner.
  • use_sms: flag to send/not send SMS messages to the candidate.
  • config_params: the dictionary is the configuration for the Reference Request
    • all the relationships that will be required for the reference request must be present (manages, employees, peers, business, social).
    • the quantities must be consistent with the min/max numbers provided on the config endpoint.
  • send_past_due_notification: flag that determines if Crosschq should send email and/or SMS reminders to the candidate if the request is past-due.
  • send_completed_notification: flag that determines if Crosschq should send a completion notification to the team member that owns the request.
  • 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": "John",
"last_name": "Candidate",
"email": "devops+johncandidate@crosschq.com",
"mobile_phone": "+13234441234"
},
"jobrole": "brand-marketer-manager",
"requestor": "devops+user1@crosschq.com",
"use_sms": false,
"config_params": {
"managers": 2,
"employees": 0,
"peers": 0,
"business": 0,
"social": 0
},
"send_past_due_notification": false,
"send_completed_notification": false,
"job_position": "Business Manager",
"hiring_manager": {
"first_name": "Tito",
"last_name": "Hiring",
"email": "soler+hiringman@crosschq.com"
}
}

Response

The successful response for this endpoint is a request_id that can be used to retrieve information about the request and its progress.

{
"request_id": "cd9447e1450c446a9d97c7b67ad1587f"
}

If there is an error with the request, Crosschq will return a 400 status response similar to the one below.

{
"errors": {
"candidate": {
"email": [
"This field is required."
]
}
}
}

Retrieve Reference Request /partners/reference-request/{request_id}/

This endpoint returns information for a Reference Request. For an example response see below. If the request is not found the endpoint will return a 404 status.

{
"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://org.crosschq.dev/request/references/603a2d8f801a4799ab4eb3b40040587c/",
"report_summary_pdf": "https://fake-report-url/report-mike-fitz.pdf",
"report_full_pdf": "https://fake-report-url/report-mike-fitz-full.pdf",
"created_at": "2018-07-26T15:34:21.982332Z",
"updated_on": "2018-07-26T15:44:21.907327Z"
}

Webhooks

The partner-api includes a webhook that will be called each time a request changes status (sent, assigning, collection, completed, cancelled, declined). To setup this webhook, contact Crosschq at support@crosschq.com to provide us with a URL that will be called with via a POST request. The data sent via the webhook is identical to that returned with 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://org.crosschq.dev/request/references/603a2d8f801a4799ab4eb3b40040587c/",
"report_summary_pdf": "https://fake-report-url/report-mike-fitz.pdf",
"report_full_pdf": "https://fake-report-url/report-mike-fitz-full.pdf",
"created_at": "2018-07-26T15:34:21.982332Z",
"updated_on": "2018-07-26T15:44:21.907327Z"
}