API Code Examples

JavaScript / Node.js

Installation

npm install @hirecharacter/api-client

Basic Usage

const HireCharacter = require('@hirecharacter/api-client');

// Initialize the client
const client = new HireCharacter({
  apiKey: 'YOUR_API_KEY'
});

// Get user list
async function getUsers() {
  try {
    const users = await client.users.list({
      page: 1,
      per_page: 20
    });
    console.log(users);
  } catch (error) {
    console.error('Error:', error);
  }
}

// Create an assessment
async function createAssessment(candidateId) {
  try {
    const assessment = await client.assessments.create({
      candidate_id: candidateId,
      assessment_type: 'full_character',
      include_signals: true
    });
    console.log('Assessment created:', assessment.assessment_id);
  } catch (error) {
    console.error('Error:', error);
  }
}

// Search for signals
async function searchSignals(name) {
  try {
    const signals = await client.signals.search({
      q: name,
      type: 'social_media',
      limit: 10
    });
    console.log('Found signals:', signals);
  } catch (error) {
    console.error('Error:', error);
  }
}

Webhook Handler

const express = require('express');
const app = express();

app.post('/webhook', express.json(), (req, res) => {
  const { event, data } = req.body;

  switch(event) {
    case 'assessment.completed':
      console.log('Assessment completed:', data.assessment_id);
      // Handle completed assessment
      break;
    case 'signal.new':
      console.log('New signal:', data.signal_id);
      // Handle new signal
      break;
    default:
      console.log('Unknown event:', event);
  }

  res.status(200).send('OK');
});

Python

Installation

pip install hirecharacter

Basic Usage

import hirecharacter
from hirecharacter.exceptions import APIError

# Initialize the client
client = hirecharacter.Client(api_key='YOUR_API_KEY')

# Get user list
def get_users():
    try:
        users = client.users.list(page=1, per_page=20)
        for user in users['data']:
            print(f"User: {user['name']} ({user['email']})")
    except APIError as e:
        print(f"Error: {e}")

# Create an assessment
def create_assessment(candidate_id):
    try:
        assessment = client.assessments.create(
            candidate_id=candidate_id,
            assessment_type='full_character',
            include_signals=True
        )
        print(f"Assessment created: {assessment['assessment_id']}")
        return assessment
    except APIError as e:
        print(f"Error: {e}")

# Generate a report
def generate_report(candidate_id):
    try:
        report = client.reports.generate(
            candidate_id=candidate_id,
            report_type='comprehensive',
            format='pdf'
        )
        print(f"Report URL: {report['download_url']}")
        return report
    except APIError as e:
        print(f"Error: {e}")

# Search for signals
def search_signals(name):
    try:
        signals = client.signals.search(
            q=name,
            type='social_media',
            limit=10
        )
        for signal in signals['data']:
            print(f"Signal: {signal['content'][:100]}...")
    except APIError as e:
        print(f"Error: {e}")

Async Example

import asyncio
import aiohttp

async def fetch_assessment(session, assessment_id):
    headers = {'Authorization': f'Bearer {API_KEY}'}
    url = f'https://api.hirecharacter.ai/v1/assessments/{assessment_id}'

    async with session.get(url, headers=headers) as response:
        return await response.json()

async def batch_assessments(assessment_ids):
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_assessment(session, aid) for aid in assessment_ids]
        results = await asyncio.gather(*tasks)
        return results

PHP

Installation

composer require hirecharacter/api-client

Basic Usage

<?php
require 'vendor/autoload.php';

use HireCharacter\Client;
use HireCharacter\Exception\APIException;

// Initialize the client
$client = new Client('YOUR_API_KEY');

// Get user list
try {
    $users = $client->users->list([
        'page' => 1,
        'per_page' => 20
    ]);

    foreach ($users['data'] as $user) {
        echo "User: {$user['name']} ({$user['email']})\n";
    }
} catch (APIException $e) {
    echo "Error: " . $e->getMessage();
}

// Create an assessment
function createAssessment($client, $candidateId) {
    try {
        $assessment = $client->assessments->create([
            'candidate_id' => $candidateId,
            'assessment_type' => 'full_character',
            'include_signals' => true
        ]);

        echo "Assessment created: {$assessment['assessment_id']}\n";
        return $assessment;
    } catch (APIException $e) {
        echo "Error: " . $e->getMessage();
    }
}

