The Happo Developer Hub

Welcome to the Happo developer hub. You'll find comprehensive guides and documentation to help you start working with Happo APIs as quickly as possible, as well as support if you get stuck. Let's jump right in!

    
 

The Happo API is the main way to get data in and out of the Happo platform. It lets you connect external sources directly into your Happo account, allowing you to add, update, and delete items.

To get full access to the Happo API, contact our team at support@happo.com to request a key.

Suggest Edits

List of APIs

 

API Base URL Production : https://api.happo.com/v1

API Base URL Test Environment : https://api-staging.happo.com/v1

Below is the list of all APIs

HTTP Method
URL
Description

GET

/positions

List all positions

GET

/positions/{position_id}

View position details

POST

/positions

Create a new position

POST

/positions/{position_id}

Update an existing position

GET

/positions/{position_id}/candidates

List all the candidates related to the position

GET

/positions/{position_id}/candidates/{candidate_id}

View the candidate details

POST

/positions/{position_id}/candidates

Create a new candidate for the position

POST

/positions/{position_id}/candidates/bulk

Create multiple candidates for the position.

POST

/positions/{position_id}/candidates/{candidate_id}

Update an existing candidate

POST

/attachments

Upload an attachment.

GET

/attachments/{attachment_id}

View an attachment.

 

Major Version

Version v1 specified in the base URL https://api.happo.com/v1 is current major version of API.
Version v2 if released in the future may be completely different and incompatible with v1

Minor Version

Currently v20180701 is stable available version.

We will try to keep minor version upgrades compatible with previous versions.
In unavoidable circumstances, incompatibility information will be mentioned here.

You need to specify the minor version in http header x-happo-api-version

curl https://api.happo.com/v1/positions \
-H "x-happo-api-version:v20180701"
Suggest Edits

Authentication

 

Authenticate your account by including your secret key in API requests.
Your API keys carry many privileges, so make sure you keep them secure!

Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth.
Provide your API key in Authorization Header

curl https://api.happo.com/v1/positions \
-H "Authorization:Bearer <your_api_secret_key>" 
Suggest Edits

Request Headers

 

Every API request must have following headers in HTTP request

Header
Value
Description

Authorization

Bearer <your_api_secret_key>

User will be identified and authenticated based on valid secret key provided here

x-happo-api-version

v20180701

Specify API version to use

Content-Type

multipart/form-data: for Uploading Attachment
application/json: for other APIs

curl https://api.happo.com/v1/positions \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H 'Content-Type: application/json'
Suggest Edits

Response Object

 

All APIs have content-type application/json; charset=utf-8 in response header

Response object has following structure.

Attribute
Type
Contents
Description

statusCode

Integer

200: Successful API Response
4XX: Validation Errors
5XX: Processing Errors

HTTP Status code representing if API call was successful or failed

success

Boolean

true on Successful API Response

Not present on Error response

Boolean representing API request was successful or not

error

String

Present only if statusCode is not 200

Short message representing type of HTTP error

message

String

Present only if statusCode is not 200

Detailed error message

data

JSON Object

Present only if statusCode is 200

Actual API response data in JSON format

{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "1ac435ee-9b11-4172-a934-3272b365e718",
        "title": "Software Enginner",
        "location": "Stockholm",
        "notes": "<div>Test Note</div>",
        "type": "part-time",
        "adPostingLink": "https://linkedin.com/positions/1234",
        "targetDate": "2018-06-25T00:00:00.000Z",
        "status": "open",
        "noOfPositions": 5,
        "collaborators": [
            {
                "email": "john@happo.com",
                "userId": "83fadf49-5645-498c-a6a8-e64725ac83e6",
                "type": "admin"
            },
            {
                "email": "tara@aw.se",
                "userId": "65d15bf6-4991-4cd0-9c72-280e83de2fb9",
                "type": "client"
            }
        ]
    }
}
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "type must be one of [full-time, part-time]"
}
Suggest Edits

