diff --git a/docs_eng/employer_negotiations.md b/docs_eng/employer_negotiations.md index f4dde210..8fe9438f 100644 --- a/docs_eng/employer_negotiations.md +++ b/docs_eng/employer_negotiations.md @@ -90,7 +90,7 @@ resumes. Employers do not need such access to work with an existing response/inv allows them to process responses to jobs even without access to the resume database. If you need to **take an action** with respect to a response/invitation, -please refer to the [list of actions](#actions-info) that will be available in the +please refer to the list of actions that will be available in the [list (collection) of responses/invitations](#negotiations-list) and in the [individual response/invitation](#get-negotiation). If the action changes the status of a response/invitation, it will be explicitly specified in the @@ -119,376 +119,7 @@ or [individual response/invitation](#get-negotiation) ## List of responses/invitation - -### Request - -Upon getting URL from the [collection list](#collections) send a GET request to -this URL, e.g.: - -``` -GET https://api.hh.ru/negotiations/somecollection?vacancy_id=123456 -``` - -Some parameters take multiple values: `key=value&key=value`. If a parameter can take multiple values, this is explicitly stated in its description. -Collection `phone_calls` accepts only parameters `vacancy_id`, `order_by`, `page` and `per_page` from the table below. - -Parameters: - -Name | Required | Description ---- | ------------ | -------- -vacancy_id| yes | Vacancy ID -order_by | no | Sorting option. Possible values may differ for different collections; the available options are specified in the [list of collections in the `order_types` field](#order-types). -page | no | Page number, default: 0 -per_page | no | Number of items per page: default value is 20; the maximum value is 50 -age_from | no | Applicant's age in years, range from -age_to | no | Applicant's age in years, range up to -area | no | Area. Multiple values can be specified. Possible values: [/areas](https://github.com/hhru/api/blob/master/docs/areas.md) -citizenship | no | Country of desired citizenship. Multiple values can be specified. Possible values can be found in the [country dictionary](https://api.hh.ru/openapi/en/redoc#tag/Public-directories/operation/get-countries) -currency | no | Currency code. Possible values: `currency` (key=code) from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries -driver_license_types | no | Driver license categories. Multiple values can be specified. Possible values: `driver_license_types` from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -educational_institution | no | ID of the [educational institution](https://github.com/hhru/api/blob/master/docs_eng/suggests.md). Multiple values can be specified -education_level | no | Education. Possible values: `education_level` from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -experience | no | Work experience. Multiple values can be specified. Possible values: `experience` from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -gender | no | Gender. Possible values: `gender` from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -language | no | Language skills. Multiple values can be specified. Set in the format language.level, where `language` is the value from the dictionary [/languages](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-languages), `level` is the value from the dictionary `language_level` [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -relocation | no | Ready to relocate. Possible values: `resume_search_relocation` from [/dictionaries](https://api.hh.ru/openapi/redoc#tag/Obshie-spravochniki/operation/get-dictionaries) -salary_from | no | Desired salary (range from) -salary_to | no | Desired salary (range up to) -search_radius_meters | no | Distance to a potential candidate (in meters) -search_text | no | Search string -show_only_new_responses | no | Show only new responses (these responses have not been viewed yet). Only for the "All unsorted" collection (`/response`) -show_only_with_vehicle | no | Filter by car availability -show_only_new | no | Shows responses that have new messages. For collections **other than** "All unsorted" (`/response`) - - -### Response - -Successful server response is returned with `200 OK` code and contains: - -```json -{ - "ordered_by": { - "id": "created_at", - "name": "by created date" - }, - "found": 12, - "pages": 1, - "page": 0, - "per_page": 20, - "items": [ - { - "id": "123456789", - "created_at": "2015-05-14T00:00:00+0300", - "updated_at": "2015-05-14T12:00:05+0300", - "has_updates": true, - "state": { - "id": "response", - "name": "Response" - }, - "employer_state": { - "id": "response", - "name": "Response" - }, - "actions": [ - { - "id": "invitation", - "name": "Invite", - "enabled": true, - "method": "PUT", - "url": "https://api.hh.ru/negotiations/somecollection/123456789", - "resulting_employer_state": { - "id": "invitation", - "name": "Invitation" - }, - "templates": [ - { - "id": "invite_after_response", - "name": "Invite responded applicant", - "quick": false, - "url": "https://api.hh.ru/message_templates/invite_after_response?topic_id=123456789" - } - ], - "arguments": [ - { - "id": "message", - "required": true, - "required_arguments": [] - }, - { - "id": "send_sms", - "required": false, - "required_arguments": [ - { - "id": "message" - } - ] - }, - { - "id": "address_id", - "required": false, - "required_arguments": [ - { - "id": "message" - } - ] - } - ] - }, - { - "id": "hold", - "name": "Think", - "enabled": true, - "method": "PUT", - "url": "https://api.hh.ru/negotiations/hold/123456789", - "arguments": [], - "resulting_employer_state": null, - "templates": [] - } - ], - "url": "https://api.hh.ru/negotiations/123456789", - "messages_url": "https://api.hh.ru/negotiations/123456789/messages", - "viewed_by_opponent": false, - "resume": { - "id": "0123456789abcdef", - "title": "Young specialist", - "url": "https://api.hh.ru/resumes/0123456789abcdef?topic_id=123456789", - "first_name": "Ivan", - "last_name": "Ivanov", - "middle_name": "Ivanovich", - "age": 19, - "can_view_full_info": true, - "alternate_url": "https://hh.ru/resume/0123456789abcdef?vacancyId=123456&t=123456789", - "created_at": "2015-02-06T12:00:00+0300", - "updated_at": "2015-04-20T16:24:15+0300", - "area": { - "id": "1", - "name": "Moscow", - "url": "https://api.hh.ru/areas/1" - }, - "certificate": [ - { - "achieved_at": "2015-01-01", - "owner": null, - "title": "test", - "type": "custom", - "url": "http://example.com/" - } - ], - "education": { - "primary": [ - { - "name": "Russian State Social University, Moscow", - "name_id": "39420", - "organization": "Faculty of Information Technology", - "organization_id": null, - "result": "", - "result_id": null, - "year": 2012 - } - ] - }, - "total_experience": { - "months": 118 - }, - "experience": [ - { - "position": "cattleman", - "start": "2010-01-01", - "end": null, - "company": "Horns and Hoofs", - "industries": [ - { - "id": "51.643", - "name": "Land and building improvement and cleaning" - }, - { - "id": "29.503", - "name": "Farming, crop growing, livestock farming" - } - ], - "company_url": "http://example.com/", - "area": { - "id": "1", - "name": "Moscow", - "url": "https://api.hh.ru/areas/1" - }, - "company_id": null, - "employer": null - }, - { - "start": "2005-01-01", - "end": "2009-03-01", - "company": "HeadHunter", - "area": { - "id": "1", - "name": "Moscow", - "url": "https://api.hh.ru/areas/1" - }, - "industries": [ - { - "id": "7.513", - "name": "Internet company (search engines, payment systems, social networks, educational and entertainment resources, website promotion, and more)" - } - ], - "company_url": "https://hh.ru", - "company_id": "1455", - "employer": { - "alternate_url": "https://hh.ru/employer/1455", - "id": "1455", - "logo_urls": { - "90": "https://hh.ru/employer/logo/1455" - }, - "name": "HeadHunter", - "url": "https://api.hh.ru/employers/1455" - } - } - ], - "gender": { - "id": "male", - "name": "Male" - }, - "salary": { - "amount": 1000000, - "currency": "RUR" - }, - "photo": { - "medium": "https://hh.ru/...", - "small": "https://hh.ru/...", - "id": "1337" - }, - "owner": { - "id": "123456", - "comments": { - "url": "https://api.hh.ru/applicant_comments/123456", - "counters": { - "total": 7 - } - } - }, - "negotiations_history": { - "url": "https://api.hh.ru/resumes/0123456789abcdef/negotiations_history" - }, - "download": { - "pdf": { - "url": "https://hh.ru/api_resume_converter/0123456789abcdef/IvanovIvanIvanovich.pdf?type=pdf" - }, - "rtf": { - "url": "https://hh.ru/api_resume_converter/0123456789abcdef/IvanovIvanIvanovich.rtf?type=rtf" - } - } - }, - "templates": [ - { - "url": "https://api.hh.ru/message_templates/discard_after_interview?topic_id=123456789", - "id": "discard_after_interview" - } - ], - "counters": { - "messages": 100, - "unread_messages": 50 - }, - "source": "NEGOTIATION", - "test_result": { - "url": "https://api.hh.ru/negotiations/1359970704/test/solution", - "alternate_url": "https://hh.ru/employer/vacancy_response/test?topicId=1359970704", - "score": 100, - "mark": "EXCELLENT" - } - } - ] -} -``` - -where: - -Name | Type | Description ---- | --- | -------- -ordered_by | object | Enabled sorting option -found | number | Number of responses found ( ≥ 0 ) -pages | number | Number of pages with responses ( ≥ 1 ) -per_page | number | Number of elements per page ( > 0 ) -page | number | Number of the current page ( ≥ 0 ) - - -The `items` entity contains response/invitation data and CVs for them: - -Name | Type | Description -------------------------------- | ------------- | -------- -id | string | Response ID -created_at | string | Response/invitation creation date and time -updated_at | string | Response/invitation update date and time -state | object | The current [applicant's response status](#term-state). -employer_state | object | The current [employer's response status](#term-employer-state). -actions | list | list of possible [actions on response/invitation](#actions-info) -url | string | URL to get [the full version of response/invitation](#get-negotiation) -messages_url | string | URL to get [the list of messages in the response](#get-messages) -resume | object, null | Short CV. To get full CV, send a GET request to URL from key `url`. It can be `null`, if the applicant deleted the CV or disabled access to it. -has_updates | logical | Whether the response/invitation includes updates that require attention. The flag can be disabled upon different response/invitation actions, e.g. upon [viewing message list](#get-messages), and [appropriate view of CV on response/invitation](#view-resume). -viewed_by_opponent | logical | Whether the response was viewed by the applicant -counters | object | Counters -counters.messages | number | Total number of messages -counters.unread_messages | number | Number of messages that have not been read by the employer -test_result | object, null | [Test](https://api.hh.ru/openapi/en/redoc#tag/Employer-responsesinvitations/operation/get-negotiation-test-results)'s result -test_result.url | string | Full test's result link -test_result.alternate_url | string | Full test's result site link -test_result.score | number | Test's score -test_result.mark | string | Test's mark (`UNFAIR` - from 0 to 14 points, `FAIR` - from 15 to 44 points, `GOOD` - from 45 to 79 points, `EXCELLENT` from 80 to 100 points) -source | string | Response source. Available values are NEGOTIATION, PHONE_CALL, CHAT, VR, AUTO_INVITE. - - - -The list of responses/invitations contains only basic CV info. -To get full info, such as applicant contact details, -request the full CV. The applicant will see this CV request in -view history. - -**Important!** Additional request on CV data **should be** -sent to URL from JSON response. This is the only option -to correctly process the request in view history. E.g, if the CV is requested from the response -to anonymous vacancy, the history will display anonymous name of the company. - -### Errors - -* `400 Bad Request` – error in the request parameters -* `404 Not Found` - if the vacancy of requested responses doesn't exist or -not available to the current user - - -### Response/invitation actions (`actions`) - -The number of actions may differ, and the list of actions may be empty. - -The following parameters are specified for each action: - -Name | Type | Description ---- | --- | -------- -id | string | Action ID -name | string | Action name -enabled | logical | Whether the action is possible -method | string | HTTP method to perform -url | string | URL to send the request to -resulting_employer_state | object, null | [employer's response/invitation status](#term-employer-state) to be assigned after the action is performed. If the action does not change the state, the value is "null". -templates | list | Email templates. Contains the template ID and URL for [getting the text for the template](https://api.hh.ru/openapi/en/redoc#tag/Employer-responsesinvitations/operation/get-mail-templates). -arguments | list | Mandatory and additional arguments for the request - -There is a list of arguments for the action; at this point, you may encounter the following arguments: - -* `message` – the message that will be sent to the applicant's email. Use [templates](https://api.hh.ru/openapi/en/redoc#tag/Employer-responsesinvitations/operation/get-mail-templates) to obtain texts. -* `address_id` – [address](https://api.hh.ru/openapi/en/redoc#tag/Employer-addresses) ID that will be specified in the invitation -* `send_sms` – whether to notify the applicant of the invitation via SMS. To initiate the sending of a message, pass "true"; the default is "false". Note: a template text is used in sms message, this text is not customizable. - -The application should be able to fill in these arguments. Other arguments may be added in the future; -however, they will not be mandatory. The list of mandatory arguments -can be different for different responses/invitations. - -The following parameters will be specified for each argument: - -Name | Type | Description ---- | --- | -------- -id | string | Argument ID -required | logical | Whether the argument is mandatory -required_arguments | list | Arguments that must also be passed if this argument is specified. For example, the address is optional, but you must also specify a message when you pass the address. - +>!! Method is defined in [OpenAPI](https://api.hh.ru/openapi/en/redoc#tag/Employer-responsesinvitations/operation/get-collection-negotiations-list) ## View the response/invitation