Back

Recruitee API Essential Guide

Aug 17, 20246 minute read

What type of API does Recruitee provide?

Recruitee offers a public API that allows users to automate workflows and integrate with websites and other software. The API documentation refers to "Recruitee's ATS API" and "Recruitee's Careers Site API", which suggests a REST-style API architecture. The API requires authentication using API tokens that can be generated in the Recruitee settings.

Does the Recruitee API have webhooks?

Yes, the official Recruitee API does have webhooks. Here are the key points about Recruitee's webhook functionality:

Webhook Availability

  • Recruitee offers webhooks as part of their API, allowing you to receive notifications when certain events occur in the system.

Configurable Events

You can subscribe to the following types of events:

  1. Candidate created

    • Event type: "new_candidate"
    • Event subtypes: "email", "career_site", "manual", or "imported"
  2. Candidate assigned

  3. Move on pipeline (candidate moved)

    • Event type: "candidate_moved"
    • Event subtype: "stage_changed"
  4. Candidate deleted

  5. Job published

    • Event type: "offer_published"
    • Event subtype: "manual"
  6. Job unpublished

  7. Job updated

Webhook Configuration

  • Webhooks can be configured under Settings > Apps and Plugins > Webhooks in the Recruitee interface.
  • You need to provide an HTTPS endpoint URL where Recruitee will send the webhook notifications.
  • You can select which specific events you want to subscribe to.

Webhook Security

  • Recruitee provides a webhook verification mechanism using the X-Recruitee-Signature header and a webhook secret.
  • It's strongly recommended to verify the webhooks for security purposes.

Additional Features

  • Recruitee offers a test functionality to send sample payloads to your endpoint.
  • You can set up email notifications for failed webhook deliveries.

Best Practices

  • Use HTTPS for your webhook endpoint.
  • Implement proper error handling and logging for your webhook receiver.
  • Verify the webhook signatures to ensure the requests are coming from Recruitee.

By utilizing these webhooks, you can create real-time integrations and automate workflows based on events occurring in your Recruitee account.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding the API Rate Limits of the Recruitee API:

No Current Rate Limits

Currently, Recruitee does not impose any rate limits on their API usage. Specifically:

  • There are no limits on the API usage.
  • There are no limits on the number of generated API Tokens.

Key Points to Consider

While there are no explicit rate limits, there are some important aspects to keep in mind when using the Recruitee API:

  1. Authentication: The API requires authentication using an API Token.

  2. Token Scope: API Tokens have the same permissions as the user who generated them.

  3. Company-Specific Tokens: API Tokens are generated per user and per company, with respect to their user role.

  4. Token Management: You can revoke API Tokens at any time, but this will stop any integrations using that token.

  5. User Removal: Removing a user from your company will restrict access of their API Tokens to your company.

Best Practices

Even though there are no rate limits, it's advisable to follow these best practices:

  1. Use separate API Tokens for different integrations for easier management.

  2. Be careful when sharing your API Tokens with other people, as they have the same permissions as your user account.

  3. When making modifications (POST, PATCH, DELETE methods), be cautious as these requests are run live on your account.

  4. If you're missing any endpoints or examples, contact Recruitee via Intercom for improvements to their documentation.

Summary

While Recruitee currently does not impose API rate limits, users should still be mindful of their API usage and follow best practices for token management and security. It's also worth noting that this policy could change in the future, so it's a good idea to design your integrations with potential rate limits in mind.

Latest API Version

Based on the search results provided, I could not find a specific mention of the most recent version of the Recruitee API. However, I can provide some relevant information about the Recruitee API:

Key Points:

  • Recruitee offers both a Careers Site API and an ATS (Applicant Tracking System) API.

  • The full API endpoint documentation is available at https://apidocs.recruitee.com/.

  • The API requires authentication using an API token.

API Access and Authentication:

  • To use the ATS API, you need to generate a personal API token under Settings > Apps and plugins > Personal API tokens.

  • API requests require authentication with a header Authorization: Bearer <token>.

  • API tokens have the same permissions as the user who generated them.

