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+json

Responses

A response to a tiny request:

HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type:  application/vnd.api+json
Date:          Wed, 13 Oct 2021 04:26:34 GMT

{
    "data": {
        "type": "candidate-match",
        "id": "f662e979-6925-46db-ac69-c11658be1de1",
        "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, 13 Oct 2021 04:26:34 GMT

{
    "data": {
        "type": "candidate-match",
        "id": "dd6a1a7a-ed67-4585-942d-e3ac3f0d4c9a",
        "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, 13 Oct 2021 04:26:34 GMT

{
    "data": {
        "type": "candidate-match",
        "id": "67f2c084-bf52-4c1e-9b91-530a67d8e980",
        "attributes": {
            "match": true,
            "confidence": "medium",
            "grade": 3,
            "result_culture": 78,
            "dimension_score": [
                {
                    "code": "dimension_a",
                    "score": 75,
                    "name": "Dimension A",
                    "description": "A description what this dimension really means."
                },
                {
                    "code": "dimension_b",
                    "score": 57,
                    "name": "Dimension B",
                    "description": "A description what this dimension really means."
                }
            ],
            "tests": [
                {
                    "report_url": "https:\/\/api.happyrmatch.com\/report\/result\/44c3ef2b-6f2e-4a0c-96bc-baf3dee31bfe-d1578f5-sv.pdf",
                    "test_type": "d8d139a3-e710-4973-a9fc-e5b26685957b",
                    "display_name": "Dream Candidate Match",
                    "test_result": 87,
                    "dimensions": [
                        "dimension_a",
                        "dimension_b"
                    ]
                }
            ]
        }
    }
}

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+json

Supported 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, 13 Oct 2021 04:26:34 GMT

{
    "data": {
        "type": "candidate-match",
        "id": "0fc119fd-3578-40bc-aaa4-f9b0e1e6869e",
        "attributes": {
            "match": true,
            "confidence": "medium",
            "grade": 3,
            "result_culture": 78,
            "dimension_score": [
                {
                    "code": "dimension_a",
                    "score": 62,
                    "name": "Dimension A",
                    "description": "A description what this dimension really means."
                },
                {
                    "code": "dimension_b",
                    "score": 76,
                    "name": "Dimension B",
                    "description": "A description what this dimension really means."
                }
            ],
            "tests": [
                {
                    "report_url": "https:\/\/api.happyrmatch.com\/report\/result\/cddd22b5-6404-42af-b907-86f0b8bffd1b-d1578f5-sv.pdf",
                    "test_type": "4523d9c9-ab2d-480a-a8d6-e9752258e352",
                    "display_name": "Dream Candidate Match",
                    "test_result": 87,
                    "dimensions": [
                        "dimension_a",
                        "dimension_b"
                    ]
                }
            ],
            "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.

{
    "data": {
        "type": "string",
        "id": "string",
        "attributes": {
            "match": "bool|null",
            "confidence": "string",
            "grade": "int [-2 - 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",
                    "test_type": "string",
                    "display_name": "string",
                    "test_result": "int [0 - 100]|null",
                    "dimensions": [
                        "dimension_a"
                    ]
                }
            ]
        }
    }
}

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+json

Response

A response to a small request:

HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type:  application/vnd.api+json
Date:          Wed, 13 Oct 2021 04:26:34 GMT

{
    "data": [
        {
            "type": "candidate-match",
            "id": "85b5a7ab-0257-4dae-a5ea-bff5d4935240",
            "attributes": {
                "match": true,
                "confidence": "medium",
                "grade": 3
            }
        },
        {
            "type": "candidate-match",
            "id": "3bd61190-3c5a-4119-ac6c-39fba589d121",
            "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+json

Response

A response to a small request:

HTTP/1.0 200 OK
Cache-Control: no-cache, private
Content-Type:  application/vnd.api+json
Date:          Wed, 13 Oct 2021 04:26:34 GMT

{
    "data": {
        "type": "group-match-filtered",
        "id": "c2845ee2-7677-4f24-b145-0f992c3ac01c",
        "attributes": {
            "candidates": [
                "28b17818-ccbf-4b8e-b013-f9a1b0c89af2",
                "2cbf7ba9-1ac9-4924-b0da-9f470d8638ca",
                "76644941-5a3a-4ce4-8312-92e5e537620e",
                "bdfb8951-9c20-4504-8b4c-7ca4aa714c77",
                "eace04ab-0009-450b-891b-e2feacda16f0"
            ]
        },
        "relationships": {
            "group-created": {
                "data": {
                    "type": "group",
                    "id": "4b6be620-3c39-428c-b7f8-8022ac393a5e"
                }
            }
        }
    },
    "included": [
        {
            "type": "group",
            "id": "4b6be620-3c39-428c-b7f8-8022ac393a5e",
            "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