Positions

 

Job positions in Happo can be managed by positions APIs.

You can:

  • Create and update a position
  • Get a list of all positions available to you
  • View details of a specific position
Suggest Edits

Position Object

 

Position object contains following fields

Attribute
Nested Attribute
Type
Always Present
Contents
Description

id

-

String

YES

-

UUID based unique identifier of the job

title

-

String

YES

-

Position title

location

-

String

NO

-

Location of the job position

notes

-

String

NO

Text can contain following html tags for formatting.

b, i, em, strong, a, p, div, ol, li, ul.

Instructions, job description, requirement profile or other information to related to job position

type

-

String

NO

Can be one of
full-time
part-time

Position type

adPostingLink

-

String

NO

-

Link to the job position ad posted online

targetDate

-

Date

NO

-

Date when position has to be filled

status

-

String

NO

Can be one of
draft
open
closed

Position status

collaborators

Array

NO

-

List of collaborators

userId

String

YES

-

Unique user ID of collaborator

email

String

YES

-

Email ID of collaborator

type

String

YES

Can be one of
admin
client
supplier

Type of collaborator

status

String

YES

Can be one of
awaiting_registration
awaiting_approval
declined
accepted

Invitation status of the collaborator

attachmentIds

-

Array of Strings

NO

Contains array of attachment IDs attached to this position.

Refer Uploading Attachment for generating attachment id.

Refer View Attachment for attachment details.

createdBy

String

YES

Job creator's user ID

createdAt

Date

YES

Time stamp when position was created

updatedAt

Date

YES

Time stamp when position was updated

{
    "id": "1ac435ee-9b11-4172-a934-3272b365e718",
    "title": "Software Enginner",
    "location": "Stockholm",
    "notes": "<div>Test Note</div>",
    "type": "full-time",
    "adPostingLink": "https://linkedin.com/positions/1234",
    "targetDate": "2018-06-25T00:00:00.000Z",
    "status": "open",
    "noOfPositions": 5,
    "collaborators": [
        {
            "email": "john@happo.com",
            "userId": "83fadf49-5645-498c-a6a8-e64725ac83e6",
            "type": "admin",
            "status": "accepted"
        },
        {
            "email": "tara@aw.se",
            "userId": "65d15bf6-4991-4cd0-9c72-280e83de2fb9",
            "type": "client",
            "status": "awaiting_approval"
        }
    ],
    "attachmentIds": [
        "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
        "16880903-3496-4e0b-853b-af8cd4dcb3b2"
    ],
    "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
    "createdAt": "2018-07-05T09:57:09.244Z",
    "updatedAt": "2018-07-06T07:16:16.667Z"
}
Suggest Edits

Create/Update Position

 

Position can be created by POST method to /positions.

and can be updated by POST method to /positions/{position_id}.

Slug Parameters

Name
Type
Description

position_id

String(Optional)

Position ID.
If passed existing position will be updated, otherwise new position will be created

Request Payload

Note: Any optional field can be deleted by posting null value in update request payload

Attribute
Nested Attribute
Type
Required
Validations
Description

title

-

String

YES

-

Position title

location

-

String

NO

-

Location of the job position

notes

-

String

NO

Text can contain following html tags for formatting.

b, i, em, strong, a, p, div, ol, li, ul.

Other html tags will be removed while saving.

Instructions, job description, requirement profile or other information to related to job position

type

-

String

NO

Can be one of
full-time
part-time

Position type

adPostingLink

-

String

NO

-

Link to the job position ad posted online

targetDate

-

Date

NO

-

Date when position has to be filled

collaborators

-

Array

NO

-

List of collaborators

email

String

YES

-

Email ID of collaborator

type

String

YES

Can be one of
admin
client
supplier

Type of collaborator

attachmentIds

-

Array of Strings

NO

Contains array of attachment IDs attached to this position.

