--- title: "How to Offer Assessment Packages and Receive Orders with Unified's Assessment API" img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_offer_assessment_packages_and_receive_orders_with_unified_assessment_api-icon.png date: 2026-02-19T23:32:00.000Z tag: Product description: "Assessment providers increasingly need to integrate directly into Applicant Tracking Systems (ATS) so recruiters can request assessments without leaving their..." url: "https://unified.to/blog/how_to_offer_assessment_packages_and_receive_orders_with_unified_assessment_api" --- # How to Offer Assessment Packages and Receive Orders with Unified's Assessment API ------ _February 19, 2026_ Assessment providers increasingly need to integrate directly into Applicant Tracking Systems (ATS) so recruiters can request assessments without leaving their hiring workflow. The Unified [Assessment API](/assessment) allows you to: - Publish assessment packages into supported ATS platforms - Receive recruiter-initiated assessment orders via [webhooks](/blog/replacing_polling_with_unified_webhooks_and_virtual_streams) - Submit structured results back to the ATS - Support multiple ATS platforms through a single integration This is not a status-trigger workflow. This is a recruiter-initiated, embedded integration model. ## What This Use Case Covers This guide explains how to: 1. Create an assessment integration connection 2. Publish assessment packages 3. Receive recruiter-initiated assessment orders 4. Process and update assessment results 5. Handle order lifecycle events Supported ATS platforms (assessment integrations): - Ashby Assessment - Cornerstone Assessment - Greenhouse Assessment - Recruitee Assessment - TalentLyft Assessment - Workable Assessment Each of these uses an assessment-specific integration type that is separate from the standard [ATS API](/ats). ## Mental Model: Embedded Assessment Integration With the Assessment API: 1. You create assessment packages via Unified. 2. The ATS lists your packages inside its interface. 3. A recruiter selects a package and orders an assessment for a candidate. 4. Unified sends you an `assessment_order` webhook. 5. You process the assessment. 6. You submit results via the order update endpoint. 7. The results appear inside the ATS. The recruiter never leaves the ATS. ## Step 1: Create an Assessment Connection Unlike ATS OAuth connections, Assessment connections are manually created and authenticated using a **Partner API Key**. You create a connection with: - `integration_type` (e.g., `greenhouseassessment`) - `auth.token` (your Partner API Key) Your customer configures their ATS using: ```plain text Base URL: https://api.unified.to/assessment/{connection_id} Partner API Key: ``` Each assessment integration may have additional authentication requirements (for example, Ashby may require additional identifiers). Always verify integration-specific auth requirements before onboarding customers. ## Step 2: Publish Assessment Packages Recruiters cannot order an assessment unless you first publish packages. ### Create a Package ```plain text POST /assessment/{connection_id}/package ``` ### Required fields - `id` - `name` - `type` Valid `type` values: - `SKILLS_TEST` - `BEHAVIORAL_ASSESSMENT` - `VIDEO_INTERVIEW` - `BACKGROUND_CHECK` - `REFERENCE_CHECK` - `OTHER` ### Example (Node SDK) ```typescript const results = await sdk.assessment.createAssessmentPackage({ connectionId, assessmentPackage: { id: 'engineering_skills_v1', name: 'Engineering Skills Test', type: 'SKILLS_TEST', description: 'Backend engineering evaluation', max_score: 100, }, }); ``` ### Package Configuration Fields Key configuration fields include: - `parameters[]` — assessment input fields (TEXT, NUMBER, FILE, etc.) - `has_redirect_url` — whether candidate is redirected externally - `needs_ip_address` — whether IP address is required - `regions[]` — availability restrictions - `cost_amount` and `currency` - `processing_time` These determine how the ATS displays your package and what information it collects. ### List Packages ```plain text GET /assessment/{connection_id}/package ``` Default pagination: - `limit` (default 100) - `offset` (default 0) ## Step 3: Configure Webhook to Receive Orders Assessment orders are delivered through the standard Unified webhook system. Create a webhook: ```plain text POST /unified/webhook ``` Example configuration: ```json { "hook_url": "https://your-platform.com/webhooks", "connection_id": "", "object_type": "assessment_order", "event": "created" } ``` This webhook fires when a recruiter orders an assessment in the ATS. ### Webhook Payload You receive an `AssessmentOrder` payload: ```json { "id": "123", "package_id": "engineering_skills_v1", "candidate_id": "candidate_456", "application_id": "application_789", "job_id": "job_012", "status": "OPEN" } ``` Additional profile fields may be included: - `profile_name` - `profile_emails` - `profile_resume_url` - `profile_ip_address` - `profile_date_of_birth` - etc. Webhook delivery includes: - HMAC signature - `nonce` - Retry mechanism (3 immediate retries + Fibonacci backoff) - Event type indicators (`INITIAL-PARTIAL`, `INITIAL-COMPLETE`, etc.) ## Step 4: Process the Assessment After receiving the order: 1. Validate webhook signature 2. Store the order in your system 3. Issue the assessment to the candidate 4. Track completion Order status lifecycle: - `OPEN` - `IN_PROGRESS` - `COMPLETED` - `FAILED` - `REJECTED` ## Step 5: Submit Results Back to ATS When assessment is complete: ```plain text PUT /assessment/{connection_id}/order/{order_id} ``` ### Example ```typescript const results = await sdk.assessment.updateAssessmentOrder({ connectionId, id: 'order_123', assessmentOrder: { status: 'COMPLETED', response_score: 85, response_max_score: 100, response_url: 'https://your-platform.com/results/order_123', response_completed_at: '2026-02-19T10:30:00Z', response_attributes: [ { type: 'TEXT', label: 'Overall Assessment', value: 'Strong technical proficiency' } ] } }); ``` The ATS displays: - Score - Completion status - Result link - Structured attributes - Download URLs (if provided) ## Order Update Considerations The `AssessmentOrder` model supports: - Structured score fields - Redirect URLs - Detailed result breakdown (`response_details`) - Additional attributes (`response_attributes`) - Downloadable reports (`response_download_urls`) Writable fields vary slightly by integration (per your writable field matrix). Required fields are marked per integration and must be respected. ## Handling Order Lifecycle Events If supported, some ATS integrations may issue cancellation events. If your system receives a cancellation: - Mark order as `REJECTED` - Stop processing - Avoid duplicate fulfillment Always design your webhook handler to be idempotent. ## Real-Time Architecture The Assessment API is real-time and stateless: - Unified does not store your assessment results. - Orders are delivered via webhook immediately. - Result updates are written directly back to the ATS. This allows: - Immediate recruiter visibility - Automated downstream workflows - Reduced recruiter friction ## Provider Variability While the API is normalized: - Writable fields vary by integration. - Some integrations require specific fields when updating results. - Always consult the integration's writable field matrix before deploying. Your CSV matrices provide authoritative per-provider field support. ## Security Best Practices - Treat Partner API Keys as sensitive. - Validate webhook signatures. - Implement idempotent webhook processing. - Store `connection_id` securely. - Handle retries gracefully. ## When to Use the Assessment API vs ATS API Use the **Assessment API** when: - The ATS supports embedded assessment listings. - You want recruiters to initiate assessments inside the ATS. - You have a partnership-style integration. Use the **ATS API fallback** when: - The ATS does not support embedded assessment integrations. - You trigger assessments based on status changes. Most providers will use both: - Assessment API for supported ATS platforms. - ATS API for broader coverage. ## Closing Thoughts The Unified Assessment API allows assessment providers to integrate once and support multiple ATS platforms without: - Maintaining separate authentication systems - Supporting multiple webhook formats - Managing platform-specific order models - Tracking API deprecations per ATS You publish packages once. Recruiters order from within their ATS. You receive orders in real time. You push results back through a single endpoint. One integration. Multiple ATS platforms. Embedded recruiter workflow. [→ Start your 30-day free trial](https://app.unified.to/login) [→ Book a demo](https://calendly.com/d/cph9-g8n-jzg/connect-with-unified)