Skip to content

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

sequenceDiagram
    actor U as Agency User
    participant A as Agency System
    participant T as Trio VMS API
    participant W as Trio
    actor F as Facility

    Note over A,T: Initial Setup
    A->>+T: Register Submission Update Webhook
    T->>-A: Webhook Confirmation

    Note over A,T: Candidate Submission Process
    U->>+A: Submit Candidate for Job
    A->>+T: GET /api/v3/candidates?email={email}
    T->>-A: Candidate List (may be empty)
    alt Candidate Exists
        A->>A: Use existing candidate number
    else Candidate Does Not Exist
        A->>+T: POST /api/v3/candidates
        T->>-A: New Candidate Details
        A->>A: Store new candidate number
    end
    A->>+T: POST /api/v3/Submission (multipart/form-data)
    T->>-A: Submission Response
    A->>-U: Submission Confirmation

    Note over A,W: Real-time Updates
    F->>+W: Update Submission Status
    W->>+A: POST Webhook: Submission Update
    A->>-W: 200 OK
    A->>A: Update Local Submission Status

Step-by-Step Implementation

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.

POST https://api.triovms.com/ahsa/api/v3/Webhooks
X-API-KEY: apiKeyValue
Content-Type: application/json

{
  "Name": "Submission Status Updates",
  "Url": "https://your-agency-domain.com/trio-webhooks/submission-updates",
  "Events": [
    "Submission Update"
  ],
  "IsActive": true
}

Implement Webhook Endpoint

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

  1. Set up a secure HTTPS endpoint (e.g., https://your-agency-domain.com/trio-webhooks/submission-updates)
  2. Process the incoming webhook payload and update your local submission data

Webhook Payload Structure:

interface SubmissionNotification {
    Number: number;
    Status: string;
    StatusCode: number;
    StatusReason: string | null;
    JobNumber: number;
    CandidateNumber: number;
    BestContactDescription: string | null;
    BillRateAmount: number | null;
    StartDate: string | null;
    AvailabilityDescription: string | null;
    DaysOffDescription: string | null;
    ExperienceDescription: string | null;
    ModifiedDateUTC: string;
}

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:

GET https://api.triovms.com/ahsa/api/v3/candidates?email=candidate@example.com
X-API-KEY: apiKeyValue

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:

POST https://api.triovms.com/ahsa/api/v3/candidates
X-API-KEY: apiKeyValue
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe", 
  "email1": "candidate@example.com",
  "phone1": "555-123-4567",
  "isNicotineFree": true,
  "isAlcoholFree": true,
  "stateLicenses": [
    {
      "state": "CA",
      "isCompact": false,
      "expirationDate": "2025-12-31"
    }
  ]
}

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:

POST https://api.triovms.com/ahsa/api/v3/Submission
X-API-KEY: apiKeyValue
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="JobNumber"

12345
--boundary
Content-Disposition: form-data; name="CandidateNumber"

67890
--boundary
Content-Disposition: form-data; name="BestContactDescription"

Call anytime between 9 AM and 5 PM
--boundary
Content-Disposition: form-data; name="BillRateAmount"

75
--boundary
Content-Disposition: form-data; name="StartDate"

2024-10-01T08:00:00Z
--boundary
Content-Disposition: form-data; name="AvailabilityDescription"

Available immediately, prefer day shifts
--boundary
Content-Disposition: form-data; name="DaysOffDescription"

Prefers weekends off
--boundary
Content-Disposition: form-data; name="ExperienceDescription"

5 years ICU experience, ACLS certified
--boundary
Content-Disposition: form-data; name="Description"

Excellent nurse with strong patient care skills
--boundary
Content-Disposition: form-data; name="ModifyNote"

Initial submission
--boundary
Content-Disposition: form-data; name="CandidateProfileFile"; filename="resume.pdf"
Content-Type: application/pdf

[PDF file content]
--boundary
Content-Disposition: form-data; name="AgencyContacts"

[{"name": "John Smith", "email": "john@agency.com", "phoneNumber": "555-987-6543"}]
--boundary--

Managing Submissions

View Submission Status

Retrieve all submissions for your agency:

GET https://api.triovms.com/ahsa/api/v3/Submission
X-API-KEY: apiKeyValue

Get a specific submission:

GET https://api.triovms.com/ahsa/api/v3/Submission/{submissionId}
X-API-KEY: apiKeyValue

Accept an Offered Submission

When a submission is offered, accept it:

POST https://api.triovms.com/ahsa/api/v3/Submission/Accept
X-API-KEY: apiKeyValue
Content-Type: application/json

{
  "submissionNumber": 12345,
  "reason": "Freeform text (optional)",
}

Decline an Offered Submission

Get available withdrawal reasons:

GET https://api.triovms.com/ahsa/api/v3/Submission/WithdrawReasons
X-API-KEY: apiKeyValue

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

POST https://api.triovms.com/ahsa/api/v3/Submission/Decline
X-API-KEY: apiKeyValue
Content-Type: application/json

{
  "submissionNumber": 12345,
  "reason": "Accepted Another Position",
  "description": "Candidate accepted a different job offer."
}

Withdraw a Submission

Get available withdrawal reasons:

GET https://api.triovms.com/ahsa/api/v3/Submission/WithdrawReasons
X-API-KEY: apiKeyValue

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

POST https://api.triovms.com/ahsa/api/v3/Submission/Withdraw
X-API-KEY: apiKeyValue
Content-Type: application/json

{
  "submissionNumber": 12345,
  "reason": "No Longer Available",
  "description": "Candidate is no longer available for the position."
}

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

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

  2. Document Requirements: Ensure candidate profile documents are:

    1. Under 2.5MB in size
    2. In supported formats (PDF, DOC, DOCX, RTF, TXT)
    3. Include relevant candidate information

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

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

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

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

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

  8. 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

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

Integration Checklist

  • [ ] Set up API key authentication
  • [ ] Register for Submission Update webhooks
  • [ ] 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.