Refer Uploading Attachment for generating attachment id.

Response

Returns Position Object.

curl https://api.happo.com/v1/positions \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json" -d \
'{
    "title":"Software Tester",
    "location":"Malmo",
    "targetDate":"2018-09-25",
    "type":"part-time",
    "noOfPositions":"2",
    "adPostingLink":"https://moster.com/positions/1234",
    "notes":"<div><b>Job Description</b></div><ul><li>Testing</li><li>Automation</li></ul>",
    "attachmentIds": [
        "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
        "16880903-3496-4e0b-853b-af8cd4dcb3b2"
    ],
    "collaborators":[
        {
            "email":"dave@happo.com",
            "type":"admin"
        },
        {
            "email":"neo@test.se",
            "type":"supplier"
        }
    ]
}'
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "5e03d22d-e6b4-4d02-9344-a338295215de",
        "title": "Software Tester",
        "location": "Malmo",
        "notes": "<div><b>Job Description</b></div><ul><li>Testing</li><li>Automation</li></ul>",
        "type": "part-time",
        "adPostingLink": "https://moster.com/positions/1234",
        "targetDate": "2018-09-25T00:00:00.000Z",
        "status": "draft",
        "noOfPositions": 2,
        "attachmentIds": [
            "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
            "16880903-3496-4e0b-853b-af8cd4dcb3b2"
        ],
        "collaborators": [
            {
                "email": "dave@happo.com",
                "userId": "95f7bca5-e8c6-4dc9-88db-cf5d18b4fdf6",
                "type": "admin",
                "status": "awaiting_approval"
            },
            {
                "email": "neo@test.se",
                "userId": "83a8c457-7571-440c-b4d4-756d43094a2e",
                "type": "supplier"
                "status": "awaiting_registration"
            }
        ],
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-06T07:17:35.972Z",
        "updatedAt": "2018-07-06T07:17:35.972Z"
    }
}
curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718 \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json" -d \
'{
    "title":"Software Enginner",
    "location":"Stockholm",
    "targetDate":"2018-06-25",
    "type":"part-time",
    "noOfPositions":"5",
    "adPostingLink":"https://linkedin.com/positions/1234",
    "notes":"<div>Test Note</div>",
    "attachmentIds": [
        "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
        "16880903-3496-4e0b-853b-af8cd4dcb3b2"
    ],
    "collaborators":[
        {
            "email":"john@happo.com",
            "type":"admin",
            "status": "accepted"
        },
        {
            "email":"tara@aw.se",
            "type":"client",
            "status": "awaiting_registration"
        }
    ]
}'
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "1ac435ee-9b11-4172-a934-3272b365e718",
        "title": "Software Enginner",
        "location": "Stockholm",
        "notes": "<div>Test Note</div>",
        "type": "full-time",
        "adPostingLink": "https://linkedin.com/positions/1234",
        "targetDate": "2018-06-25T00:00:00.000Z",
        "status": "open",
        "noOfPositions": 5,
        "attachmentIds": [
            "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
            "16880903-3496-4e0b-853b-af8cd4dcb3b2"
        ],
        "collaborators": [
            {
                "email": "john@happo.com",
                "userId": "83fadf49-5645-498c-a6a8-e64725ac83e6",
                "type": "admin",
                "status": "accepted"
            },
            {
                "email": "tara@aw.se",
                "userId": "65d15bf6-4991-4cd0-9c72-280e83de2fb9",
                "type": "client",
                "status": "awaiting_approval"
            }
        ],
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-05T09:57:09.244Z",
        "updatedAt": "2018-07-06T07:16:16.667Z"
    }
}
Suggest Edits

View Position

 

GET /positions/{position_id}

Call this API to view position details.

Slug Parameters

Name
Type
Description

position_id

String

Position ID

Response

Returns Position Object.

curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718 \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "1ac435ee-9b11-4172-a934-3272b365e718",
        "title": "Software Enginner",
        "location": "Stockholm",
        "notes": "<div>Test Note</div>",
        "type": "full-time",
        "adPostingLink": "https://linkedin.com/positions/1234",
        "targetDate": "2018-06-25T00:00:00.000Z",
        "status": "open",
        "noOfPositions": 5,
        "attachmentIds": [
            "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
            "16880903-3496-4e0b-853b-af8cd4dcb3b2"
        ],
        "collaborators": [
            {
                "email": "john@happo.com",
                "userId": "83fadf49-5645-498c-a6a8-e64725ac83e6",
                "type": "admin",
                "status": "accepted"
            },
            {
                "email": "tara@aw.se",
                "userId": "65d15bf6-4991-4cd0-9c72-280e83de2fb9",
                "type": "client",
                "status": "awaiting_approval"
            }
        ],
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-05T09:57:09.244Z",
        "updatedAt": "2018-07-06T07:04:36.140Z"
    }
}
Suggest Edits

List Positions

 

GET /positions

Call this API to list all positions visible to the user.

Position is accessible if:

  1. User is position owner/creator
  2. User is collaborator (admin/supplier/client)

Archived positions will not be visible.

Response

Returns the list of position objects.

curl https://api.happo.com/v1/positions \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": [
        {
            "id": "1ac435ee-9b11-4172-a934-3272b365e718",
            "title": "Software Enginner",
            "location": "Stockholm",
            "notes": "<div>Test Note</div>",
            "type": "full-time",
            "adPostingLink": "https://linkedin.com/positions/1234",
            "targetDate": "2018-06-25T00:00:00.000Z",
            "status": "open",
            "noOfPositions": 5,
            "attachmentIds": [
                "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
                "16880903-3496-4e0b-853b-af8cd4dcb3b2"
            ],
            "collaborators": [
                {
                    "email": "john@happo.com",
                    "userId": "83fadf49-5645-498c-a6a8-e64725ac83e6",
                    "type": "admin",
                    "status": "accepted"
                },
                {
                    "email": "tara@aw.se",
                    "userId": "65d15bf6-4991-4cd0-9c72-280e83de2fb9",
                    "type": "client",
                    "status": "awaiting_registration"
                }
            ],
            "creatorId": "94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt": "2018-07-05T09:57:09.244Z",
            "updatedAt": "2018-07-06T07:16:16.667Z"
        },
        {
            "id": "5e03d22d-e6b4-4d02-9344-a338295215de",
            "title": "Software Tester",
            "location": "Malmo",
            "notes": "<div><b>Job Description</b></div><ul><li>Testing</li><li>Automation</li></ul>",
            "type": "part-time",
            "adPostingLink": "https://moster.com/positions/1234",
            "targetDate": "2018-09-25T00:00:00.000Z",
            "status": "draft",
            "noOfPositions": 2,
            "attachmentIds": [
                "a9a4c7d7-142c-4a21-9697-c6c213a81b14"
            ],
            "collaborators": [
                {
                    "email": "dave@happo.com",
                    "userId": "95f7bca5-e8c6-4dc9-88db-cf5d18b4fdf6",
                    "type": "admin",
                    "status": "accepted"
                },
                {
                    "email": "neo@test.se",
                    "userId": "83a8c457-7571-440c-b4d4-756d43094a2e",
                    "type": "supplier",
                    "status": "awaiting_approval"
                }
            ],
            "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt": "2018-07-06T07:17:35.972Z",
            "updatedAt": "2018-07-06T07:17:35.972Z"
        }
    ]
}
Suggest Edits

Candidates

 

Job candidates in Happo can be managed by candidates APIs.

You can:

  • Create and update a candidate for a specific position
  • Get a list of all candidates belonging to the specific position that's accessible to you
  • View details of a specific candidate
Suggest Edits

Candidate Object

 

Position object contains following fields

Attribute
Nested Attribute
Type
Always Present
Contents
Description

