menu

Assessment Web Service V2

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

WSDL

Access the webservice at the following URLs:

https://uat.pymetrics.com/integrations/webservice/v2/wsdl/
https://uat.pymetrics.com/integrations/webservice/v2/wsdl/
HTTP Headers

All requests should be sent with Content-Type: application/xml

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
XML

The XML body for an authentication request is as follows:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0">
    <soapenv:Header/>
    <soapenv:Body>
        <pym:authenticate>
          <pym:client_id>{{ client_id }}</pym:client_id>
          <pym:client_secret>{{ client_secret }}</pym:client_secret>
        </pym:authenticate>
    </soapenv:Body>
</soapenv:Envelope>

The expected response is:

<?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:authenticateResponse>
            <tns:authenticateResult>SESSION_TOKEN</tns:authenticateResult>
        </tns:authenticateResponse>
    </soap11env:Body>
</soap11env:Envelope>
Session Expiration

Session tokens expire after some time. Exipred sessions will receive a response with the following error test:

Your session has expired. Please use the AuthenticationService to renew it.

To refresh the session, use the authentication endpoint to retrieve a new session token.


Walkthrough

For a full walkthrough, see the Walkthrough section below.

Methods

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

Endpoint Authentication Required Description
Echo No Returns whatever you send. Useful for initial testing
Ping Yes Returns PONG. Useful for testing authentication
RequestAssessment Yes Create a new assessment order
GetBulkStatus Yes Returns the current status for multiple orders
GetBulkResults Yes Returns the scores for multiple orders
GetReport Yes Retrieve the recruiter report URL for an order
Echo

The only endpoint that does not require authentication.

Request
                    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0">
  <soapenv:Header/>
  <soapenv:Body>
    <pym:echo>
      <pym:echo>ECHO</pym:echo>
    </pym:echo>
  </soapenv:Body>
</soapenv:Envelope>
                
Response
                    <?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:echoResponse>
            <tns:echoResult>ECHO</tns:echoResult>
        </tns:echoResponse>
    </soap11env:Body>
</soap11env:Envelope>
                
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. ISO 639-1 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".
Important!

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.

Sample Request
                    
                    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0" xmlns:int="integrations.webservice.ws_models">
<soapenv:Header>
    <pym:RequestHeader>
        <pym:session_id>{{ session_id }}</pym:session_id>
        <pym:client_id>{{ client_id }}</pym:client_id>
    </pym:RequestHeader>
</soapenv:Header>
<soapenv:Body>
    <pym:request_assessment>
        <!--Optional:-->
        <pym:order>
            <int:city>New York</int:city>
            <int:first_name>Pass</int:first_name>
            <int:last_name>User</int:last_name>
            <int:callback_url>http://example.com/TEST1-0001</int:callback_url>
            <int:gender>Female</int:gender>
            <int:assessment_id>{{ assessment_id }}</int:assessment_id>
            <int:application_locale>en</int:application_locale>
            <int:country>US</int:country>
            <int:external_id>ATS-ID-0001</int:external_id>
            <int:email>pass.user@example.com</int:email>
        </pym:order>
    </pym:request_assessment>
</soapenv:Body>
</soapenv:Envelope>

                
Sample Response
                    <?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:s1="integrations.webservice.ws_models" xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:request_assessmentResponse>
            <tns:request_assessmentResult>
                <s1:success>true</s1:success>
                <s1:order_id>13263</s1:order_id>
                <s1:assessment_url>https://uat.pymetrics.com/c/company/candidate/invite/2/</s1:assessment_url>
            </tns:request_assessmentResult>
        </tns:request_assessmentResponse>
    </soap11env:Body>
</soap11env:Envelope>
                

Get Bulk Status

This endpoint accepts one or more order IDs, and returns thier status. The meaning of each order status is as follows:

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. Once this status is reached, you should begin polling the GetBulkResults endpoint for assessment results
FULFILLED Results have been transferred to requesting partner.
Note

There may be some delay after the order reaches COMPLETED status, before assessment results are ready.

Sample Request
                    
                    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0">
<soapenv:Header>
    <pym:RequestHeader>
        <pym:session_id>{{ session_id }}</pym:session_id>
        <pym:client_id>{{ client_id }}</pym:client_id>
    </pym:RequestHeader>
