API Reference

List Users

Returns a paginated list of users in your organization.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)
role	string	No	Filter by role (candidate, employer, admin)

Response

{
  "success": true,
  "data": [
    {
      "id": "usr_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "candidate",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Create User

Creates a new user account.

Request Body

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "candidate",
  "password": "SecurePassword123"
}

Response

{
  "success": true,
  "data": {
    "id": "usr_xyz789",
    "email": "jane@example.com",
    "name": "Jane Smith",
    "role": "candidate",
    "created_at": "2025-01-15T14:45:00Z"
  }
}

Get Candidate Profile

Retrieves detailed information about a specific candidate.

Path Parameters

id

string

Required

Candidate ID

Response

{
  "success": true,
  "data": {
    "id": "cnd_abc123",
    "user_id": "usr_abc123",
    "profile": {
      "bio": "Experienced software engineer...",
      "skills": ["JavaScript", "Python", "React"],
      "experience_years": 5
    },
    "assessment_scores": {
      "integrity": 92,
      "reliability": 88,
      "teamwork": 95
    }
  }
}

Create Assessment

Initiates a new character assessment for a candidate.

Request Body

{
  "candidate_id": "cnd_abc123",
  "assessment_type": "full_character",
  "include_signals": true,
  "webhook_url": "https://yourapp.com/webhook"
}

Response

{
  "success": true,
  "data": {
    "assessment_id": "ast_xyz789",
    "status": "processing",
    "estimated_completion": "2025-01-15T15:00:00Z"
  }
}

Get Assessment Results

Retrieves the results of a completed assessment.

Response

{
  "success": true,
  "data": {
    "assessment_id": "ast_xyz789",
    "status": "completed",
    "scores": {
      "integrity": 92,
      "judgment": 87,
      "reliability": 90,
      "teamwork": 88,
      "leadership": 85
    },
    "risk_level": "low",
    "recommendations": [
      "Strong candidate for positions requiring trust",
      "Shows consistent ethical decision-making"
    ]
  }
}

Submit Signal

Submit a new public signal about a person.

Request Body

{
  "name": "John Doe",
  "signal_type": "social_media",
  "content": "Post content here...",
  "source_url": "https://twitter.com/...",
  "timestamp": "2025-01-15T10:30:00Z",
  "confidence": "high"
}

Search Signals

Search for signals by name or keywords.

Query Parameters

q	string	Required	Search query
type	string	No	Filter by signal type
date_from	string	No	Start date (ISO 8601)
date_to	string	No	End date (ISO 8601)

Generate Report

Generate a comprehensive character report for a candidate.

Request Body

{
  "candidate_id": "cnd_abc123",
  "report_type": "comprehensive",
  "include_signals": true,
  "include_ai_analysis": true,
  "format": "pdf"
}

Response

{
  "success": true,
  "data": {
    "report_id": "rpt_abc123",
    "download_url": "https://api.hirecharacter.ai/reports/download/rpt_abc123",
    "expires_at": "2025-01-22T15:00:00Z"
  }
}

Find Matches

Find candidate matches for a job position based on character traits.

Request Body

{
  "job_id": "job_123",
  "required_traits": {
    "integrity": 85,
    "reliability": 80,
    "teamwork": 75
  },
  "candidate_pool": ["cnd_001", "cnd_002", "cnd_003"],
  "max_results": 10
}

Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "candidate_id": "cnd_002",
        "match_score": 94,
        "trait_matches": {
          "integrity": 92,
          "reliability": 88,
          "teamwork": 90
        }
      }
    ]
  }
}

Register Webhook

Register a webhook endpoint to receive real-time notifications.

Request Body

{
  "url": "https://yourapp.com/webhook",
  "events": ["assessment.completed", "signal.new", "report.ready"],
  "secret": "your_webhook_secret"
}

Webhook Payload Example

{
  "event": "assessment.completed",
  "timestamp": "2025-01-15T15:00:00Z",
  "data": {
    "assessment_id": "ast_xyz789",
    "candidate_id": "cnd_abc123",
    "status": "completed"
  }
}