id

-

String

YES

-

UUID based unique identifier of the candidate

name

-

String

NO

Candidate's name

phoneNumber

-

String

NO

-

Candidate's phone number

compensation

-

String

NO

-

Candidate's Rate/Fee/Salary

description

-

String

NO

Text can contain following html tags for formatting.

b, i, em, strong, a, p, div, ol, li, ul.

Presentation / Candidate description.

attachmentIds

-

Array of Strings

NO

Contains array of attachment IDs attached to this candidate.

Refer Uploading Attachment for generating attachment id.

Refer View Attachment for attachment details.

email

-

String

NO

Candidate's email address

availableFromDate

-

Date

NO

-

Date candidate is available for the job

stack

-

String

YES

Can be one of
draft
application
longlist
interesting
interviewing
shortlist
hired

Stack candidate is currently in.
It represents the actual status of the candidate in regards to hiring process.

phase

-

Array

YES

Can be one of
application
screening
evaluation
decision
hired

Phase candidate is currently in.
It represents the brief status of the candidate in regards to hiring process.

positionId

-

String

YES

ID of the position to which candidate belongs

createdAt

-

Date

YES

Time stamp when candidate was created

updatedAt

-

Date

YES

Time stamp at when candidate was updated

createdBy

-

String

YES

Creator's user ID.

{
    "id": "0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52",
    "name": "Riya Johnson",
    "phoneNumber": "1234567890",
    "compensation": "$3400 per month",
    "email": "riya.j@test.com",
    "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
    "attachmentIds": [
        "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
        "cf167dd7-e43b-46dc-800a-310406f57a4e"
    ],
    "availableFromDate": "2018-08-28T18:30:00.000Z",
    "stack": "interviewing",
    "phase": "evaluation",
    "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
    "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
    "createdAt": "2018-07-06T06:39:44.713Z",
    "updatedAt": "2018-07-06T06:48:46.013Z"
}
Suggest Edits

Create/Update Candidate

 

Candidate can be created by POST method to /positions/{position_id}/candidates.

and can be updated by POST method to /positions/{position_id}/candidates/{candidate_id}.

Slug Parameters

Name
Type
Description

position_id

String Required

Position ID.

candidate_id

String Optional

Candidate ID.
If passed existing candidate will be updated, otherwise new candidate will be created

Request Payload

Note: Any optional field can be deleted by posting null value in update request payload

Attribute
Nested Attribute
Type
Required
Validations
Description

name

-

String

YES

-

Candidate name.

phoneNumber

-

String

NO

-

Candidate's phone number

compensation

-

String

NO

-

Candidate's Rate/Fee/Salary

description

-

String

NO

Text can contain following html tags for formatting.

b, i, em, strong, a, p, div, ol, li, ul.

Other html tags will be removed while saving.

Presentation / Candidate description.

attachmentIds

-

Array of Strings

NO

Contains array of attachment IDs attached to this candidate.

Refer Uploading Attachment for generating attachment id.

email

-

String

NO

-

Candidate's email address

availableFromDate

-

Date

NO

-

Date candidate is available for the job

Response

Returns Candidate Object.

curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718/candidates \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json" -d \
'{
    "name":"Adam Smith",
    "phoneNumber":"1234567890",
    "compensation":"$3000 per month",
    "email":"adam.smith@test.com",
    "availableFromDate":"2018-08-28T18:30:00.000Z",
    "description":"<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
    "attachmentIds": [
        "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
        "cf167dd7-e43b-46dc-800a-310406f57a4e"
    ]
}'
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "cfac0e8a-2528-4f53-b1af-de63d81f6f09",
        "name": "Adam Smith",
        "phoneNumber": "1234567890",
        "compensation": "$3000 per month",
        "email": "adam.smith@test.com",
        "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
        "availableFromDate": "2018-08-28T18:30:00.000Z",
        "attachmentIds": [
            "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
            "cf167dd7-e43b-46dc-800a-310406f57a4e"
    		],
        "stack": "longlist",
        "phase": "screening",
        "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-06T05:40:21.678Z",
        "updatedAt": "2018-07-06T05:40:21.678Z"
    }
}
curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718/candidates/0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52 \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json" -d \
'{
    "name":"Riya Johnson",
    "phoneNumber":"1234567890",
    "compensation":"$3400 per month",
    "email":"riya.j@test.com",
    "availableFromDate":"2018-08-28T18:30:00.000Z",
    "description":"<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
    "attachmentIds": [
        "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
        "cf167dd7-e43b-46dc-800a-310406f57a4e"
    ]
}'
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52",
        "name": "Riya Johnson",
        "phoneNumber": "1234567890",
        "compensation": "$3400 per month",
        "email": "riya.j@test.com",
        "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
        "attachmentIds": [
            "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
            "cf167dd7-e43b-46dc-800a-310406f57a4e"
        ],
        "availableFromDate": "2018-08-28T18:30:00.000Z",
        "stack": "interviewing",
        "phase": "evaluation",
        "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-06T06:39:44.713Z",
        "updatedAt": "2018-07-06T06:48:46.013Z"
    }
}
Suggest Edits

Bulk Posting of Candidates

 

If you want to upload more than one candidates to same position, it can be done at once by POST method to /positions/{position_id}/candidates/bulk.

Slug Parameters

Name
Type
Description

position_id

String Required

Position ID.

Request Payload

Note: Any optional field can be deleted by posting null value in update request payload

Attribute
Nested Attribute
Type
Required
Validations
Description

candidates

-

Array of Objects

YES

Can contain maximum 50 candidate objects for each request

name

String

Candidate name.

phoneNumber

String

NO

-

Candidate's phone number

compensation

String

NO

-

Candidate's Rate/Fee/Salary

description

String

NO

Text can contain following html tags for formatting.

b, i, em, strong, a, p, div, ol, li, ul.

Other html tags will be removed while saving.

Presentation / Candidate description.

attachmentIds

Array of Strings

NO

Contains array of attachment IDs attached to this candidate.

Refer Uploading Attachment for generating attachment id.

email

String

NO

-

Candidate's email address

availableFromDate

Date

NO

-

Date candidate is available for the job

Response

Returns the list of Candidate Object.

curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718/candidates/bulk \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json" -d \
'{
    "candidates": [
        {
            "name":"Ben Smith",
            "phoneNumber":"1234567890",
            "compensation":"$3000 per month",
            "email":"ben.smith@test.com",
            "availableFromDate":"2018-08-28T18:30:00.000Z",
            "description":"<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>"
        },
        {
            "name":"Erica Williams",
            "phoneNumber":"1234567890",
            "compensation":"$4000 per month",
            "email":"erica.williams@test.com",
            "availableFromDate":"2018-09-28T18:30:00.000Z"
        }
    ]
}'
HTTP/1.1 200 OK
#Example
{
    "success":true,
    "statusCode":200,
    "data":[
        {
            "id":"731740ed-225b-46f2-a1c6-f5bc0781fa64",
            "name":"Ben Smith",
            "phoneNumber":"1234567890",
            "compensation":"$3000 per month",
            "email":"ben.smith@test.com",
            "description":"<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
            "availableFromDate":"2018-08-28T18:30:00.000Z",
            "stack":"longlist",
            "phase":"screening",
            "positionId":"1ac435ee-9b11-4172-a934-3272b365e718",
            "createdBy":"94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt":"2018-07-06T05:40:21.678Z",
            "updatedAt":"2018-07-06T05:40:21.678Z"
        },
        {
            "id":"2683a598-4fff-4560-b248-5469015c6f0c",
            "name":"Erica Williams",
            "phoneNumber":"1234567890",
            "compensation":"$4000 per month",
            "email":"erica.williams@test.com",
            "availableFromDate":"2018-09-28T18:30:00.000Z",
            "stack":"longlist",
            "phase":"screening",
            "positionId":"1ac435ee-9b11-4172-a934-3272b365e718",
            "createdBy":"94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt":"2018-07-06T05:40:21.678Z",
            "updatedAt":"2018-07-06T05:40:21.678Z"
        }
    ]
}
Suggest Edits

