API Documentation

Pass your API key in the Authorization header:

curl -H "Authorization: Bearer rr_live_YOUR_KEY_HERE" \
  https://recruiterroles.com/api/v1/jobs

Keys are issued instantly from the API access page. The raw key is shown once — store it securely.

1,000 requests per day per key, resetting at midnight UTC.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1775260800

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

All errors return a consistent JSON body:

{
  "error": "error_code",
  "message": "Human-readable description."
}

Job URLs in API responses are tracked redirect links with UTM parameters for attribution:

Your ref_code is auto-assigned when your key is created.

Paginated list of active recruiter job listings with filtering and search.

Parameters

Example request

curl -H "Authorization: Bearer rr_live_YOUR_KEY" \
  "https://recruiterroles.com/api/v1/jobs?sector=technology&per_page=2"

Example response

{
  "data": [
    {
      "id": "809385c1-19e2-4cf1-9096-a06f96e897a2",
      "slug": "associate-technology-temporary-position-300-robert-half-canada-inc-f956ba",
      "title": "Associate (Technology) - Temporary Position",
      "company_name": "300 Robert Half Canada Inc.",
      "company_website": null,
      "company_logo_url": null,
      "location": {
        "city": "Vancouver",
        "state": "BC",
        "is_remote": false,
        "work_arrangement": null
      },
      "employment_type": "full_time",
      "primary_sector": "Technology",
      "secondary_sectors": [],
      "salary": {
        "disclosed": false,
        "min_dollars": null,
        "max_dollars": null,
        "currency": "USD"
      },
      "commission": { "disclosed": false, "details": null },
      "billing_target": { "disclosed": false, "details": null },
      "description_excerpt": "As an Associate, you will be responsible for...",
      "source_type": "scraped",
      "apply_url": "https://roberthalf.wd1.myworkdayjobs.com/...",
      "url": "https://recruiterroles.com/go/associate-technology-...-f956ba?ref=your_ref",
      "canonical_url": "https://recruiterroles.com/jobs/associate-technology-...-f956ba",
      "posted_at": "2026-04-03T18:01:26.048+00:00",
      "updated_at": "2026-04-03T20:20:07.859+00:00",
      "expires_at": "2026-06-02T18:01:26.048+00:00",
      "is_featured": false,
      "is_homepage_featured": false
    }
  ],
  "meta": {
    "total": 148,
    "page": 1,
    "per_page": 2,
    "total_pages": 74,
    "next_page": 2,
    "prev_page": null
  },
  "response_generated_at": "2026-04-03T20:23:15.123Z"
}

Full detail for a single job. Returns all list fields plus description, requirements, benefits, tech_stack, team_size, and apply_email.

Example request

curl -H "Authorization: Bearer rr_live_YOUR_KEY" \
  "https://recruiterroles.com/api/v1/jobs/practice-director-technology-contract-300-robert-half-canada-inc-897525"

Example response (additional fields)

{
  "data": {
    "slug": "practice-director-technology-contract-...-897525",
    "title": "Practice Director (Technology Contract)",
    "company_name": "300 Robert Half Canada Inc.",
    "location": { "city": "Vancouver", "state": "BC", "is_remote": false },
    "salary": { "disclosed": true, "min_dollars": 68000, "max_dollars": 100000, "currency": "USD" },
    "description": "The primary responsibility of the Practice Director is to...",
    "requirements": null,
    "benefits": "Base salary ranging from $68,000 to $100,000\nBonus eligibility...",
    "tech_stack": [],
    "team_size": null,
    "apply_email": null,
    "is_sticky": false,
    "url": "https://recruiterroles.com/go/practice-director-...-897525?ref=your_ref",
    "canonical_url": "https://recruiterroles.com/jobs/practice-director-...-897525"
  }
}

Returns 404 for expired, deleted, or pending jobs.

Paginated directory of recruiting companies with active job counts. Default sort by job count descending.

Parameters

Example response

