Developer API

Use the Podium Developer API to integrate Podium products into your online tools. Send invitations, gather results, review data, all via your own tools of choice. Contact us for more information.

Overview

The following guide provides detailed information on how to use the Podium API to:

Add participants
Invite participants to tests
Request results
Generate reports for participants

The Podium API provides a RESTful interface to its functionality and JSON is used for requests and responses.

The Podium API is secured through the use of JWT tokens which must be sent in the authorisation header of each request. Partners will use their secret API key to request tokens.

Each token will be valid for 1 hour after it is requested, at which point, it will expire, and a new token must be requested.

For more information on JWT tokens, please see: https://jwt.io/introduction

All interaction with the API must be done through HTTPS and TLS v 1.2 is enforced.

Getting Started

In order to use the API, you will need the following:

An API key. The key will be used to request a security token which is required to access the API.
The IDs for one or more Podium clients. Partners will access the API in the context of a specific client. Each client may have different reporting and assessment setups.
The IDs for various system components used in API calls which could be test, report, norm or role profile IDs.

These will be provided by Podium, depending on each client’s requirements.

Base URLs and Environments

Podium operates multiple regions. Use the API base URL for your tenant’s region. If unsure, contact support.

AU/NZ: https://integration-au.podium365.com/
EU/UK: https://integration-eu.podium365.com/
UAE: https://integration-uae.podium365.com/

We will confirm the url with partners when setting up their configuration.

Authentication

All requests must be authenticated. Obtain credentials from Podium and include them with each call.

HTTP Method:

POST

API Endpoint:

{{base-url}}/token

Request Parameters:

apiKey:  The secret key provided to each partner by Podium.

Example Request:

{"apiKey":"f402477b-36b0-484d-8d7f-e3d03e8f895a"}

Response Parameters:

token:  The JWT token which must be sent in the authorisation header of each request.

Example Response:

{"token":"eyJhbGciOiJIUzI1NiIsInR5scCI6IkpXVCJ9.eyJzdWIsiOiIxMjM0NTY3ODkswIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fsvwpMeJf36POk6yJV_adQsbbwsw5c"}

The token should be included in the header as followed:

Authorization: Bearer {{token}}

The token will expire after 1 hour.

Endpoints

Key endpoint groups typically include:

Candidates and Assessments: create and manage assessments for candidates
Invitations: send invitations, manage links and expiry
Results and Reports: fetch statuses, scores, and download reports
Webhooks/Callbacks: receive asynchronous notifications

Adding Participants

Create a new participant.

HTTP Method:

POST

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants

Request Parameters:

Parameter	Description
firstName	The first name of the participant.
lastName	The last name of the participant.
gender	The sex/gender of the participant. Male, Female, Other
emailAddress	The email address of the participant.
integrationPartnerParticipantId	The partner’s id for this participant. We will include it in future responses related to this participant.
integrationPartnerParticipantMetadata	A JSON object containing partner integration specific metadata about the participant. This data is stored and returned in future responses. (optional)

Example Request:

{
    "firstName": "Terence",
    "lastName": "Test",
    "gender": "m",
    "emailAddress": "terence.test@podium365.com",
    "integrationPartnerParticipantId": "partner-id1234",
    "integrationPartnerParticipantMetadata": {
        "candidateId": "cand-5678",
        "assessmentId": "assessabc123",
        "fieldId": "cognitive-aptitude",
        "testStatus": "in-progress"
    }
}

Response Parameters:

Parameter	Description
participantId	Podium’s id for this participant. Please store this for future calls.
integrationPartnerParticipantId	The partner’s id for this participant
participantAssessmentUrl	The url where this participant can access all their tests.

Example Response:

{
    "participantId": "1-1-49164582-ad37-45aa-abc5-c4d622824131",
    "integrationPartnerParticipantId": "partner-id-1234",
    "participantAssessmentUrl": "https://p-eu.podium365.com?loginKey=1-1-49164582ad37-45aa-abc5-c4d622824131"
}

Note:

The integrationPartnerParticipantMetadata field has a maximum size of 1000 characters. Do not include any sensitive personal information (e.g., passwords) in this field. It is intended only for non-sensitive integration metadata relevant to your application.

Assigning Tests to Participants

Assign one or more tests to a participant.

HTTP Method:

POST

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/tests

Request Parameters:

Parameter		Description
tests		Array of Test – see following rows.
	Test: testId	The id of the test that you want to assign.
	Test: languageId	The language to use for the test.
	Test: expiryDate	When the invitation should expire. (optional)
	Test: order	Forced order of completion for a given test. (optional)
expiryDate		The expiry date to apply to all tests added. If the expiryDate is provided for an individual test object, it will override this value. (optional)

Example Request:

{
    "tests": [
        {
            "testId": "test1",
            "languageId": "EN",
            "order":1
        },
        {
            "testId": "test2",
            "languageId": "EN",
            "order":2
        }
    ], 
    "expiryDate":"2018-12-31T23:59:59Z"
}

Response Parameters:

Parameter		Description
Invitations		Array of Invitation – see following row.
	Invitation: testId	The test id for the invitation.
	Invitation: invitationId	The unique invitation id. If a participant has more than one invitation for the same test, this will differentiate.

Example Response:

[
    {
        "testId": "test1",
        "invitationId": "a33384de-3ae5-43f3-a3bb-84832556e62b"
    },
    {
        "testId": "test2",
        "invitationId": "4012ed2d-6445-4aa0-a5f7-e5cadffe2c0c"
    }
]

Removing Tests from Participants

Remove one or more tests from a participant.

HTTP Method:

DELETE

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/tests

Request Parameters:

Parameter	Description
testId	Array of test ids to remove from the participant. If supplied, only these test ids will be removed. If not supplied, all test ids will be removed. (optional)
startDate	Remove test(s), on or after this day (inclusive). Date required to be in YYYY-MM-DD format. (optional)
endDate	Remove test(s), on or before this day (inclusive). Date required to be in YYYY-MM-DD format. (optional)

Example Request:

DELETE {{url}}?testId=test1&testId=test2&startDate=2024-08-20&endDate=2024-12-02

Example Response:

HTTP 200

Note:

If a participant has started completing a particular test, it will not be possible to remove that test from the participant schedule.

Send Email Invite to Participant

Send an email invite to a participant.

HTTP Method:

POST

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/invite

Example Response:

HTTP 200

Note:

If a participant does not have an open valid assessment invitation, then an email invitation will not be sent.

Checking the Status of a Participant

Check the status of a participant.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/status

Response Parameters:

Parameter		Description
participantId		Podium’s id for this participant.
integrationPartnerParticipantId		The partner’s id for this participant.
integrationPartnerParticipantMetadata		JSON metadata from the original participant creation
tests		Array of Test – see following rows.
	Test: testId	The test id for the current test.
	Test: invitationId	The unique invitation id. If a participant has more than one invitation for the same test, this will differentiate.
	Test: creationDate	The date and time of when the invitation as created.
	Test: completionDate	The date and time the participant completed the invitation. If this is null, the participant has not completed the test.
	Test: expiryDate	The expiry date of the invitation, after which it will no longer be accessible to the participant.
	Test: firstLaunched	The date and time the participant first launched the test. If this is null, the participant has not attempted to complete the test.

Example Response:

{
    "participantId": "1-1-49164582-ad37-45aa-abc5c4d622824131",
    "integrationPartnerParticipantId": "partner-id-1234",
    "integrationPartnerParticipantMetadata": null,
    "tests": [
        {
            "invitationId": "a33384de-3ae5-43f3-a3bb-84832556e62b",
            "testId": "test1",
            "creationDate": "2018-11-13T12:18:49.7233333Z",
            "completionDate": null,
            "expiryDate": null,
            "firstLaunched": null
        }
    ]
}

Checking Status by IntegrationPartner ParticipantId

Check the status of a participant by their integration partner participant id.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/external/{{integrationPartnerParticipantId}}/status

Response Parameters:

Parameter		Description
participantId		Podium’s id for this participant.
emailAddress		The participant’s email address.
integrationPartnerParticipantId		The partner’s id for this participant.
integrationPartnerParticipantMetadata		JSON metadata from the original participant creation
tests		Array of Test – see following rows.
	Test: testId	The test id for the current test.
	Test: invitationId	The unique invitation id. If a participant has more than one invitation for the same test, this will differentiate.
	Test: creationDate	The date and time of when the invitation as created.
	Test: completionDate	The date and time the participant completed the invitation. If this is null, the participant has not completed the test.
	Test: expiryDate	The expiry date of the invitation, after which it will no longer be accessible to the participant.
	Test: firstLaunched	The date and time the participant first launched the test. If this is null, the participant has not attempted to complete the test.

Example Response:

[
    {
        "participantId": "1-1-49164582-ad37-45aa-abc5-c4d622824131",
        "emailAddress": "pat.participant@podium365.com",
        "integrationPartnerParticipantId": "partner-id-1234",
        "integrationPartnerParticipantMetadata": null,
        "tests": [
            {
                "invitationId": "a33384de-3ae5-43f3-a3bb-84832556e62b",
                "testId": "test1",
                "creationDate": "2018-11-13T12:18:49.7233333Z",
                "completionDate": null,
                "expiryDate": null,
                "firstLaunched": null
            }
        ]
    }
]

Getting Participant Results

Get the results of a participant.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/results

Request Parameters:

Parameter	Description
testId	The test ids of the test results that should be returned. At least one test id is required.
normId	One or more norms to use when scoring the results.
roleProfileId	One or more role profiles to use when scoring the results. (optional)

Example Request:

GET {{base-url}}/clients/{{clientId}}/participants/{{participantId}}/results?testId=test1&testId=test2&normId=norm1

Response Parameters:

Parameter		Description
participantId		Podium’s id for this participant.
integrationPartnerParticipantId		The partner’s id for this participant
integrationPartnerParticipantMetadata		JSON metadata from the original participant creation
results		Array of Result – see following rows.
	Result: testId	The test id for the current result.
	Result: completionDate	The date and time the participant completed the test. If null, the test has not been completed.
	Result: scores	An array of scores for each scale in the current test. This will vary from test to test.

Example Response:

{
    "participantId": "1-1-49164582-ad37-45aa-abc5-c4d622824131",
    "integrationPartnerParticipantId": "partner-id-1234",
    "integrationPartnerParticipantMetadata": null,
    "results": [
        {
            "testId": "test1", 
            "completionDate": "2018-10-30T15:29:51.0733333Z",
            "scores": [
                {
                    "scaleId": "Scale1",
                    "percentileScore": 99,
                    "rawScore": 18,
                    "standardisedScore": 10
                }
            ]
        }
    ]
}

Getting Participant Results by Date

Get the results of a participant by date.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/results

Request Parameters:

Parameter	Description
testId	The test ids of the test results that should be returned. At least one test id is required.
normId	One or more norms to use when scoring the results.
roleProfileId	One or more role profiles to use when scoring the results. (optional)
startDate	Completion date for results of specified tests, on or after this date (inclusive). Must be in YYYY-MM-DD format. (Optional)
endDate	Completion date for results of specified tests, on or before this date (inclusive). Must be in YYYY-MM-DD format. (Optional)

Example Request:

GET {{base-url}}/{{clientId}}/participants/{{participantId}}/results?testId=test1&testId=test2&normId=norm1&startDate =2024-08-12&endDate=2024-12-02

Response Parameters:

Parameter		Description
participantId		Podium’s id for this participant.
integrationPartnerParticipantId		The partner’s id for this participant
integrationPartnerParticipantMetadata		JSON metadata from the original participant creation
results		Array of Result – see following rows.
	Result: testId	The test id for the current result.
	Result: completionDate	The date and time the participant completed the test. If null, the test has not been completed.
	Result: scores	An array of scores for each scale in the current test. This will vary from test to test.

Example Response:

[
    {
        "participantId":"1-1-49164582-ad37-45aa-abc5-c4d622824131",
        "integrationPartnerParticipantId":"partner-id-1234",
        "integrationPartnerParticipantMetadata": null,
        "results":[
            {
                "testId":"test1",
                "completionDate":"2018-10-30T15:29:51.0733333Z",
                "scores":[
                    {
                        "scaleId": "Scale1",
                        "percentileScore": 99,
                        "rawScore": 18,
                        "standardisedScore": 10
                    }
                ]
            }
        ]
    }
]

Managing Participant Metadata

Manage the metadata of a participant.

HTTP Method:

PATCH

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/metadata 
OR
{{base-url}}/clients/{{clientId}}/participants/external/{{integrationPartnerParticipantId}}/metadata

Request Parameters:

Parameter	Description
integrationPartnerParticipantMetadata	A JSON object of non-sensitive metadata to associate with this participant.

Example Request:

{
    "integrationPartnerParticipantMetadata": {
        "candidateId":"cand-7890",
        "assessmentId":"assess-5678",
        "fieldId":"emotional-intelligence",
        "testStatus":"in-progress",
        "reviewedBy":"admin_user_2"
    }
}

Response Parameters:

Parameter	Description
integrationPartnerParticipantMetadata	JSON metadata from the original participant creation.

Example Response:

