Assessment Web Service

A web service which can be used to request assessments and receive candidate results.

Authentication

Before you can access the bulk of the assessment web service, you'll need to authenticate your platform. In order do that, you'll need the following pieces of information which should have been provided to you by your pymetrics representative.

Credentials

Key	Description
Client ID	Your unique identifier in our system
Client Secret	Use this to authenticate to use the webservice

Walkthrough

For a full walkthrough, see the Walkthrough section below.

Refreshing A Session

If a session expires, follow the below steps to reauthenticate and create a new session:

                        status = client.service.get_status(order.id, _soapheaders=[header])
-> Exception: Your session has expired. Please use the AuthenticationService to renew it.

# Renew your session token
SESSION_ID = client.service.authenticate(CLIENT_ID, CLIENT_SECRET)

# Update SOAP Headers
header_factory = xsd.Element(
    "{pym.intg.ws}RequestHeader",
    xsd.ComplexType([
        xsd.Element("{https://www.staging.pymetrics.com/integrations/webservice/wsdl/}client_id", xsd.String()),
        xsd.Element("{https://www.staging.pymetrics.com/integrations/webservice/wsdl/}session_id", xsd.String()),
    ])
)
header = header_factory(client_id=client_id, session_id=session_id)

# Retry Request
status = client.service.get_status(order.id, _soapheaders=[header])
-> "COMPLETED"
                    

Methods

After authenticating your platform, you will be presented with the following methods:

Request Assessment

Creating an assessment request is the entry point in to the system. An assessment request consists of the following:

Field Name	Type	Usage
assessment_id	int	Assessment identification number provided by pymetrics. Used to identify which model the candidate should be scored against.
external_id	string	Candidate identification number from your (partner's) system in order to properly correlate the candidates that go through the integration.
first_name	string	Candidate's first name.
last_name	string	Candidate's last name.
email	string	Candidate's email.
gender	string	Optional. Candidate's gender ("Male", "Female", "Other")
city	string	Optional. City in which candidate resides.
country	string	Optional. Country in which candidate resides.
application_locale	string	Optional. Locale code of language in which assessment should be administered. By default, candidates will be given a dropdown from which they can choose which language they prefer to use. If you desired to have the assessment administered in Chinese, you would denote "zh".

Once an assessment order is requested, you will receive an order ID back. The only way to access that assessment is to save and use the provided order ID.

Get Status

Ensure that the the order ID from "Request Assessment" has been saved. The API returns one of the following statuses:

Status	Meaning
PENDING	Request for an assessment has been received, but pymetrics has not approved it.
ACCEPTED	Request for an assessment has been received AND approved. Assessment URL provided is now usable
NOT_STARTED	Candidate has come to pymetrics and created an account but has NOT started the games.
IN_PROGRESS	Candidate has started, but has not completed, the assessment.
COMPLETED	Candidate has completed the games. Results have not been transferred to requesting partner.
FULFILLED	Results have been transferred to requesting partner.

Once the status reached "COMPLETED", the candidate's results are available. Then, and only then, can you fetch a candidate's results.

Get Results

Ensure that the the order ID from "Request Assessment" has been saved. This RPC call will return a float, which is the candidates fitscore.

Get Report

pymetrics provides a summary report of the candidate's results as well. Using the order ID from "Request Assessment", make the RPC call. It will return a string, which is a URL to access the candidate's report.

Walkthrough

Written in Python with Zeep SOAP Client library

1. Begin by creating a client with the WSDL provided by pymetrics

   from zeep import Client, xsd
   client = Client("https://www.pymetrics.com/integrations/webservice/wsdl/") 
                       

2. Ensure that the service is up and running

   client.service.echo("Hello World!")
   -> Hello World!
                       

3. Authenticate the interactions with the webservice. Provide the client_id/client_secret in the following way:

   session_id = client.service.authenticate(CLIENT_ID, CLIENT_SECRET)
                         

   • NOTE: Each session is valid for ONE hour

4. With the session_id, you can now interact with the AssessmentService. Create a RequestHeader to be attached to all requests made:

   header_factory = xsd.Element(
       "{pym.intg.ws}RequestHeader",
       xsd.ComplexType([
           xsd.Element("{https://www.staging.pymetrics.com/integrations/webservice/wsdl/}client_id", xsd.String()),
           xsd.Element("{https://www.staging.pymetrics.com/integrations/webservice/wsdl/}session_id", xsd.String()),
       ])
   )
   header = header_factory(client_id=client_id, session_id=session_id)
                         

5. Request an assessment order

   aor = client.get_type("{integrations.webservice.ws_models}AssessmentOrderRequest")()
   aor.first_name = "John"
   aor.last_name = "Smith"
   .
   .
   .
   order = client.service.request_assessment(aor, _soapheaders=[header])
                         

6. Poll the assessment order status until it becomes COMPLETED

   status = client.service.get_status(order.id, _soapheaders=[header])
   while status != "COMPLETED":
       time.sleep(3 * 60 * 60)   # 3 hours
       status = client.service.get_status(order.id, _soapheaders=[header])
   results = client.service.get_results(order.id, _soapheaders=[header])
   report = client.service.get_report(order.id, _soapheaders=[header])