A short story about our custom recruiting service and a big story about the problems that appeared when integrating with HeadHunter in terms of posting vacancies. Why HeadHunter? Because on Superjob, everything is somewhat simpler (but this is not accurate).

Background

My team is developing a web-based job placement application for one major retail chain. The chain of actions is constructed in this way:

1. the business approves the basic vacancy templates (requirements, responsibilities, conditions), universal for all stores and cities;
2. HRs, on the basis of the basic template, create the main vacancy template for each city, indicating the salary range for a particular position (for the same positions in different regions there may be different salaries);
3. the store director, on the basis of the vacancy template, opens a vacancy in his store inside our application and receives a link to it;
4. the candidate, following the link, gets to the questionnaire, where he enters contact information and sends it to the store director for consideration;
5. ??????
6. PROFIT!

When there was a proposal to publish a vacancy on HeadHunter with a link to the questionnaire, I briefly studied the documentation for their API and thought something in the style of "there is a business for 5 minutes." And now, after ~ 1.5 months, I am writing this article.

Working with the HeadHunter API

So, there is the task of publishing vacancies on HeadHunter, you will need:

Current API Version

Unfortunately (or fortunately?), The API is not versioned, so, theoretically , anything can fall off at any time. Even if this has never happened and there are no prerequisites for this, it is still updated:

You can find keys in the answers and API parameters that are not described in the documentation. This usually means that they are left for compatibility with older versions. Their use is not recommended.

Application Registration

Everything is simple here, but not as simple as we would like. It will be proposed to fill out a form where one of the fields contains the wording " Describe all the functionality of the application and indicate the API methods used ." How detailed ???

When registering the application for the first time, the form was filled out in detail, indicating all the routes, the second time there was enough patience only for the phrase “ all methods from the vacancy block ”. Both options passed.

The application is approved for about two weeks. This is one of the reasons our integration has dragged on a bit.

Registration of the second application

Note the Redirect URI parameter when registering the application. According to our observation, confirmed by HeadHunter technical support, if your test circuit is on a subdomain (for example, test.example.com), then you need an application for sale (with redirect_uri = example.com) and for development (with redirect_uri = test.example.com ) And this is another two weeks of waiting for approval.

Learning and clarifying the rules

While we were developing the functional and published closed vacancies in test mode, everything was fine. Having rolled out open vacancies to the publication of publications, links were found to disappear due to the prohibition by the rules of their placement in vacancies, but, from words of support, links can be automatically sent to the PM in response (which is not described in the rules). Here we were let down by our own carelessness, however, in my opinion, it was possible to put a validator at the stage of receiving the vacancy text.

A bit of intuition

Sometimes error texts are completely unpredictable and illogical. This is what we are faced with:

• not_enough_purchased_services
  
  
  
  (purchased services for publishing or updating this type of vacancy are not enough) - when publishing a vacancy with the type free . What exactly needs to be bought for free vacancies is not clear. Solution: specify type: standard
  
  
  
  ;
• quota_exceeded
  
  
  
  (manager’s quota for publishing this type of vacancy has ended) - manager quotas are configured through https://hh.ru/employer/settings/quotas , the last time we saw it when typing standart
  
  
  
  instead of standard
  
  
  
  in the type
  
  
  
  field;
• duplicate
  
  
  
  (a similar vacancy has already been published) when using the ignore_duplicates
  
  
  
  flag - occurs when the name
  
  
  
  and area
  
  
  
  fields are the same, regardless of the presence of the flag to ignore duplicates.

And

About security

Take into account the fact that the life of the token is two weeks (this is their favorite term, apparently) and you cannot refresh it ahead of time, only by razlogin. Theoretically, this should not cause problems, however, if the token leaks, then the attacker may have enough time for meditation, atrocities and gloating.

About interfaces

Job description - this is one description



field that supports several HTML tags that can be seen in their visual editor on the site. We chose a job format from three text fields: responsibilities, requirements, conditions, and for HeadHunter we simply combine them by inserting h3



with the field name as a separator.

About reference books

Like the entire API, directories can change at any time, as explicitly stated in their descriptions:

Errors are still possible, for example, in the directory of regions found excess spaces that you may not be ready for. I started a review on this topic, I hope that they will fix it, but be careful.

---

Summary

A quick start will take you about two weeks, probably with the need to register several applications. In general, the documentation and the API itself are quite sane, otherwise you can figure out how to communicate with tech support or through issue on their github.

I’m sure that we didn’t find all the interesting things related to the HeadHunter API, because we didn’t even touch the resume branch. Therefore, if you have something to tell / supplement / clarify - write in the comments.