Skip to content

Commit

Permalink
Moved list of responses/invitation to OpenAPI
Browse files Browse the repository at this point in the history
  • Loading branch information
@DaniilIdrisov
DaniilIdrisov committed Apr 18, 2024
1 parent 947500f commit 1a09c5b
Showing 1 changed file with 2 additions and 371 deletions.
373 changes: 2 additions & 371 deletions docs_eng/employer_negotiations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -119,376 +119,7 @@ or [individual response/invitation](#get-negotiation)
<a name="negotiations-list"></a>
## 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 )

<a name="negotiations-list-item"></a>
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 | <a name="has_updates"></a> 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.

<a name="view-resume"></a>

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

<a name="actions-info"></a>
### 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](
<a name="get-negotiation"></a>
## View the response/invitation
Expand Down

0 comments on commit 1a09c5b

Please sign in to comment.