menu

Assessment Web Service V3

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

WSDL

Access the webservice at the following URLs:

https:///integrations/webservice/v3/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.3.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.3.0.0">
    <soap11env:Body>
        <tns:authenticateResponse>
            <tns:authenticateResult xsi:type="s1:AuthenticationResponseV3">
                <s1:session_id>SESSION_TOKEN<s1:session_id>
                <s1:expiry_period>EXPIRY_PERIOD_SECONDS<s1:expiry_period>
            </tns:authenticateResult>
        </tns:authenticateResponse>
    </soap11env:Body>
</soap11env:Envelope>
Session Expiration

Session tokens expire after time specified in EXPIRY_PERIOD_SECONDS. 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 Yes Returns whatever you send. Useful for initial testing
ListAssessments Yes Lists assessments
RequestAssessmentOrder 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
Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.3.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.3.0.0">
    <soap11env:Body>
        <tns:echoResponse>
            <tns:echoResult>ECHO</tns:echoResult>
        </tns:echoResponse>
    </soap11env:Body>
</soap11env:Envelope>
List Assessments

Lists active and available assessments belonging to organization represented by organization_id.

Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.3.0.0">
    <soapenv:Header>
        <pym:RequestHeader>
            <pym:session_id></pym:session_id>
            <pym:client_id></pym:client_id>
        </pym:RequestHeader>
    </soapenv:Header>
    <soapenv:Body>
    <pym:list_assessments>
        <pym:organization>
            <str:organization_id>XYZ123</str:organization_id>
        </pym:organization>
    </pym:request_assessment>
</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.3.0.0">
    <soap11env:Body>
        <tns:list_assessmentsResponse>
            <tns:list_assessmentResult>
                <s1:assessment_id>33</s1:assessment_id>
                <s1:assessment_name>Job Assessment</s1:assessment_name>
                <s1:assessment_type>Numerical and Logical Reasoning</s1:assessment_type>
            </tns:list_assessmentResult>
            <tns:list_assessmentResult>
            .
            .
            .
            </tns:list_assessmentResult>
        </pym:list_assessmentsResponse>
    </soapenv:Body>
</soap11env:Envelope>
Request Assessment

Creating an assessment request is the entry point in to the system. Note that you may create multiple orders with the same external_id. During results retrieval in the get_bulk_results operation, the service will return results for all orders sharing the external_id. The typical use case is to supply a job application ID. 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.3.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>
        <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>Male</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.3.0.0">
    <soap11env:Body>
        <tns:request_assessment_orderResponse>
            <tns:request_assessment_orderResult>
                <s1:success>true</s1:success>
                <s1:order_id>13263</s1:order_id>
                <s1:assessment_url>https://www.pymetrics.com/invite/sc.c52bc90ddf1e43e3be70e71b285ca4d5/</s1:assessment_url>
            </tns:request_assessment_orderResult>
        </tns:request_assessment_orderResponse>
    </soap11env:Body>
</soap11env:Envelope>

Get Bulk Status

This endpoint accepts one or more order IDs, and returns their 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.

evaluation_url is available in the response if the candidate is eligible for video evaluation

Sample Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.3.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:integer>13268</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.3.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:assessment_id>2019</s1:assessment_id>
                    <s1:assessment_type>Games</s1:assessment_type>
                    <s1:invite_url>https://www.pymetrics.com/invite/sc.c52bc90ddf1e43e3be70e71b285ca4d5/</s1:invite_url>
                </s1:AssessmentStatus>
                <s1:AssessmentStatus>
                    <s1:status>COMPLETED</s1:status>
                    <s1:order_id>13268</s1:order_id>
                    <s1:assessment_id>2025</s1:assessment_id>
                    <s1:assessment_type>Video</s1:assessment_type>
                    <s1:invite_url>https://www.pymetrics.com/invite/sc.c52bc90ddf1e43e3be70e71b285ca4d5/</s1:invite_url>
                    <s1:evaluation_url>https://www.pymetrics.com/video/evaluation/245/677/</s1:evaluation_url>
                </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. This operation will return assessment results for each order identified in the request input, as well as any other order that shares the same external_id value and also has available assessment results. A request for a single order id may return results for multiple assessment orders.

Sample Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pym="pym.intg.ws.3.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.3.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>Highly Recommend</s1:band>
                    <s1:passed>true</s1:passed>
                    <s1:external_id>your_external_id_here</s1:external_id>
                    <s1:assessment_id>2019</s1:assessment_id>
                    <s1:assessment_type>Games</s1:assessment_type>
                </s1:AssessmentResultFullResponse>
            </tns:get_bulk_resultsResult>
            <tns:get_bulk_resultsResult>
            .
            .
            .
            </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.
external_id string Candidate identification number from your (partner's) system in order to properly correlate the candidates that go through the integration.
assessment_id int Assessment identification number provided by pymetrics. Used to identify which model the candidate should be scored against.
assessment_type string The type of assessment that the candidate will complete. Eg: "Games" or "Video"
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.3.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.3.0.0">
    <soap11env:Body>
        <tns:get_reportResponse>
            <tns:get_reportResult>
                <s1:report_url>https://www.pymetrics.com/results/downloads/assessments/?invite_hash=1c6efdbab78wefc486eacb1fe651adb274b</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://www.pymetrics.com/integrations/webservice/v3/wsdl/") 
  2. 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
  3. With the session_id, you can now interact with the AssessmentServiceV3. Create a RequestHeader to be attached to all requests made:

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

  4. Ensure that the service is up and running
    client.service.echo("Hello World!")
    -> Hello World!
  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.3.0.0}RequestHeader",
    xsd.ComplexType([
        xsd.Element("{https://www.pymetrics.com/integrations/webservice/v3/wsdl/}client_id", xsd.String()),
        xsd.Element("{https://www.pymetrics.com/integrations/webservice/v3/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"