Skip to main content

Shared Profile API

The Shared Profile endpoint provides comprehensive candidate information within a specific position context, combining personal details, assessment results, and detailed test performance data.

Available Endpoint​

EndpointMethodDescription
/shared/{candidate_id}/{position_id}GETGet full candidate profile and position information

Endpoint Purpose​

This endpoint provides a complete candidate evaluation view by combining:

  • Personal Information: Name, email, phone, and contact details
  • Resume Details: Experience, skills, education, and parsed resume properties
  • Assessment Results: Overall scores, AI-generated evaluations, and position-specific data
  • Test Performance: Detailed question-level results with candidate answers and correctness
  • File Access: Avatar and resume file URLs for complete candidate records

Use Cases​

Interview Preparation​

  • Access comprehensive candidate profiles before interviews
  • Review detailed test results and performance metrics
  • Analyze skills and experience matching for the position

Candidate Evaluation​

  • Get complete assessment overview including AI-generated insights
  • Compare candidate performance across different test components
  • Access both quantitative scores and qualitative assessment data

Reporting and Documentation​

  • Generate detailed candidate reports with all available information
  • Create comprehensive evaluation summaries
  • Document hiring decisions with complete candidate context

Response Structure​

Profile Section​

Contains candidate personal information and resume details:

{
  "profile": {
    "personal_info": {
      "id": "candidate-uuid",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "phone": "+1-555-123-4567"
    },
    "last_activity": "2023-06-05T14:30:00Z",
    "resume_properties": {
      "language": "English",
      "location_country": "United States",
      "location_city": "Boston",
      "latest_job_title": "Senior Software Engineer"
    },
    "skills": [
      { "skill": "Python", "years_experience": "5+" },
      { "skill": "React", "years_experience": "3" }
    ],
    "avatar_url": "https://storage.example.com/avatars/candidate.jpg",
    "resume_urls": ["https://storage.example.com/resumes/resume.pdf"]
  }
}

Tests Section​

Provides detailed test results with question-level data:

{
  "tests": [
    {
      "id": "test123",
      "name": "Python Programming",
      "type": "Technical Skills",
      "sub_type": "Coding",
      "score": 85,
      "questions": [
        {
          "id": "q1",
          "question": "What is a Python decorator?",
          "type": "Multiple Choice",
          "options": ["Option A", "Option B", "Option C"],
          "candidate_answer": "A function that takes another function as an argument",
          "is_correct": "true"
        }
      ]
    }
  ]
}

Position Results Section​

Contains position-specific assessment information:

{
  "position_results": {
    "id": "assessment123",
    "name": "Software Engineer Assessment",
    "job_title": "Senior Python Developer",
    "status": "Completed",
    "created_at": "2023-06-01T10:00:00Z",
    "completed_at": "2023-06-02T15:30:00Z",
    "ai_score": "87",
    "ai_score_desc": "Strong match for the position",
    "overall_score": 85,
    "salary_expectation": 120000,
    "salary_expectation_currency": "USD"
  }
}

Data Available​

Personal Information​

  • Basic contact details (name, email, phone)
  • Last activity timestamp
  • Avatar image URL

Resume Analysis​

  • Parsed resume properties (location, job title, language)
  • Extracted skills with years of experience
  • Resume file URLs for document access
  • Raw resume text content

Assessment Performance​

  • Overall assessment score
  • AI-generated score and description
  • Assessment status and timeline
  • Salary expectations and currency

Test Results​

  • Individual test scores and performance
  • Complete question and answer details
  • Answer correctness indicators
  • Test categorization (type and sub-type)

Access Requirements​

Authentication​

  • Valid API key required for all requests
  • Candidate must be associated with a position in your organization
  • Position must belong to your organization

Permissions​

  • Organization-based access control
  • Position ownership validation
  • Candidate-position association verification

Error Responses​

403 - Access Denied​

Occurs when:

  • Position doesn't belong to your organization
  • Candidate is not associated with the specified position
  • Insufficient permissions to access the data

404 - Not Found​

Occurs when:

  • Candidate ID doesn't exist
  • Position ID doesn't exist
  • Candidate-position association doesn't exist

500 - Server Error​

Occurs when:

  • Database connectivity issues
  • Unexpected system errors
  • Data processing failures

Implementation Notes​

Data Completeness​

  • Not all candidates may have complete profile information
  • Resume properties depend on successful AI processing
  • Skills data requires resume analysis completion
  • Test results only available after assessment completion

File URLs​

  • Avatar and resume URLs are pre-signed for secure access
  • URLs have expiration times for security
  • Files are stored securely with organization-based access controls

Performance Considerations​

  • This endpoint returns comprehensive data and may have longer response times
  • Consider caching responses for frequently accessed candidate profiles
  • Use appropriate timeout settings for API calls

This endpoint serves as a comprehensive data source for candidate evaluation, providing all available information in a single API call for complete candidate assessment workflows.