API Documentation

Authentication

The Outreach API uses OAuth 2.0 for authentication, providing secure, auditable access with per-user accountability. All API requests require a valid access token.

OAuth 2.0 Flow Overview

GET https://outreach.taladria.com/api/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &state=RANDOM_STATE_STRING

POST https://outreach.taladria.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://your-app.com/callback

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Using Access Tokens

Include the access token in the Authorization header for all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Lifetimes

Refreshing Access Tokens

POST https://outreach.taladria.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Endpoints

{
  "jobSpec": "Senior PHP Developer with Laravel experience, 5+ years, Dublin-based",
  "topN": 10,
  // Optional: Job title for improved search relevance and email subjects
  "jobTitle": "Senior PHP Developer",
  // Optional: Location filtering
  "jobLocation": "Dublin, Ireland",
  "radiusKm": 50,
  // Optional: Must-have requirements (ALL must be met)
  "mustHaves": "5+ years PHP, Laravel experience"
}

{
  "companyId": "your-company",
  "matchCount": 5,
  "totalScored": 10,
  "clientRequirements": ["5+ years PHP", "Laravel experience", "Dublin-based"],
  "promptInfo": {
    "source": "company_specific",
    "versionId": "match_scoring_20240105_0920",
    "companyId": "your-company"
  },
  "matches": [
    {
      "resumeId": "abc123",
      "name": "Alex Thompson",
      "email": "alex@example.com",
      "phone": "+353 87 1234567",
      "location": "Dublin, Ireland",
      "skills": ["PHP", "Laravel", "MySQL", "Docker", "Redis"],
      "matchScore": 0.80,
      "matchReasoning": "SCORE: 80\n\nSTRENGTHS:\n**Extensive PHP Experience:** 10 years of full-stack development...\n\nCONCERNS:\n**No AI/LLM Experience:** The role requires AI integration...\n\nRECOMMENDATION: YES - Strong technical foundation makes this candidate worth interviewing.\n\nINTERVIEW_FOCUS:\n**AI Learning Aptitude:** Assess willingness to learn AI/LLM technologies...",
      "meets_all_must_haves": true,
      "must_haves_identified": ["5+ years PHP", "Laravel experience", "Dublin-based"],
      "bullhornId": "123456",
      "bullhornUrl": "https://cls20.bullhornstaffing.com/BullhornStaffing/OpenWindow.cfm?Entity=Candidate&id=123456",
      "atsType": "bullhorn"
    }
  ]
}

Error Responses

Code Examples

cURL

curl -X POST \
  https://outreach.taladria.com/api/match-candidates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jobSpec": "Senior PHP Developer with Laravel, 5+ years experience",
    "topN": 5
  }'

Python

import requests

response = requests.post(
    "https://outreach.taladria.com/api/match-candidates",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    json={
        "jobSpec": "Senior PHP Developer with Laravel, 5+ years experience",
        "topN": 5
    }
)

data = response.json()
for candidate in data["matches"]:
    print(f"{candidate['name']}: {candidate['matchScore']*100:.0f}%")

JavaScript / Node.js

const response = await fetch(
  "https://outreach.taladria.com/api/match-candidates",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    body: JSON.stringify({
      jobSpec: "Senior PHP Developer with Laravel, 5+ years experience",
      topN: 5
    })
  }
);

const data = await response.json();
data.matches.forEach(candidate => {
  console.log(`${candidate.name}: ${(candidate.matchScore * 100).toFixed(0)}%`);
});

Location + Must-Haves Example (Python)

import requests

# Combined location and must-haves filtering (unified endpoint)
response = requests.post(
    "https://outreach.taladria.com/api/match-candidates",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    json={
        "jobSpec": "Senior PHP Developer with Laravel",
        "jobLocation": "Dublin, Ireland",
        "radiusKm": 50,
        "mustHaves": "5+ years PHP, Laravel experience",
        "topN": 10
    }
)

data = response.json()
print(f"Found {data['matchCount']} candidates within {data.get('radiusKm', 'N/A')}km")
for candidate in data["matches"]:
    distance = candidate.get('distanceKm', 'N/A')
    print(f"{candidate['name']}: {candidate['matchScore']*100:.0f}% - {distance}km away")

Need Help?

For API support, integration assistance, or to request higher rate limits, contact us at info@taladria.com.