Trio Candidate Submission Integration Guide

Introduction

This guide outlines the process for agencies to integrate with Trio VMS to submit candidates for available jobs. The integration uses the Trio API to check for existing candidates, create new candidates when necessary, and submit candidates to specific jobs with required documentation.

Authentication

Before accessing the Trio API, you need to set up authentication and obtain an API Key to use in the X-API-KEY header in each request.

Integration Flow

Step-by-Step Implementation

1. Register Submission Update Webhook (Recommended)

To receive real-time updates about submission status changes, register a webhook for submission updates. This allows your system to be immediately notified when a submission status changes instead of polling the API.

Implement Webhook Endpoint

Create an endpoint on your server to receive submission update webhooks:

Set up a secure HTTPS endpoint (e.g., https://your-agency-domain.com/trio-webhooks/submission-updates)

Process the incoming webhook payload and update your local submission data

Webhook Payload Structure:

Example webhook payload:

{
  "Number": 12345,
  "Status": "Offered",
  "StatusCode": 3,
  "StatusReason": null,
  "JobNumber": 67890,
  "CandidateNumber": 11111,
  "BestContactDescription": "Call anytime between 9 AM and 5 PM",
  "BillRateAmount": 75.00,
  "StartDate": "2024-10-01T08:00:00Z",
  "AvailabilityDescription": "Available immediately, prefer day shifts",
  "DaysOffDescription": "Prefers weekends off",
  "ExperienceDescription": "5 years ICU experience, ACLS certified",
  "ModifiedDateUTC": "2024-09-16T14:30:00Z"
}

2. Check for Existing Candidate

Before creating a new candidate, check if one already exists using their email address:

Response:

If candidate exists: Returns array with candidate details including the number field

If candidate doesn't exist: Returns empty array

3. Create Candidate (if needed)

If the candidate doesn't exist, create a new one using the candidate creation endpoint:

The response will include the candidate's details with a number field that you'll need for submission.

4. Submit Candidate to Job

Submit the candidate to a specific job using the submission endpoint. This endpoint requires multipart/form-data because it must include a candidate profile document:

Managing Submissions

View Submission Status

Retrieve all submissions for your agency:

Get a specific submission:

Accept an Offered Submission

When a submission is offered, accept it:

Decline an Offered Submission

Get available withdrawal reasons:

Decline a submission offer, reason must be provided from the withdraw reasons list:

Withdraw a Submission

Get available withdrawal reasons:

Withdraw a submitted candidate, reason must be provided from the withdraw reasons list:

Error Handling

Common error scenarios and responses:

400 Bad Request: Invalid data format or missing required fields

403 Forbidden: Insufficient permissions or API key issues

404 Not Found: Job or candidate not found

500 Internal Server Error: System error

Always implement proper error handling and logging for troubleshooting.

Best Practices

Candidate Management: Always check for existing candidates by email before creating new ones to avoid duplicates.

Document Requirements: Ensure candidate profile documents are:

Under 2.5MB in size

In supported formats (PDF, DOC, DOCX, RTF, TXT)

Include relevant candidate information

Rate Limiting: Implement appropriate delays between API calls to avoid rate limiting.

Data Validation: Validate all required fields before making API calls.

Secure Storage: Store candidate numbers and submission IDs for future reference and status tracking.

Error Recovery: Implement retry logic for transient failures and meaningful error messages for users.

Real-time Updates: Use webhooks for immediate notification of submission status changes rather than constant polling.

Webhook Reliability:

Implement webhook endpoint with proper error handling

Use periodic API sync as backup for missed webhooks

Respond to webhook requests promptly (within 10 seconds)

Process webhooks idempotently to handle potential duplicates

Status Monitoring: Regularly verify webhook registrations are active and properly configured.

Integration Checklist

Set up API key authentication

Implement webhook endpoint for submission status updates

Implement candidate search by email

Implement candidate creation with required fields

Implement multipart/form-data submission creation

Add document upload functionality

Implement submission status tracking

Add submission acceptance/decline/withdrawal

Implement proper error handling and webhook validation

Add logging for troubleshooting

Test webhook endpoint with sample payloads

Implement backup API polling for webhook failures

Test with sample data

By following this guide, you should be able to implement a robust candidate submission integration with Trio VMS, allowing your agency to efficiently submit qualified candidates to available positions.

Trio Candidate Submission Integration Guide

Introduction#

Authentication#

Integration Flow#

Step-by-Step Implementation#

1. Register Submission Update Webhook (Recommended)#

Implement Webhook Endpoint#

2. Check for Existing Candidate#

3. Create Candidate (if needed)#

4. Submit Candidate to Job#

Managing Submissions#

View Submission Status#

Accept an Offered Submission#

Decline an Offered Submission#

Withdraw a Submission#

Error Handling#

Best Practices#

Integration Checklist#