View Candidate

 

GET /positions/{position_id}/candidates/{candidate_id}

Call this API to view position details.

Slug Parameters

Name
Type
Description

position_id

String

Position ID

candidate_id

String

Candidate ID

Response

Returns Candidate Object.

curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718/candidates/0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52 \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52",
        "name": "Riya Johnson",
        "phoneNumber": "1234567890",
        "compensation": "$3400 per month",
        "email": "riya.j@test.com",
        "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
         "attachmentIds": [
            "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
            "cf167dd7-e43b-46dc-800a-310406f57a4e"
        ],
        "availableFromDate": "2018-08-28T18:30:00.000Z",
        "stack": "interviewing",
        "phase": "evaluation",
        "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
        "createdAt": "2018-07-06T06:39:44.713Z",
        "updatedAt": "2018-07-06T06:48:46.013Z"
    }
}
Suggest Edits

List Candidates

 

GET /positions/{position_id}/candidates

Call this API to list all Candidates visible to the user.

Note:
Suppliers can only view candidates created by themselves or by their colleagues who have the same email domain

Slug Parameters

Name
Type
Description

position_id

String

Position ID

Response

Returns the list of candidate objects.

curl https://api.happo.com/v1/positions/1ac435ee-9b11-4172-a934-3272b365e718/candidates \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": [
        {
            "id": "0d5a3e07-e56a-4d28-b3d4-b87cfaefbe52",
            "name": "Riya Johnson",
            "phoneNumber": "1234567890",
            "compensation": "$3400 per month",
            "email": "riya.j@test.com",
            "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
            "attachmentIds": [
                "b8a22718-a086-45ac-bfa7-2383a1b2f91b",
                "cf167dd7-e43b-46dc-800a-310406f57a4e"
            ],
            "availableFromDate": "2018-08-28T18:30:00.000Z",
            "stack": "interviewing",
            "phase": "evaluation",
            "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
            "creatorId": "94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt": "2018-07-06T06:39:44.713Z",
            "updatedAt": "2018-07-06T06:48:46.013Z"
        },
        {
            "id": "cfac0e8a-2528-4f53-b1af-de63d81f6f09",
            "name": "Adam Smith",
            "phoneNumber": "1234567890",
            "compensation": "$3000 per month",
            "email": "adam.smith@test.com",
            "description": "<div><b>Skills</b></div><ul><li>Java</li><li>Javascript</li><li>HTML</li></ul>",
            "attachmentIds": [
                "z8a22718-a086-45ac-bfa7-2383a1b2f91e"
            ],
            "availableFromDate": "2018-08-28T18:30:00.000Z",
            "stack": "longlist",
            "phase": "screening",
            "positionId": "1ac435ee-9b11-4172-a934-3272b365e718",
            "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436",
            "createdAt": "2018-07-06T05:40:21.678Z",
            "updatedAt": "2018-07-06T05:40:21.678Z"
        }
    ]
}
Suggest Edits

Attachments

 

Before attaching documents to any Position or Candidate in Happo, you need to upload a document to Happo storage.

Using attachments API you can

  • Upload an attachment to Happo storage.
  • View the attachment if you are the creator or if you have access to the Position or Candidate to which the attachment belongs.
Suggest Edits

Attachment Object

 

Attachment object contains following fields

Attribute
Nested Attribute
Type
Always Present
Contents
Description

id

-

String

YES

-

UUID based unique identifier of the attachment

fileName

-

String

YES

