Skip to content
SolidATS Logo SolidATS Logo Developer Portal

SolidATS App Integration API

SolidATS App Integration API Reference

This documentation provides detailed information about the SolidATS API for developers building app integrations.

Authentication

All API requests require authentication using an API key that you receive when you register your app in the SolidATS marketplace.

Authorization: Bearer YOUR_API_KEY

Webhook Endpoints

Receiving Assessment Requests

Your app must expose a webhook endpoint to receive assessment requests from SolidATS.

URL: Your specified webhook URL (configured during app registration) Method: POST Content-Type: application/json

Request Payload Schema

{
    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
}

Responding to Assessment Requests

Your app can respond in two ways:

  1. Synchronous response: Return the assessment result directly in the webhook response
  2. Asynchronous response: Return a 202 Accepted status and later submit results to the SolidATS callback endpoint

Response Schema

{
    // 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:

  1. Standard object response:
{
  "candidate_id": "test_123",
  "pipeline_step_id": "step_456",
  "call_secret": "abc123xyz",
  "rating": 85,
  "comment": "Great candidate!"
}
  1. Array of responses (first item will be used):
[
  {
    "candidate_id": "test_123",
    "pipeline_step_id": "step_456",
    "call_secret": "abc123xyz",
    "rating": 85
  }
]
  1. 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

Asynchronous Callback

For assessments that take longer to process, use the asynchronous pattern.

URL: https://api.solidats.com/webhook/app-callback Method: POST Content-Type: application/json Headers:

  • Authorization: Bearer YOUR_API_KEY
  • X-SolidATS-App-ID: YOUR_APP_ID

The request body should match the Response Schema above.

Status Codes

  • 200 OK: Assessment completed successfully
  • 202 Accepted: Assessment in progress (for async processing)
  • 400 Bad Request: Invalid payload
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server-side error

Implementation Examples

Node.js Example (Express)

const express = require('express');
const app = express();
app.use(express.json());


app.post('/webhook/assessment', (req, res) => {
  const {
    candidate_id,
    pipeline_step_id,
    call_secret,
    candidate_parsed_cv,
    application_form,
    integration_config,
    job
  } = req.body;


  // Process assessment
  // ...


  // Return immediate response
  res.json({
    app_id: 'your-app-id',
    candidate_id,
    pipeline_step_id,
    call_secret,
    rating: 85,  // 0-100 score based on your assessment
    context: {
      // Additional assessment data
      skills_matched: ['JavaScript', 'React', 'Node.js'],
      strengths: ['Problem solving', 'Communication'],
      areas_for_improvement: ['Database design']
    },
    comment: 'Strong candidate with excellent frontend skills. Consider for technical interview.',
    status: 200
  });
});


app.listen(3000, () => {
  console.log('Assessment webhook server running on port 3000');
});

Python Example (Flask)

from flask import Flask, request, jsonify
import json
from datetime import datetime


app = Flask(__name__)


@app.route('/webhook/assessment', methods=['POST'])
def process_assessment():
    data = request.get_json()


    # Extract necessary information
    candidate_id = data.get('candidate_id')
    pipeline_step_id = data.get('pipeline_step_id')
    call_secret = data.get('call_secret')
    parsed_cv = data.get('candidate_parsed_cv', {})
    application_form = data.get('application_form', {})
    job_details = data.get('job', {})


    # Process assessment
    # ...


    # Return assessment result
    return jsonify({
        'candidate_id': candidate_id,
        'pipeline_step_id': pipeline_step_id,
        'call_secret': call_secret,
        'rating': 78,
        'app_id': 'your-app-id',  # Optional but helpful for tracking
        'context': {
            'assessment_details': 'Custom assessment data'
        },
        'comment': 'Candidate shows promising skills in data analysis.',
        'status': 200,
        'created_at': datetime.now().isoformat()
    })


if __name__ == '__main__':
    app.run(debug=True, port=5000)