{
    "integrationPartnerParticipantMetadata": {
        "candidateId":"cand-7890",
        "assessmentId":"assess-5678",
        "fieldId":"emotional-intelligence",
        "testStatus":"in-progress",
        "reviewedBy":"admin_user_2"
    }
}

Delete Participant Metadata

Delete the metadata of a participant.

HTTP Method:

DELETE

API Endpoint:

{{base-url}}/clients/{{clientId}}/participants/{{participantId}}/metadata 
OR
{{base-url}}/clients/{{clientId}}/participants/external/{{integrationPartnerParticipantId}}/metadata

Example Response:

HTTP 200

Request a Report

Request a report for a participant.

HTTP Method:

POST

API Endpoint:

{{base-url}}/clients/{{clientId}}/reports

Request Parameters:

Parameter	Description
participantIds	Array of ids for each participant to be included in the report request.
reportBundleId	The id of the bundle in which the desire reports are located.
reportIds	Array of ids for each report that should be included.
normIds	Array of ids for each norm that should be included.
roleProfileIds	Array of ids for each role profile that should be included. (Optional)
format	The document format for the report. This can be ‘doc’, ‘docx’ or ‘pdf’. The default is ‘docx’ if no format is specified.

Example Request:

{
    "participantIds": [
        "1-1-49164582-ad37-45aa-abc5-c4d622824131",
        "1-1-50164512-ad37-45aa-abc5-c4d122824131"
    ],
    "reportBundleId":"reportBundle1", 
    "reportIds":[
        "report1",
        "report2"],
    "normIds":[
        "norm1",
        "norm2"
        ]
}

Response Parameters:

Parameter	Description
reportQueueId	The id of the report in the Podium report queue. This can be used to check the status of the report creation and to download it when ready.

Example Response:

{ 
    "reportQueueId": "1-1-58bbcd87-d0f4-4673-9e40-c9e3d3772012"
}

Request a Report by Date

Request a report for a participant by date.

HTTP Method:

POST

API Endpoint:

{{base-url}}/clients/{{clientId}}/reportsbydaterange

Request Parameters:

Parameter	Description
reportBundleId	The id of the bundle in which the desire reports are located.
reportIds	Array of ids for each report that should be included.
normIds	Array of ids for each norm that should be included.
roleProfileIds	Array of ids for each role profile that should be included. (Optional)
format	The document format for the report. This can be ‘doc’, ‘docx’ or ‘pdf’. The default is ‘docx’ if no format is specified.
startDate	All participants with completed results, on or after this date (inclusive). Must be in YYYY-MM-DD format.
endDate	All participants with completed results, on or before this date (inclusive). Must be in YYYY-MM-DD format.

Example Request:

{
    "participantIds": [
        "1-1-49164582-ad37-45aa-abc5-c4d622824131", 
        "1-1-50164512-ad37-45aa-abc5-c4d122824131"
    ],
    "reportBundleId":"reportBundle1", 
    "reportIds":[
        "report1",
        "report2"
        ],
    "normIds":[
        "norm1",
        "norm2"
        ], 
    "startDate": "2024-08-20", 
    "endDate": "2024-12-02"
}

Response Parameters:

Parameter	Description
reportQueueId	The id of the report in the Podium report queue. This can be used to check the status of the report creation and to download it when ready.

Example Response:

{ 
    "reportQueueId": "1-1-58bbcd87-d0f4-4673-9e40-c9e3d3772012"
}

Check the Status of a Report

Check the status of a report.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/reports//status

Response Parameters:

Parameter	Description
completionDate	The date and time the report was completed. If this is null, the report has not been generated.
error	true/false. Whether or not an error occurred while generating the report. If this is true, a notification will have been sent to a Podium technical support representative and a resolution will be sought. If a resolution cannot be achieved, the ‘suspended’ flag will be set (see final parameter).
suspended	true/false. A more serious problem has been discovered. The integration partner will be notified of the issue.

Example Response:

{
    "completionDate": "2018-11-30T15:29:51.0733333Z", 
    "error": false, 
    "suspended": false
}

Download a Report

Download a report.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/reports/

Storage:

The report will be returned as a direct file download with the appropriate mime type. For security reasons, we do not return public endpoint urls so please download the file directly and store on your own system as required.

Reports will be held on our system for a period of 1 year after generation or shorter if a deletion request is made in keeping with our GDPR policy.

Getting a Secure Report Download Link

Getting a secure report download link.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/reports//securelink

Response Parameters:

Parameter	Description
downloadLink	A secure, time-limited link to the report. The link will be valid for one hour from the time it is requested and then it will be unusable. New links to the same report can be requested as many times as required.

Example Response:

{
    "downloadLink": " https://podiumreports.blob.core.windows.net/production/1/1/reportdownload.zip"
}

Getting the Current Client Credit Total

Getting the current client credit total.

HTTP Method:

GET

API Endpoint:

{{base-url}}/clients/{{clientId}}/credits

Example Response:

{
"creditTotal": 100
}

Podium Webhooks

Integration partners are able to register webhooks on the Podium platform for asynchronous events. Webhooks enable partners to receive real-time notifications about events that occur on the Podium platform.

Supported Webhooks

Currently, we support the following webhooks:

Test Completed
Test Completed With Result Scoring * Results incur usage charges (see below for further details).

Webhook Setup & Configuration

During initial setup, integration partners can request which webhooks they would like to have enabled. Only the webhooks you explicitly request will be activated for your integration.

To request webhook activation, please contact your Podium integration representative and provide:

The list of webhook event types you want enabled (e.g. testCompleted, testCompletedWithResultScoring)
The endpoint URL(s) you want us to send webhook notifications to, these can be separate or combined for each webhook event type

* For the testCompletedWithResultScoring webhook: We will also need to confirm the default normId you wish to use for automated result delivery. This ensures that results are scored and mapped consistently across your integration.

You may update your webhook configuration at any time by contacting your representative.

Test Completed

This webhook is triggered when a participant completes a test on the Podium platform. This allows integration partners to track participant test completion and take appropriate actions (such as updating CRM records, triggering follow-up communications, or logging the event).

Example Payload:

[POST]
{
    "event": "testCompleted", 
    "timeStamp": "2019-01-23T11:07:15.1077954Z", 
    "participantId": "1-1-c57ffc13-7f62-4eb7-b7c8-8d38ad11acc2", 
    "integrationPartnerParticipantId": "partner-id-12345", 
    "invitationId": "327677cb-a539-4a2f-af1f-d72e603e9072", 
    "testId": "PERSPECTIVES90" 
}

Test Completed With Result Scoring

This webhook is triggered when a participant completes a test. This allows integration partners to immediately capture both the fact that the test was completed and the resulting data.

* Enabling this webhook will incur usage charges equivalent to making a /results API call. If you have this webhook enabled and later manually call the /results endpoint with the same details, a second charge will not be taken.

Example Payload:

[POST]
{
    "event": "testCompletedAndScored", 
    "timeStamp": "2019-01-23T11:07:15.1077954Z", 
    "participantId": "1-1-c57ffc13-7f62-4eb7-b7c8-8d38ad11acc2", 
    "integrationPartnerParticipantId": "partner-id-12345", 
    "invitationId": "327677cb-a539-4a2f-af1f-d72e603e9072", 
    "testId": "PERSPECTIVES90", 
    "results": { 
        "participantId": "1-1-c57ffc13-7f62-4eb7-b7c8-8d38ad11acc2", 
        "clientId": "d10ffc13-7f62-fef7-b7c8-8d38ad11acc2", 
        "integrationPartnerId": "partner-12345", 
        "integrationPartnerParticipantId": "partner-id-12345", 
        "integrationPartnerParticipantMetadata": null, 
        "results": [ 
            { 
                "testId": "PERSPECTIVES90", 
                "completionDate": "2019-01-23T11:07:15.1077954Z", 
                "scores": [ 
                    { 
                        "scaleId": "SOC", 
                        "percentileScore": 41, 
                        "rawScore": 23.0, 
                        "standardisedScore": 5.0 
                    } 
                ] 
            } 
        ] 
    }
}

Full API Reference (PDF)

The full specification, including request/response schemas and complete endpoint list, is available below.

Developer API

Overview

Getting Started

Base URLs and Environments

Authentication

Endpoints

Adding Participants

Assigning Tests to Participants

Removing Tests from Participants

Send Email Invite to Participant

Checking the Status of a Participant

Checking Status by IntegrationPartner ParticipantId

Getting Participant Results

Getting Participant Results by Date

Managing Participant Metadata

Delete Participant Metadata

Request a Report

Request a Report by Date

Check the Status of a Report

Download a Report

Getting a Secure Report Download Link

Getting the Current Client Credit Total

Podium Webhooks

Test Completed

Test Completed With Result Scoring

Full API Reference (PDF)

Need access or help?