pymetrics Assessment API (1.3.0)

Download OpenAPI specification:Download

This is pymetrics's public API for assessments, usually as part of a job application workflow.

The typical use case for this is to support an externally initiated assessment for a candidate job application. This is often done "inline" with the candidate's application, or asynchronously after the candidate submits their application.

The expected sequence of API calls is:

  • Generate OAuth Token with the OAuth Client ID and Secret you've been provided
  • Get Assessment Configurations to determine which configured assessment templates are available
  • Create Assessment Order for a selected Assessment and candidate job application
  • Get Assessment Order to receive the recommendation results, once they are available

Generate OAuth Token

The response's bearer token must be used in the Authorization header for any other API request. Tokens are valid for only a period of time.

All requests, with the exception of this one, also require an API Key to be supplied in the X-Api-Key request header. pymetrics will supply this along with the OAuth Client ID and Secret.

Request Body schema: application/json

OAuth2 Client Credentials

client_id
required
string (Client Id)

OAuth Client ID provided during setup

client_secret
required
string (Client Secret)

OAuth Client Secret provided during setup

grant_type
required
string (Grant Type)

Usually set to client_credentials

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "grant_type": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "scope": "string"
}

Get Assessment Configurations

Lists the assessment templates that are currently registered for your integration. These are configured outside of the API, and represent the different candidate experiences for each role pymetrics is being leveraged for.

header Parameters
Authorization
string

Standard Bearer token request, from Generate OAuth Token. Formatted Bearer {token}

X-Api-Key
string

Mandatory API Key that pymetrics will provide

Responses

Response samples

Content type
application/json
{
  • "assessments": [
    ]
}

Create Assessment Order

Creates an assessment order for a candidate. This represents the transaction for a candidate's job application.

This is an idempotent operation, and may return an existing assessment order. The following inputs constitute the uniqueness criteria:

  • candidate.email
  • assessment_id
  • application_id
header Parameters
Authorization
string

Standard Bearer token request, from Generate OAuth Token. Formatted Bearer {token}

X-Api-Key
string

Mandatory API Key that pymetrics will provide

Request Body schema: application/json

Candidate, assessment, and job application details

required
object (MercuryCandidate)
assessment_id
required
string <uuid> (Assessment Id)

One component of the uniqueness and idempotency criteria. Must be one of the assessment.id values from Get Assessment Configurations

send_email
boolean (Send Email)
Default: false

If true, pymetrics will send an invitation email to the candidate

application_id
required
string (Application Id)

One component of the uniqueness and idempotency criteria. This should relate to your system's job application ID

requisition_id
string (Requisition Id)

This will be returned in future API responses

requisition_title
string (Requisition Title)

This can be used in email templates if pymetricswill be sending candidates invitation emails. This will be returned in future API responses

metadata
object (Metadata)

List of key-value pairs that will returned in future API responses

candidate_redirect_url
string <uri> (Candidate Redirect Url) [ 1 .. 65536 ] characters

A URL that redirects candidates back to their respective ATS

Responses

Request samples

Content type
application/json
{
  • "candidate": {
    },
  • "assessment_id": "9f60a03f-b3de-4b19-9361-0380d9aa1e9e",
  • "send_email": false,
  • "application_id": "string",
  • "requisition_id": "string",
  • "requisition_title": "string",
  • "metadata": { },
  • "candidate_redirect_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "order": {
    },
  • "created": true
}

Get Assessment Order

Get an existing order by ID. It will move from Completed to Fulfilled if the order has results.

path Parameters
id
required
string

The Order ID value from creating the order. The create operation is idempotent, based on candidate.email, assessment_id, and application_id

query Parameters
report
boolean

Set to true to optionally force a report to be generated if one does not exist

header Parameters
Authorization
string

Standard Bearer token request, from Generate OAuth Token. Formatted Bearer {token}

X-Api-Key
string

Mandatory API Key that pymetrics will provide

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invite_link": "http://example.com",
  • "status": "Rejected",
  • "create_date": "2019-08-24T14:15:22Z",
  • "candidate": {
    },
  • "assessment_id": "9f60a03f-b3de-4b19-9361-0380d9aa1e9e",
  • "assessment": {
    },
  • "application_id": "string",
  • "ats_type": "adp",
  • "requisition_id": "string",
  • "requisition_title": "string",
  • "metadata": { },
  • "recruiter_report": "http://example.com",
  • "results": [
    ],
  • "reports": [
    ],
  • "candidate_redirect_url": "http://example.com"
}

List Assessment Orders

Get a list of Assessment Orders by either job application ID and/or candidate ID. At least one of the IDs must be provided.

header Parameters
Authorization
string

Standard Bearer token request, from Generate OAuth Token. Formatted Bearer {token}

X-Api-Key
string

Mandatory API Key that pymetrics will provide

Request Body schema: application/json

Job application ID or candidate ID

job_application_id
string (Job Application Id)

Job application ID by which to optionally filter on

candidate_id
string (Candidate Id)

Candidate ID by which to optionally filter on

Responses

Request samples

Content type
application/json
{
  • "job_application_id": "string",
  • "candidate_id": "string"
}

Response samples

Content type
application/json
{
  • "orders": [