{
  "data": [
    {
      "slug": "robert-half",
      "name": "Robert Half",
      "logo_url": "https://assets.recruiterroles.com/company-logos/robert-half.webp",
      "description": "Robert Half is a staffing agency based in Menlo Park, CA...",
      "website_url": "https://www.roberthalf.com",
      "company_type": "staffing_agency",
      "employee_count_range": "10000+",
      "headquarters": { "city": "Menlo Park", "state": "CA", "country": "US" },
      "specialties": ["consulting services", "accounting jobs", "finance jobs", "..."],
      "founded_year": 1948,
      "is_verified": true,
      "active_job_count": 159
    }
  ],
  "meta": { "total": 287, "page": 1, "per_page": 20, "total_pages": 15 }
}

Full company profile with a paginated list of their active jobs.

Parameters

Example response

{
  "data": {
    "slug": "robert-half",
    "name": "Robert Half",
    "logo_url": "https://assets.recruiterroles.com/company-logos/robert-half.webp",
    "description": "Robert Half is a staffing agency based in Menlo Park, CA...",
    "website_url": "https://www.roberthalf.com",
    "linkedin_url": "https://www.linkedin.com/company/robert-half-international/",
    "company_type": "staffing_agency",
    "employee_count_range": "10000+",
    "headquarters": { "city": "Menlo Park", "state": "CA", "country": "US" },
    "founded_year": 1948,
    "is_verified": true,
    "active_job_count": 159,
    "url": "https://recruiterroles.com/companies/robert-half",
    "jobs": {
      "data": [{ "slug": "...", "title": "...", "..." }],
      "meta": { "total": 159, "page": 1, "per_page": 20 }
    }
  }
}

All 9 recruiting sectors with current active job counts.

Example response

{
  "data": [
    { "slug": "financial-services", "name": "Financial Services", "job_count": 92 },
    { "slug": "technology", "name": "Technology", "job_count": 148 },
    { "slug": "healthcare-life-sciences", "name": "Healthcare & Life Sciences", "job_count": 77 },
    { "slug": "professional-services", "name": "Professional Services", "job_count": 312 },
    "..."
  ]
}

Location hierarchy for building filter UIs. Returns countries, regions, or cities with active job counts.

Parameters

Example: List countries

curl -H "Authorization: Bearer rr_live_YOUR_KEY" \
  "https://recruiterroles.com/api/v1/locations?level=countries"

{
  "data": [
    { "code": "US", "name": "United States", "active_job_count": 531 },
    { "code": "CA", "name": "Canada", "active_job_count": 101 },
    { "code": "GB", "name": "United Kingdom", "active_job_count": 13 },
    { "code": "AU", "name": "Australia", "active_job_count": 9 }
  ]
}

Example: US states

GET /api/v1/locations?level=regions&country=US

{
  "data": [
    { "code": "CA", "name": "California", "active_job_count": 72 },
    { "code": "TX", "name": "Texas", "active_job_count": 30 },
    { "code": "AZ", "name": "Arizona", "active_job_count": 6 },
    "..."
  ]
}

Aggregate market overview — total jobs, posting velocity, and breakdowns by sector, employment type, work arrangement, and country.

Example response

{
  "data": {
    "total_active_jobs": 711,
    "jobs_posted_24h": 24,
    "jobs_posted_7d": 173,
    "by_sector": [
      { "slug": "professional-services", "name": "Professional Services", "count": 312 },
      { "slug": "technology", "name": "Technology", "count": 148 },
      "..."
    ],
    "by_employment_type": { "full_time": 711 },
    "by_work_arrangement": { "on_site": 606, "hybrid": 0, "remote": 105 },
    "top_countries": [
      { "name": "US", "count": 531 },
      { "name": "CA", "count": 101 },
      "..."
    ]
  }
}

Every page displaying data from this API must include a visible, crawlable link back to Recruiter Roles:

Jobs sourced from <a href="https://recruiterroles.com">Recruiter Roles</a>

Keys may be suspended if the backlink is removed or hidden.