// Submit a signal
function submitSignal($client, $signalData) {
    try {
        $signal = $client->signals->create([
            'name' => $signalData['name'],
            'signal_type' => 'social_media',
            'content' => $signalData['content'],
            'source_url' => $signalData['url'],
            'confidence' => 'high'
        ]);

        echo "Signal submitted: {$signal['signal_id']}\n";
        return $signal;
    } catch (APIException $e) {
        echo "Error: " . $e->getMessage();
    }
}

Webhook Handler

<?php
$payload = json_decode(file_get_contents('php://input'), true);

if ($payload) {
    switch($payload['event']) {
        case 'assessment.completed':
            handleAssessmentCompleted($payload['data']);
            break;
        case 'signal.new':
            handleNewSignal($payload['data']);
            break;
    }

    http_response_code(200);
    echo "OK";
}

Ruby

Installation

gem install hirecharacter

Basic Usage

require 'hirecharacter'

# Initialize the client
client = HireCharacter::Client.new(api_key: 'YOUR_API_KEY')

# Get user list
begin
  users = client.users.list(page: 1, per_page: 20)
  users['data'].each do |user|
    puts "User: #{user['name']} (#{user['email']})"
  end
rescue HireCharacter::APIError => e
  puts "Error: #{e.message}"
end

# Create an assessment
def create_assessment(client, candidate_id)
  begin
    assessment = client.assessments.create(
      candidate_id: candidate_id,
      assessment_type: 'full_character',
      include_signals: true
    )
    puts "Assessment created: #{assessment['assessment_id']}"
    assessment
  rescue HireCharacter::APIError => e
    puts "Error: #{e.message}"
  end
end

# Search signals
def search_signals(client, name)
  begin
    signals = client.signals.search(
      q: name,
      type: 'social_media',
      limit: 10
    )
    signals['data'].each do |signal|
      puts "Signal: #{signal['content'][0..100]}..."
    end
  rescue HireCharacter::APIError => e
    puts "Error: #{e.message}"
  end
end

Java

Maven Dependency

<dependency>
    <groupId>ai.hirecharacter</groupId>
    <artifactId>api-client</artifactId>
    <version>1.0.0</version>
</dependency>

Basic Usage

import ai.hirecharacter.Client;
import ai.hirecharacter.models.*;
import ai.hirecharacter.exceptions.APIException;

public class HireCharacterExample {
    public static void main(String[] args) {
        // Initialize the client
        Client client = new Client("YOUR_API_KEY");

        // Get user list
        try {
            UserList users = client.users().list(1, 20);
            for (User user : users.getData()) {
                System.out.println("User: " + user.getName() +
                                 " (" + user.getEmail() + ")");
            }
        } catch (APIException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }

    // Create an assessment
    public Assessment createAssessment(Client client, String candidateId) {
        try {
            AssessmentRequest request = new AssessmentRequest()
                .setCandidateId(candidateId)
                .setAssessmentType("full_character")
                .setIncludeSignals(true);

            Assessment assessment = client.assessments().create(request);
            System.out.println("Assessment created: " +
                             assessment.getAssessmentId());
            return assessment;
        } catch (APIException e) {
            System.err.println("Error: " + e.getMessage());
            return null;
        }
    }

    // Generate a report
    public Report generateReport(Client client, String candidateId) {
        try {
            ReportRequest request = new ReportRequest()
                .setCandidateId(candidateId)
                .setReportType("comprehensive")
                .setFormat("pdf");

            Report report = client.reports().generate(request);
            System.out.println("Report URL: " + report.getDownloadUrl());
            return report;
        } catch (APIException e) {
            System.err.println("Error: " + e.getMessage());
            return null;
        }
    }
}

cURL

Get Users

curl -X GET "https://api.hirecharacter.ai/v1/users?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create Assessment

curl -X POST "https://api.hirecharacter.ai/v1/assessments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cnd_abc123",
    "assessment_type": "full_character",
    "include_signals": true
  }'

Search Signals

curl -X GET "https://api.hirecharacter.ai/v1/signals/search?q=John%20Doe&type=social_media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Generate Report

curl -X POST "https://api.hirecharacter.ai/v1/reports/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_id": "cnd_abc123",
    "report_type": "comprehensive",
    "include_signals": true,
    "format": "pdf"
  }'

Register Webhook

curl -X POST "https://api.hirecharacter.ai/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook",
    "events": ["assessment.completed", "signal.new"],
    "secret": "your_webhook_secret"
  }'