Getting Started with App Integrations

Getting Started with SolidATS App Integrations

App integrations in SolidATS allow developers to create custom assessment steps that can be added to recruitment pipelines. These integrations can range from simple skill tests to complex AI-powered evaluations.

What is a SolidATS App Integration?

An app integration is a specialized step in the SolidATS recruitment pipeline that performs an assessment action on candidates. It receives candidate data, performs an evaluation, and returns structured results that help recruiters make informed decisions.

Integration Types

App integrations can be:

AI-powered assessments: Using AI to evaluate candidate skills, fit, or potential
Skill tests: Technical or domain-specific evaluations
Coding challenges: Code execution and analysis tools
Psychometric assessments: Personality or cognitive evaluations
Manual review tools: Interfaces for human reviewers to assess candidates
Third-party integrations: Connecting to external testing or verification services

How App Integrations Work

Registration: Register your app in the SolidATS marketplace
Configuration: Define the configuration schema for your app
Webhook Setup: Configure endpoints to receive candidate data
Assessment Processing: Process the assessment based on candidate data
Response: Return a structured response with ratings and context

Webhook Communication

SolidATS uses webhooks to communicate with your app integration. When a candidate reaches your app’s step in the pipeline, SolidATS sends a payload with candidate information to your endpoint.

Request Payload

{
    v?: string                      // API version field to handle schema evolution
    job: {
        description: string
        skills: {
            slug: string            // Skill slug
            exp_level: 1|2|3|4      // 1 = just scratched the surface; 2 = using occasianaly, from time to time; 3 = strong theory and practice; 4 = this is my day to day used skill
        }                           // Skills are what is expected of the candidate to know for the job and at what level
        prompt: string              // Additional job prompt for the position
    }                               // Job details
    candidate_id: string            // Candidate ID on the system
    candidate_parsed_cv: {
        summary?: string            // If there was a summary in the CV or cover letter from the application
        education: [string]         // Education details, like schools, colleges, universities, etc.
        experience: [string]        // Jobs with titles, time ranges, descriptions
        hobbies: [string]           // Hobbies or other activities listed if found
        raw: string                 // Whole CV as text, just in case there were some other good details
    }                               // Anonymized and structured CV information of the candidate
    application_form: {
        ...object                   // Custom form questions
        skills: [                   // Candidate will be able to add limited number of primary skills
            {
                slug: string        // Skill slug
                exp_level: 1|2|3|4  // 1 = just scratched the surface; 2 = using occasianaly, from time to time; 3 = strong theory and practice; 4 = this is my day to day used skill
            }
        ]
    }                               // Information provided by the candidate
    pipeline_step_id: string        // ID of the step on the pipeline, so we could map back the results
    call_secret: string             // Additional, unique secret to verify the response is from intended source
    current_rating?: number         // If user has a rating, it will be shown here. Rating goes 0..100
    step_prompt?: string            // Some pipeline step can have additional prompt
    integration_config: object      // Each registered app has config schema, which is configured when app is installed to the team
    comments: [{
        created_at: DateTime        // When it was made
        content: string             // Text of comment
        is_human_created: bool      // Was it written by the human or other app
    }]                              // All the previously written comments about the candidate
    context: [object]               // All previous assessment additional context
    created_at: DateTime            // Just a timestamp when this request was issued
}

Response Format

Your app should respond with:

{
    // Required fields (must be included in response)
    candidate_id: string            // Candidate ID on the system; must match the ID from the request
    pipeline_step_id: string        // ID of the step on the pipeline; must match the ID from the request
    call_secret: string             // Secret verification token; must match the token from the request
    rating: number                  // Assessment rating score between 0-100

    // Optional fields (can be included but not required)
    v?: string                      // API version field to handle schema evolution
    app_id?: string                 // Your APP ID on the system (optional but helpful for tracking)
    context?: object                // Assessment additional context (results, notes, artifacts, etc.)
    comment?: string                // Comment about the assessment result
    status?: any                    // Status of assessment (any format is accepted, not validated)
    failure_details?: string        // Details about any failures during assessment
    created_at?: string|DateTime    // Timestamp when the response was generated
}

Response Format Flexibility

The system accepts several response formats for maximum compatibility:

Standard object response:

{
  "candidate_id": "test_123",
  "pipeline_step_id": "step_456",
  "call_secret": "abc123xyz",
  "rating": 85,
  "comment": "Great candidate!"
}

Array of responses (first item will be used):

[
  {
    "candidate_id": "test_123",
    "pipeline_step_id": "step_456",
    "call_secret": "abc123xyz",
    "rating": 85
  }
]

Nested response under “output” key:

{
  "output": {
    "candidate_id": "test_123",
    "pipeline_step_id": "step_456",
    "call_secret": "abc123xyz",
    "rating": 85
  }
}

The system will automatically sanitize and normalize these different formats before processing.

Validation Notes

Required fields must be present and valid; responses will be rejected if these are missing
Field matching: The candidate_id, pipeline_step_id, and call_secret values must match those from the original request
Rating: Must be a number between 0-100
Status: Any value is accepted (string, number, etc.) and is not validated
app_id: Optional identifier to help with tracking and debugging

Next Steps

Ready to build your first integration? Check out these resources: