Find

Find more candidates to apply for a Role.

Create

Create a request for more candidates.

Request

POST /api/find
Host:          api.happyrmatch.com
Authorization: Bearer eyJ0eXAi1QiLCJ...
Accept:        application/vnd.api+json
Content-Type:  application/vnd.api+json

{
    "role": "[role_id]",
    "type": "[find_type_id]",
    "callback_url": "https:\/\/my-app.com\/advert\/123\/webhook",
    "nonce": "[nonce]"
}

The callback_url is where we POST candidates to at a later time. nonce is an optional random string that will be used to check webhook signature.

There are two special prefixes to the callback_url. They are:

• If the callback_url starts with "mailto:" and then contains an email, we will send the candidate's data to that email.
• If the callback_url starts with "notify:" we will ask the candidate to complete a process on that URL.

Response

HTTP/1.0 202 Accepted
Cache-Control: no-cache, private
Content-Type:  application/vnd.api+json
Date:          Wed, 14 Sep 2022 05:38:55 GMT

{
    "meta": {
        "message": "Accepted"
    }
}

Callback

If the callback_url is an URL, then we will send a POST request to that URL when we found a candidate. The request contains a signature header which can be used to verify the if it is a valid request from HappyrMatch.

POST [callback_url]
Content-Type:            application/json
X-HappyrMatch-Signature: abc123

{
    "id": "a7b43191-39af-48ae-ab2c-5b23a6c1eb8a",
    "email": "foobar@example.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "phone_number": "+46 070-123 123 12",
    "resume_url": "https:\/\/storage.com\/resume.pdf",
    "timestamp": 1590933525
}

Use the following algorithm to verify the request.

$nonce = 'nonce-sent-with-find-request';
$clientSecret = 'api-client-secret';

$signature = $httpRequest->getHeader('X-HappyrMatch-Signature');
$body = $httpRequest->getBody();

if ($signature === sha1($body . hash_hmac('sha1', $nonce, $apiSecret))) {
    echo "Signature is valid";
}