Documentation Powered by ReDoc

pymetrics API (2.2.1)

Download OpenAPI specification:Download

This is pymetrics's public API. The API can be used to get information on candidates as part of a job application workflow, or for employee career pathing and development.

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. This data can then be used for career pathing and employee development in subsequent stages.

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 and reports, once they are available

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": [
    ]
}

Get Capability Content

Gets the capability content for an assessment order by its ID.

path Parameters
uuid
required
string

The Order ID of the candidates order.

type
required
string

The Capability Report Type (talent, recruiter, manager).

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
{
  • "capabilities": [
    ],
  • "overall_capabilities_alignment": "Low Alignment",
  • "title": "string"
}

Get Factor Content

Gets the factor content for an assessment order by its ID.

path Parameters
uuid
required
string

The Order ID value from creating the order.

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
{
  • "factors": [
    ],
  • "order": {
    }
}

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

scope
string (Scope)

This is an optional field. If not specified, the token will be scoped to read write

Responses

Request samples

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

Response samples

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

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.

query Parameters
job_application_id
string

Job application ID by which to optionally filter on

candidate_id
string

Candidate ID by which to optionally filter on

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
{
  • "orders": [
    ]
}

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

application_id
required
string (Application Id)

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

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

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

A URL that redirects candidates back to their respective ATS

metadata
object (Metadata)

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

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

send_email
boolean (Send Email)
Default: false

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

Responses

Request samples

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

Response samples

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

Get Assessment Order

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

path Parameters
uuid
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
{
  • "application_id": "string",
  • "assessment": {
    },
  • "assessment_id": "9f60a03f-b3de-4b19-9361-0380d9aa1e9e",
  • "ats_type": "adp",
  • "candidate": {
    },
  • "candidate_redirect_url": "http://example.com",
  • "create_date": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "invite_link": "http://example.com",
  • "metadata": { },
  • "recruiter_report": "http://example.com",
  • "reports": [
    ],
  • "requisition_id": "string",
  • "requisition_title": "string",
  • "results": [
    ],
  • "status": "Rejected"
}