API Documentation:

  • Recruitee provides detailed API documentation, which includes:

    • Sidebar navigation divided into Careers Site API, ATS API, Guides, and Partner API
    • Main documentation section with endpoint descriptions, arguments, and use cases
    • Examples of API calls and responses
  • The documentation includes a "Try It" feature that allows testing endpoints directly in the browser.

Additional Information:

  • Recruitee's API allows for automation and integration of recruitment processes with other tools and services.

  • Popular API actions include creating candidates, notes, and tasks.

  • The API can be used for various integrations, such as syncing candidates to Google Sheets or automating candidate evaluation notifications.

While I couldn't find the specific version number of the most recent Recruitee API, the information provided should give you a good overview of its current state and capabilities. If you need the exact version number, I recommend checking the official Recruitee API documentation or contacting their support directly.

How to get a Recruitee developer account and API Keys?

To get a developer account for Recruitee and create an API integration, you need to follow these steps:

Obtaining an API Token

  1. Log in to your existing Recruitee account.
  2. Navigate to Settings > Apps and plugins > Personal API tokens.
  3. Click on the '+ New token' button in the top-right corner to generate your personal API token.

Key Points to Consider

  • The permissions associated with this API token will be based on the Hiring Role of the person who created it.
  • The token does not expire unless a user has revoked it.
  • You'll need to note down your Company ID, which can be found in the Company Settings, User Profile, or Personal API tokens section.

Creating a Partner (for Integration)

To create a partner for API integration, you need to make a POST request to Recruitee's API. Here's an example:

POST https://integrations.rc.recruitee.dev/api/p/{codename}/c/{company_id}/partner HTTP/1.1
Content-Type: application/json
Authorization: Bearer {token}

{
  "kind": "assessment",
  "name": "My Assessments",
  "urls": {
    "help_article": "https://example.com",
    "validate_token": "https://c9d2c92dc329471696e8a6b670ea7c2b.m.pipedream.net",
    "tests": "https://1da22d5d35232651e170c77e943d5a68.m.pipedream.net",
    "send_candidate": "https://44c576c0fcabcf04b41673900b795b1b.m.pipedream.net"
  }
}

Replace {codename}, {company_id}, and {token} with your specific values.

Best Practices

  1. Keep your API token secure and do not share it publicly.
  2. Use HTTPS for all API requests to ensure data security.
  3. Handle API rate limits and potential errors gracefully in your integration.
  4. Regularly review and update your integration to ensure compatibility with any API changes.

What can you do with the Recruitee API?

Based on the search results provided, here is a list of data models that can be interacted with using the Recruitee API, along with what is possible for each:

Candidates

  • Create new candidates
  • Update existing candidate information
  • Retrieve candidate details
  • Add notes to candidate profiles
  • Create tasks related to candidates

Jobs

  • Post new job openings
  • Update existing job postings
  • Retrieve job details
  • Monitor for new job postings

Applications

  • Track new applications
  • Update application statuses
  • Retrieve application details

Recruitment Activities

  • Create and manage recruitment tasks
  • Track candidate evaluation processes
  • Monitor candidate status changes through different stages

Notes

  • Create new notes for candidates
  • Retrieve notes associated with candidates

Tasks

  • Create new tasks related to candidates or jobs
  • Update task statuses
  • Retrieve task details

Company Data

  • Access company profile information
  • Retrieve company ID for API calls

Analytics

  • Access recruitment analytics data
  • Retrieve metrics on job success, candidate conversions, etc.

Team Performance

  • Track KPIs related to team performance
  • Access dashboards with team metrics

Sourcing Channels

  • Track effectiveness of different sourcing platforms
  • Analyze which channels produce the best candidates

Hiring Process

  • Monitor lead times in the hiring process
  • Identify bottlenecks in the recruitment workflow

Talent Pool

  • Manage and access the company's talent pool database

While the exact endpoints and operations aren't specified in detail, the Recruitee API appears to offer comprehensive access to manage the full recruitment lifecycle, from job posting to candidate management, as well as analytics capabilities. The API uses authentication via API tokens and has rate limits that need to be considered when integrating.