Hirewall API

The enterprise interface to Ansius candidate evaluation.

Built for job boards, HR platforms, marketplaces, and ATS providers that need reliable candidate intelligence at scale.

Quick Start

Submit CV Analysis (cURL)

curl -X POST https://ansius.com/api/hirewall/v1/cv-match/analyze \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cv": "John Doe\nSoftware Engineer with 5 years...",
    "jobDescription": "We are looking for a Senior Developer...",
    "options": {
      "returnFormat": "full",
      "language": "en",
      "webhookUrl": "https://yoursite.com/webhook"
    },
    "requestId": "unique-request-123"
  }'

Response (202 Accepted):

{
  "requestId": "unique-request-123",
  "status": "processing",
  "statusUrl": "/api/hirewall/v1/cv-match/status/unique-request-123",
  "resultUrl": "/api/hirewall/v1/cv-match/result/unique-request-123",
  "message": "Job queued. You will receive a webhook when complete."
}

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header.

X-API-Key: your_api_key_here

Security Note: Never expose your API key in client-side code. Always make API calls from your backend server.

Base URL

https://ansius.com/api/hirewall/v1

API Endpoints

POST

Submit CV Analysis

/cv-match/analyze

Submit a CV and job description for matching analysis. Returns immediately with a request ID for tracking.

Request Body:

{
  "cv": "string (required) - Plain text CV content",
  "jobDescription": "string (required) - Plain text job description",
  "options": {
    "returnFormat": "full | summary | score-only (optional, default: summary)",
    "language": "en | es | fr | de | pt | it | ... (optional, default: en)",
    "webhookUrl": "string (optional) - URL for webhook delivery"
  },
  "requestId": "string (optional) - For idempotency"
}

Response (202 Accepted):

{
  "requestId": "unique-id",
  "status": "processing",
  "statusUrl": "/api/hirewall/v1/cv-match/status/{requestId}",
  "resultUrl": "/api/hirewall/v1/cv-match/result/{requestId}"
}

GET

Check Job Status

/cv-match/status/{requestId}

Check the processing status of a submitted analysis job.

Response (200 OK):

{
  "requestId": "unique-id",
  "status": "queued | processing | completed | failed",
  "queuedAt": "ISO 8601 timestamp",
  "completedAt": "ISO 8601 timestamp (if completed)",
  "processingTime": "duration (if completed)",
  "resultUrl": "/api/hirewall/v1/cv-match/result/{requestId}"
}

GET

Get Analysis Result

/cv-match/result/{requestId}

Retrieve the completed analysis result. Only available after job status is completed.

Response (200 OK):

{
  "requestId": "unique-id",
  "status": "completed",
  "data": {
    "matchScore": 87,
    "maxScore": 100,
    "analysis": {
      "criticalMatches": 4,
      "importantMatches": 6,
      "niceToHaveMatches": 3
    },
    "categoryScores": {
      "critical": "45/50",
      "important": "28/30",
      "niceToHave": "14/20"
    },
    "matches": [
      {
        "requirement": "string - Job requirement",
        "matchLevel": "full | partial | none",
        "score": 0-10,
        "evidence": "string - Evidence from CV",
        "category": "critical | important | niceToHave"
      }
    ]
  },
  "metadata": {
    "processedAt": "ISO 8601 timestamp",
    "processingTime": "milliseconds",
    "creditsUsed": 1
  }
}

Webhooks

Receive instant notifications when analysis completes. Provide a webhookUrl in your request.

Webhook Payload:

POST https://your-webhook-url.com/endpoint
Content-Type: application/json
X-Ansius-Signature: HMAC-SHA256 signature
X-Ansius-Request-Id: unique-request-id

{
  "requestId": "unique-id",
  "status": "completed",
  "data": {
    "matchScore": 87,
    "maxScore": 100,
    "analysis": { ... },
    "categoryScores": { ... },
    "matches": [ ... ]
  },
  "metadata": {
    "processedAt": "2025-10-17T10:30:45Z",
    "processingTime": 45000,
    "creditsUsed": 1
  }
}

Verify Webhook Signature:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Important: Always verify webhook signatures to ensure requests are from Hirewall API.

Rate Limits

Rate limits are customized per partnership. Standard limits:

• 30 requests per minute

• 5,000 requests per day

Rate Limit Headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 25
X-RateLimit-Reset: 1634467200

When rate limit is exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header.

Error Handling

Error Response Format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "statusCode": 400
}

Common Error Codes:

• 401 INVALID_API_KEY - API key is invalid or missing

• 403 IP_NOT_ALLOWED - Request from non-whitelisted IP

• 400 INVALID_INPUT - Request validation failed

• 429 RATE_LIMIT_EXCEEDED - Too many requests

• 404 NOT_FOUND - Resource not found

Supported Languages

Specify the desired output language using ISO 639-1 codes in the options.language parameter.

• en - English

• es - Spanish

• fr - French

• de - German

• pt - Portuguese

• it - Italian

• nl - Dutch

• pl - Polish

• ru - Russian

• zh - Chinese

• ja - Japanese

• ko - Korean

+ 24 more languages supported. If not specified, defaults to English.

Best Practices

• Use webhooks instead of polling for better performance and real-time updates

• Implement idempotency by providing unique requestId values to prevent duplicate processing

• Verify webhook signatures to ensure requests are from Hirewall API

• Handle rate limits gracefully with exponential backoff and retry logic

• Keep API keys secure - never expose them in client-side code or public repositories

• Monitor usage via rate limit headers to optimize request patterns