pymetrics documentation

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:

UAT
Production

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

https://www.pymetrics.com/integrations/webservice/v2/wsdl/

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

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/")

Ensure that the service is up and running

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

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

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)

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])

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"

Assessment Web Service V2

HTTP Headers

Authentication

Credentials

XML

Session Expiration

Walkthrough

Methods

Echo

Request

Response

Request Assessment

Sample Request

Sample Response

Get Bulk Status

Sample Request

Sample Response

Get Bulk Results

Sample Request

Sample Response

Response Attributes

Get Report

Sample Request

Sample Response

Walkthrough

Refreshing A Session