Match
Match a Candidate, Organization and Role. The match with tell you how well a candidate fits in and performs at the organization and role. There are multiple match types that you can request for.
Match types
- tiny - This is a simple match that will show if the match is below average or not.
- small - This is the standard match. It will show candidate grade.
- medium - In addition to a small match, we also show all test scores.
- large - In addition to medium we will also show text feedback. When using large match you may want to pass a language query parameter.
Candidate match
Get match for a candidate. The JSON keys shown in the examples below will always be defined but their values might be null. See response syntax for more information.
Request
GET /api/candidates/[candidate_id]/match?role=[role_id]&type=small
Host: api.happyrmatch.com
Authorization: Bearer eyJ0eXAi1QiLCJ...
Accept: application/vnd.api+jsonResponses
A response to a tiny request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": {
"type": "candidate-match",
"id": "f51f80f6-1887-43b9-9fb3-63037d6f421a",
"attributes": {
"match": true
}
}
}A response to a small request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": {
"type": "candidate-match",
"id": "bcfc8f98-7d86-4da4-a5f2-a94347fde8f7",
"attributes": {
"match": true,
"confidence": "medium",
"grade": 3
}
}
}A response to a medium request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": {
"type": "candidate-match",
"id": "2bfed39b-c5a6-4f12-8c16-bd1d7f17bc8a",
"attributes": {
"match": true,
"confidence": "medium",
"grade": 3,
"result_culture": 78,
"dimension_score": [
{
"code": "dimension_a",
"score": 95,
"name": "Dimension A",
"description": "A description what this dimension really means."
},
{
"code": "dimension_b",
"score": 50,
"name": "Dimension B",
"description": "A description what this dimension really means."
}
],
"tests": [
{
"report_url": "https:\/\/api.happyrmatch.com\/report\/result\/d9315133-409d-4b95-90c6-be1dd382961d-d1578f5-sv.pdf",
"test_type": "75949d36-41eb-418d-b1a9-8349a6c277eb",
"display_name": "Dream Candidate Match",
"test_result": 87,
"dimensions": [
"dimension_a",
"dimension_b"
],
"status": "completed"
}
]
}
}
}Request for large match
GET /api/candidates/[candidate_id]/match?role=[role_id]&type=large&language=sv
Host: api.happyrmatch.com
Authorization: Bearer eyJ0eXAi1QiLCJ...
Accept: application/vnd.api+jsonSupported languages are: sv, en, da, no and ru.
Response for large match
A response to a large request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": {
"type": "candidate-match",
"id": "74658c50-fdaa-4cee-9bee-2ca84e983ee7",
"attributes": {
"match": true,
"confidence": "medium",
"grade": 3,
"result_culture": 78,
"dimension_score": [
{
"code": "dimension_a",
"score": 95,
"name": "Dimension A",
"description": "A description what this dimension really means."
},
{
"code": "dimension_b",
"score": 72,
"name": "Dimension B",
"description": "A description what this dimension really means."
}
],
"tests": [
{
"report_url": "https:\/\/api.happyrmatch.com\/report\/result\/0d8c7df1-0b5b-40f0-8dad-d71a69312c97-d1578f5-sv.pdf",
"test_type": "988a82fd-7556-41e9-b83a-38c6abf2ddff",
"display_name": "Dream Candidate Match",
"test_result": 87,
"dimensions": [
"dimension_a",
"dimension_b"
],
"status": "completed"
}
],
"text": {
"dimension_a": {
"result_description": {
"employer": "Text feedback on the result that could be shown to a recruiter",
"candidate": "Text feedback on the result that could be shown to a candidate"
},
"employer_statements": [
"Candidate might have X behavior",
"They might act like that"
],
"interview_questions": [
"Questions that are good to use for in an interview."
]
},
"dimension_b": {
"result_description": {
"employer": "Text feedback on the result that could be shown to a recruiter",
"candidate": "Text feedback on the result that could be shown to a candidate"
},
"employer_statements": [
"Candidate might have X behavior",
"They might act like that"
],
"interview_questions": [
"Questions that are good to use for in an interview."
]
}
}
}
}
}Response syntax
Here is an overview of the data types of the Match response object. The JSON keys are described under each match type.
Test credits
When a test result is displayed for the first time the credits for that test type are reduced. If there were not enough credits then the test will not have all fields available and status will be pending_payment. If a match has only one test and its status is pending_payment then the following properties of that match will be null/empty:
- match
- result_culture
- dimension_score
- text
{
"data": {
"type": "string",
"id": "string",
"attributes": {
"match": "bool|null",
"confidence": "string",
"grade": "int [-3 - 5]",
"result_culture": "int [0 - 100]|null",
"dimension_score": [
{
"code": "string",
"score": "int",
"name": "string|null",
"description": "string|null"
}
],
"text": {
"dimension_a": {
"result_description": {
"employer": "string|null",
"candidate": "string|null"
},
"employer_statements": "array of zero or more strings",
"interview_questions": "array of zero or more strings",
}
},
"tests": [
{
"report_url": "string|null",
"test_type": "string",
"display_name": "string",
"test_result": "int [0 - 100]|null",
"dimensions": [
"dimension_a"
],
"status": "string [completed|pending|pending_payment]",
"missing_payment": "boolean"
}
]
}
}
}
Group match
Get match for a group of candidates.
Request
GET /api/groups/[group_id]/match?role=[role_id]&type=small
Host: api.happyrmatch.com
Authorization: Bearer eyJ0eXAi1QiLCJ...
Accept: application/vnd.api+jsonResponse
A response to a small request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": [
{
"type": "candidate-match",
"id": "3ad00e65-107a-4539-8eb4-75866fc62a19",
"attributes": {
"match": true,
"confidence": "medium",
"grade": 3
}
},
{
"type": "candidate-match",
"id": "e58fe6f2-04b4-491b-9f37-76696ac35f9f",
"attributes": {
"match": true,
"confidence": "medium",
"grade": 3
}
}
]
}Group match filter
You may filter a group depending on their match. When a filter reduces a group you will get a new group id. This is the only time you get to see this id, so store it safely in case you wish to do filtering or sorting on this new subgroup.
Filter types
- top-X - Returns the top X candidates. The candidates are sorted alphabetically. Supported values for X are: 5, 10, 15, 30, 50, 100
- sort - Sort candidates on their match. Highest match first.
- grade-2-or-higher - Get candidates with grade 2 or higher. The candidates are sorted alphabetically.
- grade-3-or-higher - See above.
- grade-4-or-higher - See above.
Request
GET /api/groups/[group_id]/match/filter?role=[role_id]&type=top-5
Host: api.happyrmatch.com
Authorization: Bearer eyJ0eXAi1QiLCJ...
Accept: application/vnd.api+jsonResponse
A response to a small request:
HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type: application/vnd.api+json
Date: Wed, 14 Sep 2022 05:38:55 GMT
{
"data": {
"type": "group-match-filtered",
"id": "795053b4-33ee-4dbd-ab79-fbbb5c301124",
"attributes": {
"candidates": [
"05d9bdd1-cbf5-4851-b496-195f81fc8f0d",
"1b11dc4d-5194-485c-988d-29a1c2b113a4",
"36cf45f2-035b-449a-bbaa-2a3ce485c0bb",
"6a7b1acd-07c4-43db-a158-8f241fa5942b",
"ede40a28-a8ef-4955-a0c3-6065b9475deb"
]
},
"relationships": {
"group-created": {
"data": {
"type": "group",
"id": "5ac867b0-996a-4f3d-9b18-2e861e6aa3da"
}
}
}
},
"included": [
{
"type": "group",
"id": "5ac867b0-996a-4f3d-9b18-2e861e6aa3da",
"attributes": []
}
]
}Grade
The grade shows of how good the match is between the candidate, role and organization. It is an integer between 1 and 5. A grade of 2 means that it is an average match.
Exceptions
There are two reasons why a candidate did not get a match. They will represent a grade if the following values:
- Grade: 0 - Candidate has not done the recommended tests.
- Grade: -1 - The machine learning algorithm has not learned about this combination of role, candidate and organization. This is rare but a match cannot be computed at this point.
- Grade: -2 - Temporary issue
- Grade: -3 - If the results can't be shown because all the tests are missing payment