Name of the attachment file.

parentModelId

-

String

NO

Present if parentModeType is present.

ID of the Position or Candidate to which the attachment belongs.

parentModeType

-

String

NO

Can be one of
position
candidate.

Present if parentModelId is present.

Represents if the attachment belongs to the position or candidate.

accessUrl

-

String

NO

Always present in attachment view API response.

Temporary access URL to view or download the attachment.

accessExpiringAt

-

Date

NO

Always present in attachment view API response.

Timestamp at when access will be expired.

Access window is 5 minutes since the access was requested

createdBy

-

String

YES

Creator's user ID.

{
    "id": "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
    "parentModelId": "1ac435ee-9b11-4172-a934-3272b365e718",
    "parentModelType": "position",
    "accessUrl": "https://attachments.happo.com/secure/pdf-sample-1532343073308psDWgv56mDU9WsHerljCH49XKjGZyc3r.pdf?st=2018-0T06%3A44%3A37Z&se=2018-07-25T06%3A50%3A37Z&sp=r&sv=2015-04-05&sr=b&sig=sXoPPexWVfqcEVfw9qfd8Uu9peh5rTZjAqM7LYJi%2FtA%3D",
    "accessExpiringAt": "2018-07-25T06:50:37.744Z",
    "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436"
}
Suggest Edits

Uploading Attachment

 

POST /attachments

  • To upload a file, send a multipart/form-data request to this API.
  • Note that just uploading the document will not link it to any position or candidate.
  • id in the response should be saved and used in Create/Update Position or Create/Update Candidate APIs to attach the document to the that object.
  • If attachment is linked to the particular position or candidate, all users who have access to that position or candidate can access the attachment, otherwise only attachment creator can access the attachment.
  • Maximum allowed file size is 5 MB.

Form Data

Name
Contents

attachment

File to attach.

Response

Returns Attachment object.

curl https://api.happo.com/v1/attachments \
-X POST \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: multipart/form-data" \
-F "attachment=@/path/to/sample.pdf"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "43a2335f-ef73-4bba-bfcb-d2e4e2d4aaff",
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436"
    }
}
Suggest Edits

View Attachment

 

GET /attachments/{attachment_id}

Attachment details can be get by view attachment API if the user has access to the attachment.

  • Users who has access to parent candidate or position object identified by parentModelId and parentModelType can access the attachment.
  • If parentModelId is not present only the attachment creator has access to the attachment.
  • accessUrl in the response could be used to view and download the attachment.
  • accessUrl is valid only till timestamp returned in accessExpringAt (5 minutes since the access is requested).

Slug Parameters

Name
Type
Description

attachment_id

String

Attachment ID

Response

Returns Attachment Object.

curl https://api.happo.com/v1/attachments/e9a4c7d7-142c-4a21-9697-c6c213a81b13 \
-H "Authorization:Bearer <your_api_secret_key>" \
-H "x-happo-api-version:v20180701" \
-H "Content-Type: application/json"
HTTP/1.1 200 OK
#Example
{
    "success": true,
    "statusCode": 200,
    "data": {
        "id": "e9a4c7d7-142c-4a21-9697-c6c213a81b13",
        "parentModelId": "1ac435ee-9b11-4172-a934-3272b365e718",
        "parentModelType": "position",
        "accessUrl": "https://attachments.happo.com/secure/pdf-sample-1532343073308psDWgv56mDU9WsHerljCH49XKjGZyc3r.pdf?st=2018-07-25T06%3A48%3A56Z&se=2018-07-25T06%3A54%3A56Z&sp=r&sv=2015-04-05&sr=b&sig=zzrIcSwXN1CTIl4EWmBiTbpaLubWzMHR3zHlN%2FuAMHA%3D",
        "accessExpiringAt": "2018-07-25T06:54:56.776Z",
        "createdBy": "94c4890b-461f-412e-8a69-2f60489e5436"
    }
}