</soapenv:Header>
<soapenv:Body>
    <pym:get_bulk_status>
        <pym:order_ids>
            <pym:integer>13263</pym:integer>
        </pym:order_ids>
    </pym:get_bulk_status>
</soapenv:Body>
</soapenv:Envelope>

                
Sample Response
                    <?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:s1="integrations.webservice.ws_models" xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:get_bulk_statusResponse>
            <tns:get_bulk_statusResult>
                <s1:AssessmentStatus>
                    <s1:status>ACCEPTED</s1:status>
                    <s1:order_id>13263</s1:order_id>
                </s1:AssessmentStatus>
            </tns:get_bulk_statusResult>
        </tns:get_bulk_statusResponse>
    </soap11env:Body>
</soap11env:Envelope>
                

Get Bulk Results

Retrieve assessment scores for one or more orders. Orders should be in COMPLETED status before calling this endpoint.

Sample Request
                    
                    
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0">
<soapenv:Header>
    <pym:RequestHeader>
        <pym:session_id>{{ session_id }}</pym:session_id>
        <pym:client_id>{{ client_id }}</pym:client_id>
    </pym:RequestHeader>
</soapenv:Header>
<soapenv:Body>
    <pym:get_bulk_results>
        <pym:order_ids>
            <pym:integer>13263</pym:integer>
        </pym:order_ids>
    </pym:get_bulk_results>
</soapenv:Body>
</soapenv:Envelope>

                
Sample Response
                    <?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:s1="integrations.webservice.ws_models" xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:get_bulk_resultsResponse>
            <tns:get_bulk_resultsResult>
                <s1:AssessmentResultFullResponse>
                    <s1:create_date>2018-11-05T21:29:10+00:00</s1:create_date>
                    <s1:description>Data Scientist</s1:description>
                    <s1:order_id>13263</s1:order_id>
                    <s1:fitscore>90.0</s1:fitscore>
                    <s1:band></s1:band>
                    <s1:passed>true</s1:passed>
                </s1:AssessmentResultFullResponse>
            </tns:get_bulk_resultsResult>
        </tns:get_bulk_resultsResponse>
    </soap11env:Body>
</soap11env:Envelope>
                
Response Attributes
Field Name Type Description
create_date timestamp When the order was created.
description string The title of the position that the candidate applied to
order_id integer The pymetrics order ID
fitscore float Optional. The assessment result, expressed as a percentile
band string Optional. The assessment result, expressed as a string
passed boolean Optional. Whether or not the candidate passed the assessment.
A note on results

Depending on your configuration, you will recieve at least one of score and band, and may or may not also receive a passed boolean.


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.

Sample Request
                    
                    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.2.0.0">
<soapenv:Header>
    <pym:RequestHeader>
        <pym:session_id>{{ session_id }}</pym:session_id>
        <pym:client_id>{{ client_id }}</pym:client_id>
    </pym:RequestHeader>
</soapenv:Header>
<soapenv:Body>
    <pym:get_report>
        <pym:order_id>13263</pym:order_id>
    </pym:get_report>
</soapenv:Body>
</soapenv:Envelope>


                
Sample Response
                    <?xml version='1.0' encoding='UTF-8'?>
<soap11env:Envelope xmlns:s1="integrations.webservice.ws_models" xmlns:soap11env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="pym.intg.ws.2.0.0">
    <soap11env:Body>
        <tns:get_reportResponse>
            <tns:get_reportResult>
                <s1:report_url>https://uat.pymetrics.com/results/downloads/assessments/?invite_hash=1c6efdbab78wefc486eacb1fe651adb274b&amp;include_group=1</s1:report_url>
            </tns:get_reportResult>
        </tns:get_reportResponse>
    </soap11env:Body>
</soap11env:Envelope>
                

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://uat.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://uat.pymetrics.com/integrations/webservice/wsdl/}client_id", xsd.String()),
            xsd.Element("{https://uat.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])
                          

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://uat.pymetrics.com/integrations/webservice/wsdl/}client_id", xsd.String()),
        xsd.Element("{https://uat.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"