Assessment & Background Checks
Learn how to integrate real-time assessment data, AI insights, and ATS syncing to simplify user workflows and improve candidate evaluation
As assessment providers, building and maintaining separate integrations for every ATS customer can be tricky, especially as implementation specs tend to differ between ATS providers. Each system requires custom code to sync candidate data, receive test requests, and return results.
StackOne’s Unified ATS API cuts this work dramatically thanks to the unified Assessment endpoints and webhooks. Connect once to our platform and instantly integrate with Greenhouse, Workday, Lever and others—no more juggling multiple APIs or wrestling with inconsistent data formats.
Integrating Candidate Assessments Intelligence in Your SaaS: Key Steps and System Interactions
Integrating assessments into your SaaS involves syncing with multiple ATS providers, retrieving job and candidate data, and managing assessments such as coding tests or psychometric evaluations. This enables HR teams to assign, track, and evaluate candidate assessments based on specific job requirements, simplifying the hiring process.
Implementation Approaches for Different ATS Systems
Different ATS systems have varying capabilities for handling assessment packages. StackOne provides flexible implementation approaches to accommodate these differences:
- Standard Implementation - For most ATS systems with dynamic package capabilities such as Greenhouse, Lever, Ashby, Teamtailor, etc.
- Static Packages Implementation - For systems like Workday or SAP SuccessFactors that require manual package creation
- Management of Packages via CRUD Operations - Specific approach for handling background checks through StackOne APIs
Let’s explore each approach with its specific workflow:
Standard Implementation (Dynamic Package List)
This implementation works with most ATS systems that support dynamic package retrieval.
Partnership Required: To implement this standard approach, you’ll need to establish a partnership with the ATS provider (such as Greenhouse, Lever, etc.). StackOne can help facilitate this process, but the partnership agreement is ultimately between you and the ATS provider. This partnership ensures proper API access and configuration for retrieving assessment packages from your endpoint.
For platform-specific configuration details on standard implementations, refer to our hub documentation:
Provide Assessment Packages to StackOne
Implement a packages endpoint: Create an endpoint that matches StackOne’s list packages documentation. When an end customer takes action in their ATS, the ATS will request assessment packages from StackOne, which will then fetch the tests from your endpoint.
- Your Endpoint: Must conform to
GET /ats/assessments/packagesstructure
Return available packages: Your endpoint should return a list of assessment packages that are available for the customer to select from.
End Customer Selects a Package in ATS
Package selection: The end customer selects an assessment package through their ATS interface for a specific candidate and job.
Automated triggering: Alternatively, this can be an automated process if the ATS allows configuration of a specific package for a particular stage in the hiring process.
Receive Assessment Order Notifications
Subscribe to assessment webhooks: Set up a webhook subscription to receive notifications when new assessment orders are created.
- Webhook Event:
ats_assessments.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id} - If needed, access job details:
GET /ats/jobs/{id}using the job_id from the application
Access job and candidate data: These resources contain all the information needed to process the assessment order.
Fetch assessment order details: Once you receive the webhook notification, you can fetch additional details about the assessment order.
Perform Assessment and Return Results
Reach out to candidate: Using the candidate data from the assessment order, communicate with the candidate to perform the assessment.
Process assessment results: Once the candidate completes the assessment, process and analyze the results.
Return results to ATS: Send the assessment results back to the ATS through StackOne’s unified API.
- API Endpoint:
PATCH /ats/assessments/orders/{id}/result
Static Packages Implementation (eg. Workday)
For ATS systems that use static packages (like Workday or SAP SuccessFactors), a different approach is needed.
For platform-specific configuration details on static packages implementations, refer to our hub documentation:
Manual Package Creation in the ATS
Create assessment categories: Navigate to the assessment categories management section in your ATS and create a new assessment category (e.g., “Technical Assessment Test”).
Create assessment tests: Navigate to the assessment tests management section and create a new assessment test linked to the category and the integration system (e.g., “Technical Assessment”).
Note the Assessment Test ID: This ID (e.g., “RECRUITING_ASSESSMENT_TEST-6-111”) will be needed for notification payload configurations.
Sync and Map Jobs (Optional)
Subscribe to job events: Set up webhooks to receive notifications when jobs are created or updated.
- Webhook Event:
ats_jobs.createdandats_jobs.updated
Retrieve all active jobs: Initially fetch all active jobs and store them in your system.
- API Endpoint:
GET /ats/job_postings
Create mapping interface: Build an interface in your SaaS that allows customers to map specific assessment packages to job types or individual job postings.
Store mapping data: Maintain a database of the mappings between assessment packages and job postings.
Receive and Process Assessment Orders
Receive assessment order webhook: Get notified when a new assessment order is created.
- Webhook Event:
ats_assessments.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id} - If needed, access job details:
GET /ats/jobs/{id}using the job_id from the application
Access job and candidate data: These resources contain all the information needed to process the assessment order.
Fetch full order details: Access complete information about the assessment order.
Return Assessment Results
Collect assessment results: Gather the results of the completed assessment.
Update the ATS with results: Send the assessment results back to the ATS through StackOne.
- API Endpoint:
PATCH /ats/assessments/orders/{id}/result
Management of Packages via CRUD Operations (Background Checks Only)
This approach is specifically designed for background check integrations with ATS systems like Workday Background Check, where a different approach from standard assessments is required.
StackOne Package Storage: For ATS systems that support dynamic fetching but lack proper CRUD operations support, StackOne will store and manage the background check packages. This provides a unified approach whether the underlying ATS supports package storage or not.
Create Background Check Packages
Create background check packages programmatically: Instead of implementing a list endpoint, create packages programmatically using StackOne’s unified API CRUD operations.
- API Endpoint:
POST /ats/background_checks/packages
Configure Background Check Business Process: Update the Integration System and Document Delivery settings in your ATS’s Background Check Business Process.
Manage Background Check Packages
Update existing packages: Modify background check packages as needed using StackOne APIs.
- API Endpoint:
PATCH /ats/background_checks/packages/{id}
Remove unwanted packages: Delete packages that are no longer needed.
- API Endpoint:
DELETE /ats/background_checks/packages/{id}
Receive Background Check Orders
Subscribe to background check webhooks: Configure webhooks to receive notifications when new background check orders are created.
- Webhook Event:
background_check_order.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id}
Fetch order details: Access complete information about the background check order if needed.
Return Background Check Results
Return background check results: Send the results back through StackOne’s unified API.
- API Endpoint:
PATCH /ats/background_checks/orders/{id}/result
Frequently Asked Questions
General Implementation Questions
How do I choose between the different implementation approaches?
How do I choose between the different implementation approaches?
Your choice depends on the ATS systems your customers use:
- Use the Standard Implementation for ATS systems with dynamic package capabilities (Greenhouse, Lever, etc.)
- Use the Static Packages Implementation for systems like Workday or SAP SuccessFactors
- Use the Management of Packages via CRUD Operations specifically for background checks
If you support multiple ATS systems, you may need to implement multiple approaches.
What partnership requirements exist for implementing assessments with StackOne?
What partnership requirements exist for implementing assessments with StackOne?
To implement assessments via the StackOne unified API, you’ll need to:
- Establish a formal partnership with the ATS (in instances where a partnership is required by the ATS)
- Set up a packages endpoint that conforms to our API specifications
- Deploy webhooks to receive assessment orders
- Configure your assessment delivery mechanism
- Implement result reporting back to the ATS
Contact StackOne to learn more about which ATS providers require partnerships in order to integrate with their Assessments flow, plus howStackOne can help facilitate ATS provider partnerships and support you in the application process.
What's the typical timeline for implementing an assessment integration?
What's the typical timeline for implementing an assessment integration?
Implementation timelines vary based on complexity:
- Standard implementation: 2-4 weeks
- Static packages implementation: 3-6 weeks
- Background check implementation: 3-6 weeks
Factors affecting timeline include your existing infrastructure, familiarity with our API, and specific ATS requirements.
Technical Questions
How do webhooks work with the assessment flow?
How do webhooks work with the assessment flow?
Webhooks provide real-time notifications when assessment-related events occur:
- Subscribe to relevant events like
ats_assessments.created - StackOne sends a notification to your endpoint when these events occur
- Your application processes the webhook payload and takes appropriate action
- You can fetch additional details using the IDs provided in the webhook payload
See our Webhooks documentation for detailed setup instructions.
Can I map specific assessment types to different job roles?
Can I map specific assessment types to different job roles?
Yes, you can implement job-to-assessment mapping in two ways:
For Standard Implementation:
- Return different assessment packages based on job attributes when your packages endpoint is called
For Static Packages Implementation:
- Create a custom UI in your application allowing customers to map job types to specific assessment packages
- Store these mappings and use them when you receive assessment order webhooks
This mapping functionality allows customers to automatically assign appropriate assessments based on job requirements.
How do I handle security and compliance in assessment integrations?
How do I handle security and compliance in assessment integrations?
Security best practices for assessment integrations include:
- Secure Authentication: Use HTTPS for all endpoints and implement secure authentication
- Webhook Verification: Validate webhook signatures using StackOne’s signing secret
Can I implement multiple assessment vendors for the same ATS?
Can I implement multiple assessment vendors for the same ATS?
Yes, you can integrate multiple assessment vendors with the same ATS through StackOne. This provides customers with flexibility to choose different assessment types from various vendors.
When implementing multiple vendors:
- Each vendor should have their own packages endpoint
- Each vendor receives their own assessment order webhooks
- Results are pushed back to the ATS through the same unified API
This approach allows customers to leverage specialized assessments from different providers while maintaining a consistent integration.
Troubleshooting
What should I do if assessment order webhooks aren't being received?
What should I do if assessment order webhooks aren't being received?
If you’re not receiving assessment order webhooks:
- Verify webhook subscription is correctly configured in the StackOne dashboard
- Check that you’re subscribed to the correct event types (
ats_assessments.created) - Ensure your webhook endpoint is publicly accessible and responding with 200 status codes
- Review the webhook health in the StackOne dashboard
- Test your endpoint with StackOne’s webhook testing tools
Contact StackOne support if issues persist.
How do I debug assessment result submission issues?
How do I debug assessment result submission issues?
If you encounter problems when submitting assessment results:
- Verify you’re using the correct endpoint format:
PATCH /ats/assessments/orders/{id}/result - Ensure your payload conforms to the expected schema
- Check that you’re using the correct assessment order ID
- Confirm your authentication is valid
- Review the API response for specific error details
You can test submissions with sample data before implementing in production.
Frequently Asked Questions
Assessment & Background Checks
Learn how to integrate real-time assessment data, AI insights, and ATS syncing to simplify user workflows and improve candidate evaluation
As assessment providers, building and maintaining separate integrations for every ATS customer can be tricky, especially as implementation specs tend to differ between ATS providers. Each system requires custom code to sync candidate data, receive test requests, and return results.
StackOne’s Unified ATS API cuts this work dramatically thanks to the unified Assessment endpoints and webhooks. Connect once to our platform and instantly integrate with Greenhouse, Workday, Lever and others—no more juggling multiple APIs or wrestling with inconsistent data formats.
Integrating Candidate Assessments Intelligence in Your SaaS: Key Steps and System Interactions
Integrating assessments into your SaaS involves syncing with multiple ATS providers, retrieving job and candidate data, and managing assessments such as coding tests or psychometric evaluations. This enables HR teams to assign, track, and evaluate candidate assessments based on specific job requirements, simplifying the hiring process.
Implementation Approaches for Different ATS Systems
Different ATS systems have varying capabilities for handling assessment packages. StackOne provides flexible implementation approaches to accommodate these differences:
- Standard Implementation - For most ATS systems with dynamic package capabilities such as Greenhouse, Lever, Ashby, Teamtailor, etc.
- Static Packages Implementation - For systems like Workday or SAP SuccessFactors that require manual package creation
- Management of Packages via CRUD Operations - Specific approach for handling background checks through StackOne APIs
Let’s explore each approach with its specific workflow:
Standard Implementation (Dynamic Package List)
This implementation works with most ATS systems that support dynamic package retrieval.
Partnership Required: To implement this standard approach, you’ll need to establish a partnership with the ATS provider (such as Greenhouse, Lever, etc.). StackOne can help facilitate this process, but the partnership agreement is ultimately between you and the ATS provider. This partnership ensures proper API access and configuration for retrieving assessment packages from your endpoint.
For platform-specific configuration details on standard implementations, refer to our hub documentation:
Provide Assessment Packages to StackOne
Implement a packages endpoint: Create an endpoint that matches StackOne’s list packages documentation. When an end customer takes action in their ATS, the ATS will request assessment packages from StackOne, which will then fetch the tests from your endpoint.
- Your Endpoint: Must conform to
GET /ats/assessments/packagesstructure
Return available packages: Your endpoint should return a list of assessment packages that are available for the customer to select from.
End Customer Selects a Package in ATS
Package selection: The end customer selects an assessment package through their ATS interface for a specific candidate and job.
Automated triggering: Alternatively, this can be an automated process if the ATS allows configuration of a specific package for a particular stage in the hiring process.
Receive Assessment Order Notifications
Subscribe to assessment webhooks: Set up a webhook subscription to receive notifications when new assessment orders are created.
- Webhook Event:
ats_assessments.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id} - If needed, access job details:
GET /ats/jobs/{id}using the job_id from the application
Access job and candidate data: These resources contain all the information needed to process the assessment order.
Fetch assessment order details: Once you receive the webhook notification, you can fetch additional details about the assessment order.
Perform Assessment and Return Results
Reach out to candidate: Using the candidate data from the assessment order, communicate with the candidate to perform the assessment.
Process assessment results: Once the candidate completes the assessment, process and analyze the results.
Return results to ATS: Send the assessment results back to the ATS through StackOne’s unified API.
- API Endpoint:
PATCH /ats/assessments/orders/{id}/result
Static Packages Implementation (eg. Workday)
For ATS systems that use static packages (like Workday or SAP SuccessFactors), a different approach is needed.
For platform-specific configuration details on static packages implementations, refer to our hub documentation:
Manual Package Creation in the ATS
Create assessment categories: Navigate to the assessment categories management section in your ATS and create a new assessment category (e.g., “Technical Assessment Test”).
Create assessment tests: Navigate to the assessment tests management section and create a new assessment test linked to the category and the integration system (e.g., “Technical Assessment”).
Note the Assessment Test ID: This ID (e.g., “RECRUITING_ASSESSMENT_TEST-6-111”) will be needed for notification payload configurations.
Sync and Map Jobs (Optional)
Subscribe to job events: Set up webhooks to receive notifications when jobs are created or updated.
- Webhook Event:
ats_jobs.createdandats_jobs.updated
Retrieve all active jobs: Initially fetch all active jobs and store them in your system.
- API Endpoint:
GET /ats/job_postings
Create mapping interface: Build an interface in your SaaS that allows customers to map specific assessment packages to job types or individual job postings.
Store mapping data: Maintain a database of the mappings between assessment packages and job postings.
Receive and Process Assessment Orders
Receive assessment order webhook: Get notified when a new assessment order is created.
- Webhook Event:
ats_assessments.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id} - If needed, access job details:
GET /ats/jobs/{id}using the job_id from the application
Access job and candidate data: These resources contain all the information needed to process the assessment order.
Fetch full order details: Access complete information about the assessment order.
Return Assessment Results
Collect assessment results: Gather the results of the completed assessment.
Update the ATS with results: Send the assessment results back to the ATS through StackOne.
- API Endpoint:
PATCH /ats/assessments/orders/{id}/result
Management of Packages via CRUD Operations (Background Checks Only)
This approach is specifically designed for background check integrations with ATS systems like Workday Background Check, where a different approach from standard assessments is required.
StackOne Package Storage: For ATS systems that support dynamic fetching but lack proper CRUD operations support, StackOne will store and manage the background check packages. This provides a unified approach whether the underlying ATS supports package storage or not.
Create Background Check Packages
Create background check packages programmatically: Instead of implementing a list endpoint, create packages programmatically using StackOne’s unified API CRUD operations.
- API Endpoint:
POST /ats/background_checks/packages
Configure Background Check Business Process: Update the Integration System and Document Delivery settings in your ATS’s Background Check Business Process.
Manage Background Check Packages
Update existing packages: Modify background check packages as needed using StackOne APIs.
- API Endpoint:
PATCH /ats/background_checks/packages/{id}
Remove unwanted packages: Delete packages that are no longer needed.
- API Endpoint:
DELETE /ats/background_checks/packages/{id}
Receive Background Check Orders
Subscribe to background check webhooks: Configure webhooks to receive notifications when new background check orders are created.
- Webhook Event:
background_check_order.created - Webhook Configuration: Configure at StackOne Webhooks
Use application and candidate information: The webhook payload contains application_id and candidate_id references that you can use to retrieve detailed information.
- Access candidate details:
GET /ats/candidates/{id} - Access application details:
GET /ats/applications/{id}
Fetch order details: Access complete information about the background check order if needed.
Return Background Check Results
Return background check results: Send the results back through StackOne’s unified API.
- API Endpoint:
PATCH /ats/background_checks/orders/{id}/result
Frequently Asked Questions
General Implementation Questions
How do I choose between the different implementation approaches?
How do I choose between the different implementation approaches?
Your choice depends on the ATS systems your customers use:
- Use the Standard Implementation for ATS systems with dynamic package capabilities (Greenhouse, Lever, etc.)
- Use the Static Packages Implementation for systems like Workday or SAP SuccessFactors
- Use the Management of Packages via CRUD Operations specifically for background checks
If you support multiple ATS systems, you may need to implement multiple approaches.
What partnership requirements exist for implementing assessments with StackOne?
What partnership requirements exist for implementing assessments with StackOne?
To implement assessments via the StackOne unified API, you’ll need to:
- Establish a formal partnership with the ATS (in instances where a partnership is required by the ATS)
- Set up a packages endpoint that conforms to our API specifications
- Deploy webhooks to receive assessment orders
- Configure your assessment delivery mechanism
- Implement result reporting back to the ATS
Contact StackOne to learn more about which ATS providers require partnerships in order to integrate with their Assessments flow, plus howStackOne can help facilitate ATS provider partnerships and support you in the application process.
What's the typical timeline for implementing an assessment integration?
What's the typical timeline for implementing an assessment integration?
Implementation timelines vary based on complexity:
- Standard implementation: 2-4 weeks
- Static packages implementation: 3-6 weeks
- Background check implementation: 3-6 weeks
Factors affecting timeline include your existing infrastructure, familiarity with our API, and specific ATS requirements.
Technical Questions
How do webhooks work with the assessment flow?
How do webhooks work with the assessment flow?
Webhooks provide real-time notifications when assessment-related events occur:
- Subscribe to relevant events like
ats_assessments.created - StackOne sends a notification to your endpoint when these events occur
- Your application processes the webhook payload and takes appropriate action
- You can fetch additional details using the IDs provided in the webhook payload
See our Webhooks documentation for detailed setup instructions.
Can I map specific assessment types to different job roles?
Can I map specific assessment types to different job roles?
Yes, you can implement job-to-assessment mapping in two ways:
For Standard Implementation:
- Return different assessment packages based on job attributes when your packages endpoint is called
For Static Packages Implementation:
- Create a custom UI in your application allowing customers to map job types to specific assessment packages
- Store these mappings and use them when you receive assessment order webhooks
This mapping functionality allows customers to automatically assign appropriate assessments based on job requirements.
How do I handle security and compliance in assessment integrations?
How do I handle security and compliance in assessment integrations?
Security best practices for assessment integrations include:
- Secure Authentication: Use HTTPS for all endpoints and implement secure authentication
- Webhook Verification: Validate webhook signatures using StackOne’s signing secret
Can I implement multiple assessment vendors for the same ATS?
Can I implement multiple assessment vendors for the same ATS?
Yes, you can integrate multiple assessment vendors with the same ATS through StackOne. This provides customers with flexibility to choose different assessment types from various vendors.
When implementing multiple vendors:
- Each vendor should have their own packages endpoint
- Each vendor receives their own assessment order webhooks
- Results are pushed back to the ATS through the same unified API
This approach allows customers to leverage specialized assessments from different providers while maintaining a consistent integration.
Troubleshooting
What should I do if assessment order webhooks aren't being received?
What should I do if assessment order webhooks aren't being received?
If you’re not receiving assessment order webhooks:
- Verify webhook subscription is correctly configured in the StackOne dashboard
- Check that you’re subscribed to the correct event types (
ats_assessments.created) - Ensure your webhook endpoint is publicly accessible and responding with 200 status codes
- Review the webhook health in the StackOne dashboard
- Test your endpoint with StackOne’s webhook testing tools
Contact StackOne support if issues persist.
How do I debug assessment result submission issues?
How do I debug assessment result submission issues?
If you encounter problems when submitting assessment results:
- Verify you’re using the correct endpoint format:
PATCH /ats/assessments/orders/{id}/result - Ensure your payload conforms to the expected schema
- Check that you’re using the correct assessment order ID
- Confirm your authentication is valid
- Review the API response for specific error details
You can test submissions with sample data before implementing in production.