HeadHunter API

The Employer Managers API allows you to manage the users who have access to an employer's account.

Authentication Requirement: To access these endpoints, you must be authorized as the employer. If the user is not authorized or is incorrectly authorized, the API will return a 403 Forbidden error.

The HeadHunter API allows you to integrate HeadHunter (hh.ru) functionality into your own products.

To begin using the API, you should:

1. Review the General Information regarding API operation.
2. Check the FAQ for common questions.
3. Adhere to the requirements for logo usage and application naming.

For methods requiring user or application authorization, you must register your application at https://dev.hh.ru and configure the authorization process. Registered applications can request permission to access a user's personal data without ever handling or storing the user's hh.ru login or password.

Call history information is available within the candidate's list of responses (get_negotiations) and when viewing a specific response or invitation (get_negotiation).

The call history object contains a summary flag and an array of individual call items.

{
    "picked_up_phone_by_opponent": true,
    "items": [
      {
        "id": 123,
        "status": "call_in_progress",
        "creation_time": "2022-03-04T19:39:58+0300",
        "last_change_time": null,
        "duration_seconds": null
      }
    ]
}

Assessment tools are tests or questionnaires designed for candidates to complete. Information about these tools is typically included in messages sent between an employer and a candidate within the context of job applications or invitations.

Note for Employers: Using assessment tools requires paid access.

Most requests to the HeadHunter API require an access_token for authorization. The API implements the OAuth 2.0 protocol.

There are two primary authorization levels supported:

1. Application Authorization: For accessing application-level data.
2. User Authorization: For requesting permission to access a specific user's personal data without handling their login or password.

Important: You must use the hh.ru domain for authorization; the m.hh.ru domain is no longer supported.

In addition to Etag-based validation, the API provides Cache-Control and Expires headers in responses. These headers allow clients to cache a response and use it locally until the specified expiration time without needing to contact the server.

• Cache-Control: max-age=N: Indicates the maximum amount of time (in seconds) the response is considered fresh.
• Expires: Provides a specific timestamp after which the response is considered stale.

Caching support can be identified by the presence of an Etag header in the response, which is common in most dictionary endpoints.

A candidate's response is considered 'read' by the employer if any of the following occur:

• The employer requests the message list using the URL provided in the negotiations list or the individual negotiation object.
• The employer requests the messages specifically for that response via get messages.
• The employer requests the candidate's resume using the URL provided in the negotiations list or the individual negotiation object.
• The employer explicitly uses the mark specific responses as read method.

The HeadHunter API uses specific badges to indicate the authorization level required for a given endpoint. When consuming the API, check these badges to ensure your request includes the correct credentials:

• Anonymous (anon): No authorization required.
• Client (client): Requires application-level authorization (see docs/authorization_for_application.md).
• Applicant (app): Requires user-level authorization for a job seeker (see docs/authorization_for_user.md).
• Employer (emp): Requires user-level authorization for an employer/manager (see docs/authorization_for_user.md).