Integration API
Connect your systems to PROMinsight session data via our secure REST API.
Access token-authenticated endpoints to retrieve test sessions and
item-level results programmatically.
API access is available to approved integration partners. Contact us
to request your credentials.
Key Concepts
| Term | What it means |
|---|---|
| Client ID | Public identifier for your integration. |
| Client Secret | Private key for your integration. Must be stored securely and never shared. |
| Access Token | Short-lived token sent with every API call. Obtained by exchanging your Client ID and Secret. |
Authentication
All API calls require a Bearer token in the Authorization header.
Obtain a token by calling the authentication endpoint with your Client ID and Client Secret.
POST /api/v1/auth/token
REQUEST BODY
{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"scope": "session.read"
}RESPONSE — 200 OK
{
"success": true,
"data": {
"accessToken": "eyJ...",
"tokenType": "Bearer",
"expiresIn": 3600
}
}List Sessions
POST /api/v1/tests/sessions
HEADERS
Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json
REQUEST BODY
{
"test_code": "YOUR_TEST_CODE",
"limit": 10
}RESPONSE — 200 OK
Returns an array of session rows, each containing: test_session_id, test_code, client_code, and contract fields.
Get Session Details
GET /api/v1/tests/sessions/{id}
HEADERS
Authorization: Bearer YOUR_ACCESS_TOKEN
URL PARAMETER
{id} → test_session_id from the List Sessions responseRESPONSE — 200 OK
Returns item-level response rows for the specified session.
RESPONSE — 404
No session details found — this session has no item-level responses yet. Use a different test_session_id from the List Sessions response.
Common Errors
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing or expired Bearer token. | Re-authenticate and use the new token. |
| 404 Not Found | Session has no item-level responses yet. | Use a different session ID, or generate test data first. |
| Invalid credentials | Wrong Client ID or Client Secret. | Verify credentials with your PROMinsight contact. |
| Token expired | Access token has passed its expiry time. | Request a new token via the auth endpoint. |
Security Guidelines
- Store your Client Secret and Access Token only in secure server-side systems
- Never include credentials in client-side code, screenshots, or emails
- Use HTTPS at all times in non-local environments
- Rotate your Client Secret on a regular schedule or immediately if compromised
- Tokens are short-lived — do not cache them beyond their expiry