API Reference
API endpoint:
https://api.jobscore.com/v2
The JobScore Hire API v2 is a RESTful API designed to have predictable, resource-oriented URLs.
We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. We use HTTP response codes to indicate API errors.
- JSON will be returned in all responses from the API, including errors.
- Lists of items are returned unsorted unless a sort order is explicitly stated in documentation below.
- We reserve the right to add more properties to objects, but will never change or remove them.
- All strings must be UTF-8 encoded.
- Dates are encoded as strings in the
YYYY-MM-DD
format. - Timestamps are encoded using the ISO 8601 convention.
- All objects have an immutable 22 character unique identifier (uid) and immutable created_on and updated_on timestamps.
- All dates and timestamps are UTC and encoded in ISO 8601 format (e.g.
1969-10-05
,2024-12-24T23:59:59Z
). Timestamp inputs with non-UTC timezones will be rejected.
If you want to report a bug, request a feature or ask a question about the JobScore Hire API & Webhooks, please go to this GitHub repository and open an issue.
Usage
The JobScore Hire API lets you build a variety of applications and integrations. However, the JobScore Hire API is not designed for you to build a customized careers site / jobs page. Please build your careers site using the Job Feed API.
Version 2 adds a number of PATCH and POST endpoints for create and update use cases, and is not backwards compatible with v1, which is deprecated.
The JobScore Hire API is available to Enterprise customers and select partners. Interested partners should contact partners@jobscore.com.
Authentication
Example request using Token Authentication:
curl https://api.jobscore.com/v2/users/me \
-H "Authorization: Token token={your_token}"
You authenticate to our API by providing your Personal Access Token in the request. Your tokens carry many privileges, so be sure to keep them secret and secure!
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.
You can generate an access token on the Integrations > JobScore API & Webhooks page.
HTTP Token Authentication
You can authenticate via HTTP Token Authentication by sending an Authorization header with the Token parameter.
Impersonation
Impersonation Example:
curl https://api.jobscore.com/v2/users/me \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-H "X-On-Behalf-Of: {user_id}"
You can impersonate a different user by sending the X-On-Behalf-Of
header.
Only tokens with the Account
access level can use such feature.
The content for the header must be a user’s unique identifier, which you can fetch using the List Users endpoint. Please refer to the example shown to the right.
Rate Limits
cURL uses the
-v
flag to print return headers.
curl https://api.jobscore.com/v2/users/me \
-H "Authorization: Token token={your_token}" \
-v
Among other headers, you will find the following ones:
(...)
< Ratelimit-Limit: 3600
< Ratelimit-Remaining: 2891
< RateLimit-Reset: 1683576000
(...)
We rate limit by token. By default, we allow 3,600 requests/hour. On every
request, the HTTP headers RateLimit-Limit
, RateLimit-Remaining
and
RateLimit-Reset
will be returned.
We use a fixed window implementation, meaning that your number of requests
will be reset exactly 1 hour after you made the first request.
Required HTTP Headers
The Content-Type
header must be set on every POST
or PATCH
.
The Accept
header is not required, but is recommended.
HTTP Method | Headers |
---|---|
GET | Accept: application/json |
POST | Content-Type: application/json (required)Accept: application/json |
PATCH | Content-Type: application/json (required)Accept: application/json |
DELETE | No specific headers required. |
Responses and Errors
We use HTTP response codes to indicate success or failure of a request.
Response codes in the range 2xx
indicate a successful request; 4xx
range
indicates an error with your request (this could be an invalid Content-Type
,
missing or invalid parameters, etc), and 5xx
range indicates an error on our servers.
Code | Description |
---|---|
200 | OK: If data was requested, it will be available in the data field at the top level of the response body. |
201 | Created: Resource was successfully created and information is available in the data field at the top level of the response body. |
400 | Bad Request: The request data is invalid in some way. |
401 | Unauthorized: You are not authorized to access a resource. Your authentication token is missing or is invalid. |
403 | Forbidden: You do not have permission to access that specific resource. |
404 | Not Found: The requested resource does not exist. |
405 | Method Not Allowed: You are using the wrong HTTP method. Use POST to create a resource, GET to get them and PATCH to update. |
406 | Not Acceptable: The Accept header you sent has not even one application/json media type without parameter. |
415 | Unsupported Media Type: The Content-Type header you sent is not application/json . |
422 | Unprocessable Entity: The request was formatted correctly but cannot be processed in its current form. Often used when the specified parameters fail validation errors. |
429 | Too Many Requests: You used more requests than you’re allowed to. Keep an eye on HTTP headers RateLimit-Limit RateLimit-Remaining and RateLimit-Reset to prevent that from happening again. |
500 | Internal Server Error: Houston, we have a problem. Please try again, and report continued problems to api@jobscore.com. Include the error code in your message; it is returned in the X-ErrorCode HTTP header and also as error_code on the JSON response. |
503 | Service Unavailable: We’re offline for maintenance. Try again later. |
Pagination
Example request:
curl -X https://api.jobscore.com/v2/candidates \
-H "Authorization: Token token={your_token}"
{
"items": ["REDACTED"],
"pagination": {
"current_page": 2,
"next_page": 3,
"total_pages": 27,
"total_records": 653,
"per_page": 25
}
}
(...)
< X-Current-Page: 2
< X-Next-Page: 3
< X-Total-Pages: 27
< X-Total-Records: 653
< X-Per-Page: 25
(...)
All resources with a list (candidates, jobs, etc) have pagination support.
We accept pagination as query parameters. The page
parameter denotes the page
number, starting from 1. The per_page
denotes the number of records shown in
each page. This number is 25 if omitted. The maximum is 100.
In order to help navigation, we return a pagination
object in the JSON body
response with information about pages, like: current page, next page,
and total number of pages and records. This information is also returned on
HTTP headers.
Lists of items are returned unsorted unless a sort order is explicitly stated in documentation below.
Filters
Date filter example:
curl -X https://api.jobscore.com/v2/jobs?created_after=2023-01-01&created_before=2023-12-31 \
-H "Authorization: Token token={your_token}"
Filters are available on all list endpoints. The filters available on each endpoint are documented on the endpoint itself. They should always be given via query string parameters.
Date filters are available via {attribute}_after
and {attribute}_before
parameters. You can specific one of them or both. The date format should be
a valid ISO 8601 date, like
YYYY-MM-DD
or YYYY-MM-DDTHH:MM
.
When the time part is not specified, these dates are inclusive for both the
“after” and “before” parameters, which means that ?created_before=2023-12-31
will include records within that date, for example.
UTC is assumed.
Array filter example:
curl -X "https://api.jobscore.com/v2/candidates?job_statuses[]=open&job_statuses[]=internal" \
-H "Authorization: Token token={your_token}"
Filter parameters will be ANDed together. When a filter is array of OR options for the same parameter, you should append []
to the parameter name.
Applications
An application represents your consideration of a candidate for a job.
- Every application is in a workflow stage. All candidates start out in the
new
workflow stage. - Each candidate in the system may have multiple applications, or none at all. This means a single candidate may have multiple applications and be
declined
for one role whileinterviewing
for another, for example. - There are several ways an application can be created in JobScore:
- A candidate can apply directly for a job;
- A user (employee) can assign them to a job. Employees often assign candidates to roles when making referrals and in-house recruiters usually do this when sourcing passive candidates;
- An external search firm recruiter can submit them for a specific job opportunity.
The Application Object
Attributes
- status string
-
Candidate status. One of:
new
,active
,declined
,withdrawn
orhired
. - stage object
-
Current workflow stage this application is in.
- id string
- Stage’s unique identifier.
- name string
- Stage name.
- candidate object
-
Candidate associated with the application.
- id uid
- Candidate’s unique identifier.
- first_name string
- Candidate’s first name.
- last_name string
- Candidate’s last name.
- job object
-
Job associated with the application.
- id uid
- Job’s unique identifier.
- title string
- Job title.
- internal_title string
- Internal job title.
- requisition_number string
- Job requisition number.
- status string
- Job’s status.
- documents list
- Documents attached to this application.
- offer_id
- If present, represents the unique identifier for an offer associated with the application.
- disposition_code string
- Disposition code name.
- created_on timestamp, readonly
- Application creation date.
- updated_on timestamp, readonly
- Application most recent update date.
List Applications
curl https://api.jobscore.com/v2/candidates/{candidate_id}/applications \
-H 'Authorization: Token token={your_token}'
Get list of applications for a candidate.
{
"items": [
{
"id": "dgG_37Xa1jS4dUN-9PB8hc",
"status": "new",
"stage": null,
"candidate": {
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips"
},
"job": {
"id": "ckLb8Jhtfa-BvKpmMLlFyV",
"title": "Software Engineer",
"internal_title": null,
"requisition_number": "0001",
"status": "open"
},
"documents": [
{
"id": "akfCdQ15boJOZRj2Gc_87P",
"type": "cover_letter",
"filename": "Cover Letter text added on 2023-04-12.html"
}
],
"offer_id": null,
"disposition_code": null,
"created_on": "2023-04-12T15:58:11Z",
"updated_on": "2023-04-24T13:26:11Z"
},
{
"id": "bdLMkbgj9g3Qg7mCg-oSUT",
"status": "hired",
"stage": null,
"candidate": {
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips"
},
"job": {
"id": "cHP1ehgaTpJk7OtRndxGm5",
"title": "QA Tester",
"internal_title": null,
"requisition_number": "0002",
"status": "open"
},
"documents": [],
"offer_id": "cyJmjqoULmAztSu60WgpgC",
"disposition_code": null,
"created_on": "2023-04-11T17:52:27Z",
"updated_on": "2023-04-18T11:47:25Z"
},
{
"id": "auZUyIchLpcljbrWCLG-7e",
"status": "withdrawn",
"stage": null,
"candidate": {
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips"
},
"job": {
"id": "b5gW8AbWPa-RINe8is3Zc1",
"title": "Database Administrator",
"internal_title": null,
"requisition_number": "0003",
"status": "open"
},
"documents": [],
"offer_id": null,
"disposition_code": "Not interested in Job",
"created_on": "2023-04-04T11:34:25Z",
"updated_on": "2023-04-24T13:27:38Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 3,
"per_page": 25
}
}
HTTP Request
GET /v2/candidates/{candidate_id}/applications
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - created_after
- Filter by applications created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by applications created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by applications updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by applications updated before a given date. Should be on
YYYY-MM-DD
format.
Get Application
curl https://api.jobscore.com/v2/applications/{application_id} \
-H 'Authorization: Token token={your_token}'
Get existing application.
{
"id": "auZUyIchLpcljbrWCLG-7e",
"status": "withdrawn",
"stage": null,
"candidate": {
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips"
},
"job": {
"id": "b5gW8AbWPa-RINe8is3Zc1",
"title": "Database Administrator",
"internal_title": null,
"requisition_number": "0003",
"status": "open"
},
"documents": [],
"offer_id": "bp_xVqJF5lM4OZHDKBqV4L",
"disposition_code": "Not interested in Job",
"created_on": "2023-04-04T11:34:25Z",
"updated_on": "2023-04-24T13:27:38Z"
}
HTTP Request
GET /v2/applications/{application_id}
Parameters
- application_id required, uid
- Application’s unique identifier.
Create Application
curl -X POST https://api.jobscore.com/v2/candidates/{candidate_id}/applications \
-H 'Authorization: Token token={your_token}' \
-H 'Content-Type: application/json' \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"job_id": "{job_id}",
"cover_letter": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum gravida metus non dui dictum, vitae fermentum lectus facilisis. Praesent aliquam in lacus sit amet tempus."
}
Create new application for a candidate.
HTTP Request
POST /v2/candidates/{candidate_id}/applications
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
Request Body
The application’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- job_id required, uid
- Unique identifier of the job associated with the application.
- cover_letter string
- Application’s cover letter. Must have at least 100 characters.
Update Application
curl -X PATCH https://api.jobscore.com/v2/applications/{application_id} \
-H 'Authorization: Token token={your_token}' \
-H 'Content-Type: application/json' \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"status": "active",
"stage_id": "{sub_stage_id}"
}
Update the status, active stage, and/or disposition code on a candidate application.
HTTP Request
PATCH /v2/applications/{application_id}
Parameters
- application_id required, uid
- Applications’s unique identifier.
Request Body
The application’s data you are about to update must be sent via Request Body as a JSON-formatted object.
Parameters
- status required, string
-
Must be one of:
new
,active
,declined
orwithdrawn
. (hired
is not allowed in this action). - stage_id uid
-
A workflow stage‘s unique identifier. Only applicable (and required) if
status
isactive
. - disposition_code uid
-
Disposition code’s unique identifier. Required if workflow status is either
withdrawn
ordeclined
and your account has disposition codes enabled.
Candidates
Candidates represent specific people you are trying to hire right now — or at some point in the future.
- Candidates can add themselves to your account by applying, added by your team as referrals, added as part of sourcing/research efforts, or be submitted by search firm recruiters.* Candidate records include personally identifiable information like name, phone number, email, address, work experience and education history.
- Candidates may be associated with documents (resumes, cover letters), notes, emails and tasks.
- Candidates are connected to jobs through applications. Each application has a workflow stage (e.g. interviewing).
- Candidates have a Source. It is how you originally found / came into contact with a candidate. Each candidate has only one source.
The Candidate Object
- first_name string
- First name.
- last_name string
- Last name.
- address object
-
- country string
- 2 letter ISO country code.
- state string
-
State name. If country is
US
, must be a valid 2 letter USPS abbreviation. Outside the US this is handled as free text. - city string
- City name.
- postal_code number
- Postal code or Zip code.
- street1 string
- Street address, line 1.
- street2 string
- Street address, line 2.
- tags list
- Tags provide additional context or information about candidates. They are a great way to group or categorize candidates with specific attributes.
- phone_numbers list
-
- type string
- Phone type.
- number number
- Phone number.
- email_addresses list
-
- type string
- Email address type.
- address string
- Email address.
- profile_links list
-
- type string
- Profile link type.
- url string
- Profile URL.
- employment list
-
- employer string
- Employer name.
- positions list
-
- title string
- Job title name.
- start_date string
-
Start date in
YYYY-MM-DD
format. For most records, the day part will be truncated to the 1st day of the month. - end_date string
-
End date in
YYYY-MM-DD
format. For most records, the day part will be truncated to the 1st day of the month.
- education list
-
- school_name string
- School or college name.
- graduation_date string
-
Graduation date in
YYYY-MM-DD
format. For most records, the day part will be truncated to the 1st day of the month. - degree string
- Degree type.
- degree_major string
- Degree description.
- application object
-
- job_id string
- The ID of the job. Read the Jobs section to see how you can fetch a list of existing jobs.
- source_type string
-
Source type.
Can be one of:network
,website
,job_board
,referral
,social
,email
,event
,user
,internal
,database
,search_firm
orother
. - source_detail object
-
- <additional fields>
- Specific sources accept, and in some cases require specific additional fields. See the Candidate Source Detail Object section for details.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
The Candidate Source Detail Object
Candidate source represents who “gets credit” for finding a candidate. A source may include up to three parts:
- Source type which explains how the candidate was added to your JobScore account. For example, someone may have applied because they found one of your jobs on a job board, a sourcer may have done research and found them using Google, or an employee may have added a friend’s resume directly into the system as a referral.
- Source detail provides more detail about the primary source. For instance, a candidate who found your job on a job board would have the primary source “Job Board” and the secondary source “Indeed” where a resume found on Google would have the primary source “Database” and secondary source “Google.”
Each primary source has customizable source detail attributes. Learn more about sources in JobScore.
This object represents all possible candidate source and source detail values configured for your JobScore account.
Some sources have additional fields that can be assigned and are documented below.
If no source is set, Other
will be assigned by default with API
as the detail.
{
"source_type": "company_website"
}
{
"source_type": "job_board",
"source_detail": {
"job_board": "Job Board Name"
}
}
{
"source_type": "referral",
"source_detail": {
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john_doe@mycompany.com"
}
}
{
"source_type": "social",
"source_detail": {
"social_network": "LinkedIn",
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john_doe@mycompany.com"
}
}
{
"source_type": "email",
"source_detail": {
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john_doe@mycompany.com"
}
}
{
"source_type": "event",
"source_detail": {
"social_network": "Event Name",
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john_doe@mycompany.com"
}
}
{
"source_type": "user",
"source_detail": {
"user_id": "cQOc2oZ30r3l1_aaWPX6Zm",
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john_doe@mycompany.com"
}
}
{
"source_type": "internal"
}
{
"source_type": "database",
"source_detail": {
"database": "Database Name"
}
}
{
"source_type": "search_firm",
"source_detail": {
"search_firm_id": "aGr7vFMY9gm5TMFt2XECpW",
"search_firm_recruiter_id": "cDrry0X1HdBy5LcxgKlF8n"
}
}
{
"source_type": "other",
"source_detail": {
"detail": "Any information about the source."
}
}
- Company Website
-
- source_type
website
- source_detail
- None
- Job Board
-
- source_type
job_board
- source_detail
-
- job_board required, string
- Job board name. Check out the Job Boards section to see how you can fetch a list of existing job boards.
- Referral
-
- source_type
referral
- source_detail
-
- referral_first_name required, string
- Referrer first name.
- referral_last_name required, string
- Referrer last name.
- referral_email required, string
- Referrer email address.
- Social Network
-
- source_type
social
- source_detail
-
- social_network required, string
-
One of:
Facebook
,LinkedIn
orTwitter
. - referral_first_name string
- Referrer first name.
- referral_last_name string
- Referrer last name.
- referral_email string
- Referrer email address.
-
- source_type
email
- source_detail
-
- referral_first_name required, string
- Referrer first name.
- referral_last_name required, string
- Referrer last name.
- referral_email required, string
- Referrer email address.
- Event
-
- source_type
event
- source_detail
-
- event required, string
- Event name. Check out the Events section to see how you can fetch a list of existing events.
- referral_first_name string
- Referrer first name.
- referral_last_name string
- Referrer last name.
- referral_email string
- Referrer email address.
- User
-
- source_type
user
- source_detail
-
- user_id required, uid
- User ID. Check out the Users section to see how you can fetch a list of existing users.
- referral_first_name string
- Referrer first name.
- referral_last_name string
- Referrer last name.
- referral_email string
- Referrer email address.
- Internal
-
- source_type
internal
- source_detail
- None
- Database
-
- source_type
database
- source_detail
-
- database required, string
- Database name. Check out the Databases section to see how you can fetch a list of existing databases.
- Search Firm
-
- source_type
search_firm
- source_detail
-
- search_firm_id required, uid
- Search Firm ID. Check out the Search Firms section to see how you can fetch a list of existing search firms.
- search_firm_recruiter_id required, uid
- Search Firm Recruiter ID. Check out the Search Firm Recruiters section to see how you can fetch a list of existing search firm recruiters.
- Other
-
- source_type
other
- source_detail
-
- detail required, string
- Free text. Use to add any description about this candidate source.
List Candidates
curl https://api.jobscore.com/v2/candidates \
-H 'Authorization: Token token={your_token}'
{
"items": [
{
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips",
"source_type": "email",
"source_detail": {
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john.doe@outlook.com"
},
"tags": [
"golang",
"ruby",
"typescript"
],
"address": {
"country": "US",
"state": "California",
"city": "San Francisco",
"postal_code": "94105",
"street1": "123 Main St",
"street2": "Apt 1",
"latitude": 37.7864,
"longitude": -122.3892
},
"phone_numbers": [
{
"type": "home",
"number": "+55 99720-0001"
},
{
"type": "mobile",
"number": "+55 99720-0002"
},
{
"type": "other",
"number": "+55 99720-0003"
}
],
"email_addresses": [
{
"type": "personal",
"address": "timothy.philips@gmail.com"
},
{
"type": "work",
"address": "timothy.philips@yourcompany.com"
}
],
"profile_links": [
{
"type": "github",
"url": "https://github.com/timothyphilips12345"
},
{
"type": "linked_in",
"url": "https://www.linkedin.com/in/timothy-philips-12345"
},
{
"type": "twitter",
"url": "https://twitter.com/timothyphilips12345"
}
],
"employment": [
{
"id": "bpbREEkHTgSkQO382NO103",
"employer": "Revel",
"positions": [
{
"id": "asGdoXTA1eeyb8kfd2zGbr",
"title": "Senior Software Engineer",
"start_date": "2019-01-01",
"end_date": "2019-12-31"
},
{
"id": "dDd0-Q-RvbY5lE110tq0V1",
"title": "Software Engineer",
"start_date": "2018-01-01",
"end_date": "2018-12-31"
},
{
"id": "aaM-99b79fjz5lG6V26V_u",
"title": "Intern",
"start_date": "2017-01-01",
"end_date": "2017-12-31"
}
]
},
{
"id": "bsw47qSPLaeR5mQMxiBnhX",
"employer": "YourCompany",
"positions": []
}
],
"education": [
{
"id": "bCLMQzRTbjsjGuPIHa6yqM",
"school_name": "UFPR",
"graduation_date": "2016-12-31",
"degree": "Masters",
"degree_major": "Science of Computing"
},
{
"id": "aTGq4hU19ayP07mwP-st2D",
"school_name": "UDESC",
"graduation_date": "2015-12-31",
"degree": "Bachelors",
"degree_major": "Computer Science"
}
],
"applications": [
{
"id": "ck5QkojinaJ6sPbmgFzYqB",
"status": "new",
"stage": null,
"job": {
"id": "deuV1SSDfag4xah7Hi3evR",
"title": "Senior Software Engineer",
"internal_title": null,
"requisition_number": "0004",
"status": "open"
},
"created_on": "2023-05-03T18:38:40Z",
"updated_on": "2023-05-03T18:38:40Z"
}
],
"created_on": "2023-05-03T18:38:39Z",
"updated_on": "2023-05-03T18:38:40Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1,
"per_page": 25
}
}
Get list of candidates.
HTTP Request
GET /v2/candidates
Parameters
These parameters should be given via query string.
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
full_name
,created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - job_statuses[]
-
Filter by candidates assigned to jobs in specific job statuses.
This must be:
draft
,internal
,open
,on_hold
,closed
orfilled
. - job_ids[]
- Filter by candidates assigned to specific jobs. Check out the Jobs section to see how to fetch the list of available jobs.
- statuses[]
-
Filter by candidates assigned to specific statuses.
This must be:
new
,active
,declined
,withdrawn
orhired
. - stage_ids[]
- Filter by candidates assigned to specific stages. This must be a Workflow Stage ID as returned by List Workflow Stages.
- tags[]
- Filter by candidates with specific tags.
- sources[]
-
Filter by candidates with specific sources.
This must be:
network
,website
,job_board
,referral
,social
,email
,event
,user
,internal
,database
,search_firm
orother
. - received_after
- Filter by candidates received starting on a given date. Should be on
YYYY-MM-DD
format. - received_before
- Filter by candidates received before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by candidates updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by candidates updated before a given date. Should be on
YYYY-MM-DD
format. - email_addresses[]
- Filter candidates by email addresses.
Filter examples
Filtering by candidates on open and internal job statuses:
curl "https://api.jobscore.com/v2/candidates?job_statuses[]=open&job_statuses[]=internal" \
-H 'Authorization: Token token={your_token}'
Filtering by candidates statuses:
curl "https://api.jobscore.com/v2/candidates?statuses[]=new&statuses[]=action" \
-H 'Authorization: Token token={your_token}'
Filtering by tags:
curl "https://api.jobscore.com/v2/candidates?tags[]=ruby&tags[]=golang" \
-H 'Authorization: Token token={your_token}'
Filtering by email addresses:
curl "https://api.jobscore.com/v2/candidates?email_addresses[]=john.marston@gmail.com&email_addresses[]=arthur.morgan@outlook.com" \
-H 'Authorization: Token token={your_token}'
See some filtering examples on the right panel.
Get Candidate
curl https://api.jobscore.com/v2/candidates/{candidate_id} \
-H 'Authorization: Token token={your_token}'
{
"id": "cbxucKTqLiTQiFQDGiieVw",
"first_name": "Timothy",
"last_name": "Philips",
"source_type": "email",
"source_detail": {
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john.doe@outlook.com"
},
"tags": [
"golang",
"ruby",
"typescript"
],
"address": {
"country": "US",
"state": "California",
"city": "San Francisco",
"postal_code": "94105",
"street1": "123 Main St",
"street2": "Apt 1",
"latitude": 37.7864,
"longitude": -122.3892
},
"phone_numbers": [
{
"type": "home",
"number": "+55 99720-0001"
},
{
"type": "mobile",
"number": "+55 99720-0002"
},
{
"type": "other",
"number": "+55 99720-0003"
}
],
"email_addresses": [
{
"type": "personal",
"address": "timothy.philips@gmail.com"
},
{
"type": "work",
"address": "timothy.philips@yourcompany.com"
}
],
"profile_links": [
{
"type": "github",
"url": "https://github.com/timothyphilips12345"
},
{
"type": "linked_in",
"url": "https://www.linkedin.com/in/timothy-philips-12345"
},
{
"type": "twitter",
"url": "https://twitter.com/timothyphilips12345"
}
],
"employment": [
{
"id": "bpbREEkHTgSkQO382NO103",
"employer": "Revel",
"positions": [
{
"id": "asGdoXTA1eeyb8kfd2zGbr",
"title": "Senior Software Engineer",
"start_date": "2019-01-01",
"end_date": "2019-12-31"
},
{
"id": "dDd0-Q-RvbY5lE110tq0V1",
"title": "Software Engineer",
"start_date": "2018-01-01",
"end_date": "2018-12-31"
},
{
"id": "aaM-99b79fjz5lG6V26V_u",
"title": "Intern",
"start_date": "2017-01-01",
"end_date": "2017-12-31"
}
]
},
{
"id": "bsw47qSPLaeR5mQMxiBnhX",
"employer": "YourCompany",
"positions": []
}
],
"education": [
{
"id": "bCLMQzRTbjsjGuPIHa6yqM",
"school_name": "UFPR",
"graduation_date": "2016-12-31",
"degree": "Masters",
"degree_major": "Science of Computing"
},
{
"id": "aTGq4hU19ayP07mwP-st2D",
"school_name": "UDESC",
"graduation_date": "2015-12-31",
"degree": "Bachelors",
"degree_major": "Computer Science"
}
],
"applications": [
{
"id": "ck5QkojinaJ6sPbmgFzYqB",
"status": "new",
"stage": null,
"job": {
"id": "deuV1SSDfag4xah7Hi3evR",
"title": "Senior Software Engineer",
"internal_title": null,
"requisition_number": "0001",
"status": "open"
},
"created_on": "2023-05-03T18:38:40Z",
"updated_on": "2023-05-03T18:38:40Z"
}
],
"created_on": "2023-05-03T18:38:39Z",
"updated_on": "2023-05-03T18:38:40Z"
}
Get an existing candidate.
HTTP Request
GET /v2/candidates/{candidate_id}
Parameters
- candidate_id required, string
- Candidate’s unique identifier.
Create Candidate
curl -X POST https://api.jobscore.com/v2/candidates \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"first_name": "Timothy",
"last_name": "Philips",
"source_type": "email",
"source_detail": {
"referral_first_name": "John",
"referral_last_name": "Doe",
"referral_email": "john.doe@outlook.com"
},
"address": {
"country": "US",
"state": "California",
"city": "San Francisco",
"postal_code": "94105",
"street1": "123 Main St",
"street2": "Apt 1"
},
"email_addresses": [
{ "type": "personal", "email": "timothy.philips@gmail.com" },
{ "type": "work", "email": "timothy.philips@yourcompany.com" }
],
"phone_numbers": [
{ "type": "home", "number": "+55 99720-0001" },
{ "type": "mobile", "number": "+55 99720-0002" },
{ "type": "other", "number": "+55 99720-0003" }
],
"tags": ["golang", "ruby", "typescript"],
"profile_links": [
{ "url": "https://www.linkedin.com/in/timothy-philips-12345" },
{ "url": "https://github.com/timothyphilips12345" },
{ "url": "https://twitter.com/timothyphilips12345" }
],
"employment": [
{
"employer": "Revel",
"positions": [
{
"title": "Intern",
"start_date": "2017-01-01",
"end_date": "2017-12-31"
},
{
"title": "Software Engineer",
"start_date": "2018-01-01",
"end_date": "2018-12-31"
},
{
"title": "Senior Software Engineer",
"start_date": "2019-01-01",
"end_date": "2019-12-31"
}
]
},
{ "employer": "YourCompany" }
],
"education": [
{
"school_name": "UDESC",
"graduation_date": "2015-12-31",
"degree": "bachelors",
"degree_major": "Computer Science"
},
{
"school_name": "UFPR",
"graduation_date": "2016-12-31",
"degree": "masters",
"degree_major": "Science of Computing"
}
],
"application": { "job_id": "deuV1SSDfag4xah7Hi3evR" }
}
Create a new candidate profile. See an example of the request on the right.
HTTP Request
POST /v2/candidates
It’s possible to assign a candidate to a job on the same request by populating
application.job_id
. It’s also possible to do it in a separate request by
using the Create Application endpoint.
To attach a resume, a second request should be made to the Upload Document endpoint.
Note that there is no uniqueness validation for candidates added through the
API. JobScore will aynchronously check if the candidate is a duplicate and show
a warning message to the users asking whether they want to merge the duplicates
or not. If you want to check whether a candidate is a duplicate before adding
them, we suggest using the Candidate List endpoint
filtering by email_addresses[]
.
Request Body
The candidate’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- first_name required, string
- First name.
- last_name required, string
- Last name.
- source_type
-
Source type.
Can be one of:network
,website
,job_board
,referral
,social
,email
,event
,user
,internal
,database
,search_firm
orother
.
If omitted,other
will be assigned by default, withAPI
as the detail. - source_detail object
-
- <additional fields>
- Specific sources accept, and in some cases require specific additional fields. See the Candidate Source Detail Object section for details.
- address object
-
- country string
- Country code, 2 letters.
- state string
-
State name. If country is
US
, must be a valid 2 letters state, otherwise it is free text. - city string
- City name.
- postal_code number
-
Postal code or Zip code. If country is
US
, must be Zip-5 or Zip-9. - street1 string
- Street address, line 1.
- street2 string
- Street address, line 2.
- email_addresses required, list
-
- type string
-
Email address type. Can be
personal
orwork
. Only a single email address of each type is allowed. - address string
- Email address.
- phone_numbers list
-
- type string
-
Phone type. Can be
home
,mobile
orother
. Only a single phone number of each type is allowed. - number number
- Phone number.
- tags list
- Tags provide additional context or information about candidates. They are a great way to group or categorize candidates with specific attributes. To add a tag to a candidate, the tag has to be previously created in the employer account. To get a list of available tags see the List Tags endpoint.
- profile_links list
-
- url string
- Profile URL.
- employment list
-
- employer string
- Employer name.
- positions list
-
- title string
- Job title name.
- start_date string
-
Start date in
YYYY-MM-DD
format. - end_date string
-
End date in
YYYY-MM-DD
format.
- education list
-
- school_name string
- School or college name.
- graduation_date string
-
Graduation date in
YYYY-MM-DD
format. - degree string
-
Degree type. Must be one of:
certification
,some_high_school
,high_school
,vocational
,associates
,some_college
,bachelors
,some_post_graduate
,masters
,professional
,doctorate
orpostdoctorate
. - degree_major string
- Degree description.
- application object
-
- job_id string
- The job ID to assign this candidate into. Check out the Jobs section to see how you can fetch a list of existing jobs.
Update Candidate
curl -X PATCH https://api.jobscore.com/v2/candidates/{candidate_id} \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"first_name": "Timothy",
"email_addresses": [
{ "type": "personal", "email": "timothy.philips@gmail.com" },
{ "type": "work", "email": null }
]
}
Update a candidate profile. See an example of the request to the right.
HTTP Request
PATCH /v2/candidates/{candidate_id}
Use this endpoint to update a given candidate.
Please note some differences compared to the Create Candidate endpoint:
- Only the attributes included in the JSON request body will be updated. Omitted attributes will be left untouched.
- If
null
or[]
(for lists) is passed for a given attribute, the attribute will be cleared (unless if required, in which case you get a validation error). - For attributes which are lists, like
tags
,profile_links
,employment
andeducation
, the entire list will be replaced by the new one passed in the body.email_addresses
andphone_numbers
are exceptions to this rule (only the corresponding email or phone type will be replaced, as only one value per type is allowed). - It’s not possible to assign a candidate to a job via the update candidate call. To do so, use the Create Application endpoint.
Request Body
The candidate’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- first_name string
- First name.
- last_name string
- Last name.
- source_type
-
Source type.
Can be one of:network
,website
,job_board
,referral
,social
,email
,event
,user
,internal
,database
,search_firm
orother
.
If omitted,other
will be assigned by default, withAPI
as the detail. - source_detail object
-
- <additional fields>
- address object
-
- country string
- Country code, 2 letters.
- state string
-
State name. If country is
US
, must be a valid 2 letters state, otherwise it is free text. - city string
- City name.
- postal_code number
-
Postal code or Zip code. If country is
US
, must be Zip-5 or Zip-9. - street1 string
- Street address, line 1.
- street2 string
- Street address, line 2.
- email_addresses list
-
- type string
-
Email address type. Can be
personal
orwork
. Only a single email address of each type is allowed. - address string
- Email address.
- phone_numbers list
-
- type string
-
Phone type. Can be
home
,mobile
orother
. Only a single phone number of each type is allowed. - number number
- Phone number.
- tags list
- Tags provide additional context or information about candidates. They are a great way to group or categorize candidates with specific attributes. To add a tag to a candidate, the tag has to be previously created in the employer account. To get a list of available tags see the List Tags endpoint.
- profile_links list
-
- url string
- Profile URL.
- employment list
-
- employer string
- Employer name.
- positions list
-
- title string
- Job title name.
- start_date string
-
Start date in
YYYY-MM-DD
format. - end_date string
-
End date in
YYYY-MM-DD
format.
- education list
-
- school_name string
- School or college name.
- graduation_date string
-
Graduation date in
YYYY-MM-DD
format. - degree string
-
Degree type. Must be one of:
certification
,some_high_school
,high_school
,vocational
,associates
,some_college
,bachelors
,some_post_graduate
,masters
,professional
,doctorate
orpostdoctorate
. - degree_major string
- Degree description.
Candidate EEO
Equal Employment Opportunity (EEO) reporting is required of every business with 15+ employees in the USA. You can use this endpoint to retrieve EEO information provided by candidates when applying. Read more about EEO here.
The Candidate EEO Object
For every attribute below, an object will be returned with id
and
response
properties, with the possible values describe below.
null
will be returned if the information is unavailable
(EEO is disabled in the account or job, or candidate was entered manually by an
employee, for example).
- candidate_id string
- The candidate ID.
- gender object
-
- decline_to_identify
- “I don’t wish to answer”
- female
- “Female”
- male
- “Male”
- race object
-
- decline_to_identify
- “I don’t wish to answer”
- white
- “White (Not of Hispanic Origin)”
- black
- “Black or African American (Not of Hispanic Origin)”
- hispanic
- “Hispanic or Latino”
- asian
- “Asian (Not of Hispanic Origin)”
- pacific_islander
- “Pacific Islander (Not of Hispanic Origin)”
- american_indian
- “American Indian (Not of Hispanic Origin)”
- native_alaskan
- “Native Alaskan (Not of Hispanic Origin)”
- native_hawaiian
- “Native Hawaiian (Not of Hispanic Origin)”
- two_or_more
- “Two or more races (Not of Hispanic Origin)”
- veteran object
-
- decline_to_identify
- “Decline to Identify”
- disabled_vet
- “Disabled Veteran”
- separated_vet
- “Recently separated Veteran”
- active_duty_vet
- “Active duty, wartime, or campaign badge Veteran”
- medal_vet
- “Armed Forces service medal Veteran”
- one_or_more_vet
- “One or more classifications of protected Veterans listed above”
- other_protected_vet
- “Other protected Veteran”
- not_vet
- “I am not a Protected Veteran”
- disability object
-
- decline_to_identify
- “I do not want to answer”
- disabled
- “Yes, I have a disability, or have had one in the past”
- not_disabled
- “No, I do not have a disability and have not had one in the past”
List Candidate EEO
curl https://api.jobscore.com/v2/eeo \
-H 'Authorization: Token token={your_token}'
{
"items": [
{
"candidate_id": "d0_8lowYWr67Y-dK3BIXoC",
"gender": {
"id": "male",
"response": "Male"
},
"race": {
"id": "black",
"response": "Black or African American (Not of Hispanic Origin)"
},
"veteran": {
"id": "disabled_vet",
"response": "Disabled Veteran"
},
"disability": {
"id": "disabled",
"response": "Yes, I have a disability, or have had one in the past"
}
},
{
"candidate_id": "cMCMDr1tjl_QJq7wO_dH_-",
"gender": null,
"race": null,
"veteran": null,
"disability": null
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 2,
"per_page": 25
}
}
EEO information for candidates.
HTTP Request
GET /v2/eeo
Parameters
These parameters should be given via query string.
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
full_name
,created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - job_statuses[]
-
Filter by candidates assigned to jobs in specific job statuses.
This must be:
draft
,internal
,open
,on_hold
,closed
orfilled
. - job_ids[]
- Filter by candidates assigned to specific jobs. Check out the Jobs section to see how to fetch the list of available jobs.
- statuses[]
-
Filter by candidates assigned to specific statuses.
This must be:
new
,active
,declined
,withdrawn
orhired
. - stage_ids[]
- Filter by candidates assigned to specific stages. This must be a Workflow Stage ID as returned by List Workflow Stages.
- tags[]
- Filter by candidates with specific tags.
- sources[]
-
Filter by candidates with specific sources.
This must be:
network
,website
,job_board
,referral
,social
,email
,event
,user
,internal
,database
,search_firm
orother
. - received_after
- Filter by candidates received starting on a given date. Should be on
YYYY-MM-DD
format. - received_before
- Filter by candidates received before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by candidates updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by candidates updated before a given date. Should be on
YYYY-MM-DD
format. - email_addresses[]
- Filter candidates by email addresses.
Get Candidate EEO
curl https://api.jobscore.com/v2/candidates/{candidate_id}/eeo \
-H 'Authorization: Token token={your_token}'
{
"candidate_id": "d0_8lowYWr67Y-dK3BIXoC",
"gender": {
"id": "male",
"response": "Male"
},
"race": {
"id": "black",
"response": "Black or African American (Not of Hispanic Origin)"
},
"veteran": {
"id": "disabled_vet",
"response": "Disabled Veteran"
},
"disability": {
"id": "disabled",
"response": "Yes, I have a disability, or have had one in the past"
}
}
{
"candidate_id": "d0_8lowYWr67Y-dK3BIXoC",
"gender": null,
"race": null,
"veteran": null,
"disability": null
}
Get EEO information for a candidate.
HTTP Request
GET /v2/candidates/{candidate_id}/eeo
Parameters
- candidate_id required, string
- Candidate’s unique identifier.
Departments
Departments in JobScore represent the different parts of your organization. Departments are a way to classify and group jobs so job seekers can easily find the jobs appropriate for them. Typical department names include Sales, Marketing, Operations, Finance, etc.
The Department Object
Attributes
- name string
- Department name.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last update time.
List Departments
curl https://api.jobscore.com/v2/departments \
-H 'Authorization: Token token={your_token}'
Get list of departments.
{
"items": [
{
"id": "bBkaNsvgCr3OP1eJe4aGWH",
"name": "Customer Success",
"created_on": "2022-04-26T09:54:28Z",
"updated_on": "2022-05-04T14:24:02Z"
},
{
"id": "agHLvoZFSr3lNCaaWPX6Zm",
"name": "Engineering",
"created_on": "2022-04-21T02:52:37Z",
"updated_on": "2022-04-21T02:52:37Z"
},
{
"id": "dNF4xI9Dqr3lVuaaWPX6Zm",
"name": "Marketing",
"created_on": "2022-04-21T15:45:59Z",
"updated_on": "2022-04-21T15:45:59Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 3,
"per_page": 25
}
}
HTTP Request
GET /v2/departments
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
name
,created_on
orupdated_on
. The default isname
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - created_after
- Filter by departments created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by departments created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by departments updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by departments updated before a given date. Should be on
YYYY-MM-DD
format.
Get Department
curl https://api.jobscore.com/v2/departments/{department_id} \
-H 'Authorization: Token token={your_token}'
Get existing department.
{
"id": "agHLvoZFSr3lNCaaWPX6Zm",
"name": "Engineering",
"created_on": "2022-04-21T02:52:37Z",
"updated_on": "2022-04-21T02:52:37Z"
}
HTTP Request
GET /v2/departments/{department_id}
Parameters
- department_id required, uid
- Department’s unique identifier.
Create Department
curl -X POST https://api.jobscore.com/v2/departments \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"name": "Sales"
}
Create new department.
HTTP Request
POST /v2/departments
Request Body
The department’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- name required, string
- Department name.
Disposition Codes
A disposition code is the reason a candidate didn’t work out. Disposition codes are required for OFCCP compliance and each code represents a granular, specific reason why your company chooses to decline (reject) someone for a specific job (e.g. doesn’t meet minimum qualifications) or why a candidate chooses chooses to withdraw from your interview process (e.g. didn’t want to travel).
The Disposition Code Object
Attributes
- id uid
- Disposition code’s unique identifier.
- name string
- Disposition code name.
- type string, readonly
-
Disposition code type.
Can be
declined
orwithdrawn
. - created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
List Disposition Codes
curl https://api.jobscore.com/v2/disposition_codes \
-H 'Authorization: Token token={your_token}'
{
"items": [
{
"id": "ahA_S0vTjgZjqKpJPUhUJr",
"name": "Accepted another job",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "aDgjEuVhDh5lqH-Atyqx3R",
"name": "Applied after offer was extended",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "bz1PvuKaPiHy8A8dKv1pfU",
"name": "Doesn't meet minimum qualifications",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "dFjGsHpJ5jCBxZKyAeIE9E",
"name": "Failed to show for interview",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "ct6E-GOOzl6lSlqbyjEpqX",
"name": "More qualified candidate selected",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "dOh_ne_1TkfQW51T9zd54B",
"name": "No Disposition",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "a9c8zdXiDiPQTGLs4j0j_M",
"name": "No Disposition",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "dsLnUdU2LeNlKnkEpkuulZ",
"name": "Not Considered",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "bwsb925-zgKPcZlW6kbJEY",
"name": "Not interested in Job",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "akOZ94Lljjb6XVHvK4_8PD",
"name": "Not interested in salary (too low)",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "bb2uDObLbjAQtfbyUmGjoF",
"name": "Offer rejected by candidate",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "cN3EgLpxrkwOd0ef4Nskac",
"name": "Position on hold / cancelled / not filled",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "c5x4DB5rnoYOBkfxeQ-ZTy",
"name": "Salary Requested is too high",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "dO88oQCFzhnkhRkykT1SQe",
"name": "Unable to contact",
"type": "withdrawn",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"id": "cQ58gfnI9hFBGYLfNL4Iez",
"name": "Unable to work in the United States",
"type": "declined",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 15,
"per_page": 25
}
}
Get list of disposition codes for a specific type.
HTTP Request
GET /v2/disposition_codes
Parameters
These parameters should be given via query string.
- type string
-
Filter for type. Can be
declined
orwithdrawn
. - page number
- Page number. Defaults to 1.
- per_page number
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
name
,created_on
orupdated_on
. The default isname
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by disposition code created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by disposition code created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by disposition code updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by disposition code updated before a given date. Should be on
YYYY-MM-DD
format.
Documents
Documents can represent candidates’ resumes, cover letters, offer letters, note attachments, task attachments or email attachments. They are always associated with a candidate. Resumes and cover letters may be added to applications.
A candidate may have more than one resume attached, but has only one primary resume.
The Document Object
- type string
-
Document type. Can be one of:
primary_resume
,resume
,email_attachment
,task_attachment
,note_attachment
,cover_letter
,offer_letter
,signed_offer_letter
orother
. - filename string
- The document file name.
- content_type string
- The file content type.
- filesize object
-
- bytes number
- The file size in number of bytes.
- filesize string
- The file size in human readable format.
- is_private string
- Whether the document is private or not.
- job_id uid
- Unique identifier for the job associated with this document.
- application_id uid
- Unique identifier for the application associated with this document.
- created_on timestamp, readonly
- Document creation timestamp.
- updated_on timestamp, readonly
- Document update timestamp.
List Documents
curl https://api.jobscore.com/v2/candidates/{candidate_id}/documents \
-H 'Authorization: Token token={your_token}'
{
"items": [
{
"id": "aZ-N5f7PbcdRtmwENGhfye",
"type": "resume",
"filename": "resume.pdf",
"content_type": "application/pdf",
"filesize": {
"bytes": 4911,
"human": "4.91 kB"
},
"is_private": false,
"job_id": null,
"application_id": null,
"created_on": "2023-05-10T17:34:27Z",
"updated_on": "2023-05-10T17:34:27Z"
},
{
"id": "aZ-N5f7PbcdRtmwENGhfyf",
"type": "cover_letter",
"filename": "cover_letter.txt",
"content_type": "application/pdf",
"filesize": {
"bytes": 4911,
"human": "4.91 kB"
},
"is_private": false,
"job_id": "aZ-N5f7PbcdRtmwENGhfyh",
"application_id": "aZ-N5f7PbcdRtmwENGhfyg",
"created_on": "2023-05-10T17:34:27Z",
"updated_on": "2023-05-10T17:34:27Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 2,
"per_page": 25
}
}
HTTP Request
GET /v2/candidates/{candidate_id}/documents
Parameters
- candidate_id required, string
- The ID for the candidate which you want to see documents for.
- include_private boolean
-
Include documents from private notes and private emails. Default is
false
. - page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - created_after
- Filter by documents created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by documents created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by documents updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by documents updated before a given date. Should be on
YYYY-MM-DD
format.
Get Document
curl https://api.jobscore.com/v2/documents/{document_id} \
-H 'Authorization: Token token={your_token}'
{
"id": "aZ-N5f7PbcdRtmwENGhfye",
"type": "resume",
"filename": "resume.pdf",
"content_type": "application/pdf",
"filesize": {
"bytes": 4911,
"human": "4.91 kB"
},
"is_private": false,
"job_id": null,
"application_id": null,
"created_on": "2023-05-10T17:34:27Z",
"updated_on": "2023-05-10T17:34:27Z"
}
HTTP Request
GET /v2/documents/{document_id}
Parameters
- document_id required, uid
- The ID for the document which you want to fetch.
- include_private boolean
-
Include documents from private notes and private emails. Default is
false
.
Download Document
curl https://api.jobscore.com/v2/documents/{document_id}/download \
-H 'Authorization: Token token={your_token}' \
--output {file_path}
Use this endpoint to download a document. The actual binary content of the file
will be returned. The Content-Type
header will be set according the file type.
To see more information about this file, use the
Get Document endpoint.
HTTP Request
GET /v2/documents/{document_id}/download
Parameters
- document_id required, uid
- The ID for the document which you want to download.
Upload Document
curl -X POST https://api.jobscore.com/v2/documents \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
{
"candidate_id": "{candidate_id}",
"type": "resume",
"filename": "resume.pdf",
"content": "{file_content}"
}
Use this endpoint to upload a document to a candidate or candidate note.
We automatically detect the content type of the file, and it must match the
filename extension. For example, if you’re sending a file of type
application/pdf
and filename must end with .pdf
.
HTTP Request
POST /v2/documents
Request Body
The document’s data you are about to upload must be sent via Request Body as a JSON-formatted object.
Parameters
- candidate_id required, string
- The ID for the candidate which you want to upload the document to.
- type required, string
-
Document type. Must be one of:
resume
,note_attachment
orother
. - note_id string
-
The candidate note ID. Required if the document type is
note_attachment
. - filename required, string
- The document file name.
- content required, string
- The document content encoded in base64.
Jobs
Jobs represent specific roles you are trying to hire candidates for.
In JobScore there are 6 different job statuses: draft
, internal
, open
, on_hold
, closed
and filled
.
- Draft Jobs are jobs that are not ready to start receiving candidate applies.
- Internal Jobs are roles you are trying to fill with current company employees. They are not displayed in your public careers site, but are live on your internal job board if you have set one up, and can applied to by anyone with the URL.
- Open Jobs are roles you are actively trying to fill, and will appear publicly on your careers site.
- On Hold Jobs are roles that you are not working on yet or that you have paused working on for a while.
- Closed Jobs are roles that you tried to fill but have stopped working on and don’t plan to reopen or work on anymore.
- Filled Jobs are roles where you have successfully hired a candidate.
The Job Object
- title string
- Publicly displayed job title.
- internal_title string
- Optional internal job title, as displayed in JobScore employer UI and reports.
- requisition_number string
- Job requisition number.
- description_text string, readonly
- Job description in text form.
- description_html string
- Job description in HTML form.
- status string
-
Job status. One of:
draft
,internal
,open
,on_hold
,closed
orfilled
. - job_types list
-
List of job types.
List of job types. Can be one or more of:
full_time
,part_time
,contract
,temporary
,temp_to_perm
,internship
,volunteer
. - remote_type string
-
Can be one of:
no
(must work onsite),yes
(can work entirely remotely),hybrid
(can work remotely sometimes). - desired_experience object
-
Desired career level of applicants for this job.
Can be one of:
student_high_school
,student
,entry_level
,mid_level
,experienced_non_manager
,manager
,executive
,senior executive
. - openings object
-
Object representation of job’s current openings.
- number_of_openings integer
- openings list
- compensation object
-
- currency string
- Currency is represented by its ISO 4217 code format.
- public_salary_minimum_in_cents integer
- Public salary minumum in cents.
- public_salary_maximum_in_cents integer
- Public salary maximum in cents.
- public_compensation_interval string
-
The payrate for this job, visible on your careers site and job boards. Can be one of:
per hour
,per day
,per week
,per month
andper year
. - private_salary_minimum_in_cents integer
- Private salary minumum in cents.
- private_salary_maximum_in_cents integer
- Private salary maximum in cents.
- private_compensation_interval string
-
The payrate for this job, used for internal purposes only. It is only visible by users with confidential access to this job. Valid options are:
per hour
,per day
,per week
,per month
andper year
.
- location object
- The location for this job.
- department object
- The department for this job.
- custom_fields list
-
List of custom field values for this job.
- id string
- type string
- Custom job field name.
- value string
- String representation of custom job field value.
- type string
-
Custom job field type. Can be one of:
text
,number
,checkbox
,date
,multiple_choice
,compensation_range
,currency
.
- workflow_stages list
- List of workflow stages for this job.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
List Jobs
curl https://api.jobscore.com/v2/jobs \
-H 'Authorization: Token token={your_token}'
Get list of jobs.
{
"items": [
{
"id": "cHpvBM9EWr3lkFaaWPX6Zm",
"title": "Account Executive",
"internal_title": null,
"requisition_number": "0001",
"description_text": "About us:\n\nAt Revel, we believe there is a better way to do marketing. Marketing that adds value, and is enjoyable, not invasive. We're passionate about it, and our mission is to help companies achieve it.",
"description_html": "<h3>About us:</h3><p>At Revel, we believe there is a better way to do marketing. Marketing that adds value, and is enjoyable, not invasive. We're passionate about it, and our mission is to help companies achieve it.</p>",
"status": "closed",
"job_types": ["full_time"],
"remote_type": "no",
"desired_experience": "experienced",
"openings": {
"number_of_openings": 1,
"openings": [
{
"opening_id": "0007a",
"reason_for_hire": null,
"budget_id": "",
"hired_candidate": {
"id": null,
"name": null
},
"target_start_date_on": null,
"created_on": "2022-04-21T15:48:54Z"
}
]
},
"compensation": {
"currency": null,
"public_salary_minimum_in_cents": 70000,
"public_salary_maximum_in_cents": 100000,
"public_compensation_interval": "per year",
"private_salary_minimum_in_cents": 70000,
"private_salary_maximum_in_cents": 100000,
"private_compensation_interval": "per year"
},
"location": {
"id": "agHFVAZFSr3lNCaaWPX6Zm",
"country": "US",
"state": "CA",
"city": "San Francisco",
"postal_code": "94111",
"street1": "12 Singular Rd."
},
"department": {
"id": "dIQRXw9EOr3lVuaaWPX6Zm",
"name": "Sales"
},
"job_field_answers": [
{
"id": "bPMJAMDF4r6PpadK3BIXoC",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJma2YkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Bonus"
}
},
{
"id": "bPLVoCDF4r6PpadK3BIXoC",
"type": "number",
"answer": null,
"job_field": {
"id": "bSJnIQYkGr6jjNeJii1Cgg",
"type": "number",
"question": "Stock Options"
}
},
{
"id": "bPL05UDF4r6PpadK3BIXoC",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJpdIYkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Relocation Assistance"
}
},
{
"id": "bPL58IDF4r6PpadK3BIXoC",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJqGwYkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Commission"
}
},
{
"id": "bPL_igDF4r6PpadK3BIXoC",
"type": "multiple_choice",
"answer": null,
"job_field": {
"id": "aCBqFEh9Or6O-9dGB-6ByU",
"type": "multiple_choice",
"question": "Bonus Interval"
}
},
{
"id": "bPMEtADF4r6PpadK3BIXoC",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJsc8YkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Sign On Bonus"
}
}
],
"workflow_stages": [
{
"id": "dsMGYmvgyr3OP1eJe4aGWH",
"name": "Schedule Recruiter Screen"
},
{
"id": "dzvE_Wvgyr3OP1eJe4aGWH",
"name": "Recruiter Screen"
},
{
"id": "bucPaiEXGr4P0EiGakhiyv",
"name": "Schedule Manager Interview"
},
{
"id": "bIIKoEEXGr4P0EiGakhiyv",
"name": "Manager Interview"
},
{
"id": "dG4lTcvgyr3OP1eJe4aGWH",
"name": "Schedule Onsite Interview"
},
{
"id": "agCOiMZFSr3lNCaaWPX6Zm",
"name": "Onsite Interview"
},
{
"id": "aRgKeAEXKr4P0EiGakhiyv",
"name": "Check References"
},
{
"id": "aGgzfevgCr3Pp_eJe4aGWH",
"name": "Offer"
},
{
"id": "c_KkaGXyyr3Bq_aaWPjCfa",
"name": "On Hold"
}
]
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1,
"per_page": 25
}
}
HTTP Request
GET /v2/jobs
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
title
,created_on
orupdated_on
. The default istitle
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by jobs created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by jobs created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by jobs updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by jobs updated before a given date. Should be on
YYYY-MM-DD
format.
Get Job
curl https://api.jobscore.com/v2/jobs/{job_id} \
-H 'Authorization: Token token={your_token}'
Get existing job.
{
"id": "aHa5OmZFWr3i5taaWPX6Zm",
"title": "Software Engineer",
"internal_title": null,
"requisition_number": "0002",
"description_text": "About us:\n\nAt Revel, we believe there is a better way to do marketing. Marketing that adds value, and is enjoyable, not invasive. We're passionate about it, and our mission is to help companies achieve it.",
"description_html": "<h3>About us:</h3><p>At Revel, we believe there is a better way to do marketing. Marketing that adds value, and is enjoyable, not invasive. We're passionate about it, and our mission is to help companies achieve it.</p>",
"status": "closed",
"job_types": ["full_time"],
"remote_type": "no",
"desired_experience": "experienced",
"openings": {
"number_of_openings": 1,
"openings": [
{
"opening_id": "0001a",
"reason_for_hire": null,
"budget_id": "",
"hired_candidate": {
"id": null,
"name": null
},
"target_start_date_on": null,
"created_on": "2022-04-21T02:53:17Z"
}
]
},
"compensation": {
"currency": "USD",
"public_salary_minimum_in_cents": 70000,
"public_salary_maximum_in_cents": 100000,
"public_compensation_interval": "per year",
"private_salary_minimum_in_cents": 70000,
"private_salary_maximum_in_cents": 100000,
"private_compensation_interval": "per year"
},
"location": {
"id": "agHFVAZFSr3lNCaaWPX6Zm",
"country": "US",
"state": "CA",
"city": "San Francisco",
"postal_code": "94111",
"street1": "12 Singular Rd."
},
"department": {
"id": "agHLvoZFSr3lNCaaWPX6Zm",
"name": "Engineering"
},
"job_field_answers": [
{
"id": "cuQdH42byr6ROsdSk8YT7m",
"type": "number",
"answer": null,
"job_field": {
"id": "bSJnIQYkGr6jjNeJii1Cgg",
"type": "number",
"question": "Stock Options"
}
},
{
"id": "cuQjBy2byr6ROsdSk8YT7m",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJpdIYkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Relocation Assistance"
}
},
{
"id": "cuQphs2byr6ROsdSk8YT7m",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJqGwYkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Commission"
}
},
{
"id": "cuQu2Y2byr6ROsdSk8YT7m",
"type": "multiple_choice",
"answer": null,
"job_field": {
"id": "aCBqFEh9Or6O-9dGB-6ByU",
"type": "multiple_choice",
"question": "Bonus Interval"
}
},
{
"id": "cuQDME2byr6ROsdSk8YT7m",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJsc8YkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Sign On Bonus"
}
},
{
"id": "cuQJq-2byr6ROsdSk8YT7m",
"type": "currency",
"answer": null,
"job_field": {
"id": "bSJma2YkGr6jjNeJii1Cgg",
"type": "currency",
"question": "Bonus"
}
}
],
"workflow_stages": [
{
"id": "dsMGYmvgyr3OP1eJe4aGWH",
"name": "Schedule Recruiter Screen"
},
{
"id": "dzvE_Wvgyr3OP1eJe4aGWH",
"name": "Recruiter Screen"
},
{
"id": "bucPaiEXGr4P0EiGakhiyv",
"name": "Schedule Manager Interview"
},
{
"id": "bIIKoEEXGr4P0EiGakhiyv",
"name": "Manager Interview"
},
{
"id": "dG4lTcvgyr3OP1eJe4aGWH",
"name": "Schedule Onsite Interview"
},
{
"id": "agCOiMZFSr3lNCaaWPX6Zm",
"name": "Onsite Interview"
},
{
"id": "aRgKeAEXKr4P0EiGakhiyv",
"name": "Check References"
},
{
"id": "aGgzfevgCr3Pp_eJe4aGWH",
"name": "Offer"
},
{
"id": "c_KkaGXyyr3Bq_aaWPjCfa",
"name": "On Hold"
}
]
}
HTTP Request
GET /v2/jobs/{job_id}
Parameters
- job_id required, uid
- Job’s unique identifier.
Locations
Locations are where a job is located. It’s where a candidate will work when you hire them.
- Locations require a street address and postal code. This information is required because some job boards require it to post on their site.
- Locations may have an external name. When you add an external name this is what job seekers will see when they view and apply to jobs. External names are very useful when you need to publish a job as remote / work from home.
- Locations may also have an internal name. This is what your team will see when they use the application. Internal names are very useful when you have more than one office or store in the same city.
The Location Object
- country string
- Country code, 2 letters.
- state string
- State name. If country is “US”, must be a valid 2 letters state, otherwise it is free text.
- city string
- City name.
- postal_code string
- Postal code or Zip code. If country is “US”, must be Zip-5 or Zip-9.
- street1 string
- Street Address 1.
- street2 string
- Street Address 2.
- latitude float, readonly
- Location’s latitude (in degrees).
- longitude float, readonly
- Location’s longitude (in degrees).
- internal_name string
-
Internal nickname for the location. This is what employees see in filters and reports. Customizing the internal name of a location overrides the standard “city, state” location display inside of JobScore for your employees. Most employers only customize the internal name if they have more than one location in the same city. If left
null
, it will show “city, state”. - external_name string
-
Public nickname for the location. This is what job seekers see when they apply. Customizing the external name of a location overrides the standard “city, state” location display on your careers site seen by job seekers. Most employers customize the external name if they want to publish a job with “no location” where candidates can work remotely from anywhere. If left
null
, it will show “city, state”. - created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last update time.
List Locations
curl https://api.jobscore.com/v2/locations \
-H 'Authorization: Token token={your_token}'
List all locations in your company.
{
"items": [
{
"id": "apEdAGvgGr3OP1eJe4aGWH",
"country": "US",
"state": "NY",
"city": "New York",
"postal_code": "10018",
"street1": "24 West 40th Street",
"street2": "11th floor",
"latitude": 40.755101,
"longitude": -73.99337,
"internal_name": null,
"external_name": null,
"created_on": "2022-04-26T09:54:32Z",
"updated_on": "2022-04-26T09:54:32Z"
},
{
"id": "aXfyqeJVCr6PardK3BIXoC",
"country": "US",
"state": "MI",
"city": "Novi",
"postal_code": "48375",
"street1": "",
"street2": "",
"latitude": 42.4604,
"longitude": -83.4577,
"internal_name": "Novi branch",
"external_name": "Novi Branch",
"created_on": "2022-05-03T21:17:13Z",
"updated_on": "2022-05-03T21:17:13Z"
},
{
"id": "agHFVAZFSr3lNCaaWPX6Zm",
"country": "US",
"state": "CA",
"city": "San Francisco",
"postal_code": "94111",
"street1": "12 Singular Rd.",
"street2": "",
"latitude": 37.798228,
"longitude": -122.40027,
"internal_name": null,
"external_name": null,
"created_on": "2022-04-21T02:52:37Z",
"updated_on": "2022-04-21T14:31:04Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 3,
"per_page": 25
}
}
HTTP Request
GET /v2/locations
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
address
,created_on
orupdated_on
. The default isaddress
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by locations created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by locations created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by locations updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by locations updated before a given date. Should be on
YYYY-MM-DD
format.
Get Location
curl https://api.jobscore.com/v2/locations/{location_id} \
-H 'Authorization: Token token={your_token}'
Get existing location.
{
"id": "apEdAGvgGr3OP1eJe4aGWH",
"country": "US",
"state": "NY",
"city": "New York",
"postal_code": "10018",
"street1": "24 West 40th Street",
"street2": "11th floor",
"latitude": 40.755101,
"longitude": -73.99337,
"internal_name": null,
"external_name": null,
"created_on": "2022-04-26T09:54:32Z",
"updated_on": "2022-04-26T09:54:32Z"
}
HTTP Request
GET /v2/locations/{location_id}
Parameters
- location_id required, uid
- Location’s unique identifier.
Notes
Notes are how your team enters information about candidates and discusses them.
- Candidate notes are stored as HTML so your team can use bolding, bullet points, numbered lists and more when they add feedback. Notes can also have attached documents.
- The ability to read a candidate note may be restricted by making it private. A private note is only visible to its author and users who have been granted access.
- A candidate note record may represent a simple note added by an employer user, or can contain interview feedback from an empoyer user including their candidate ratings.
The Note Object
Attributes
- content_html string
- Note’s content in HTML format.
- is_private boolean
-
Whether or not this note is private. Default is
false
. - job_id uid
- Unique identifier for the job associated with this note, when applicable.
- application_id uid
- Unique identifier for the application associated with this note, when applicable.
- type string
-
Note type. Can be either
note
orinterview_feedback
. - ratings list
-
Ratings information. Only applicable when
type
isinterview_feedback
.- name string
- Rating name.
- description string
- Rating description.
- score float
-
Rating score. Ranges from
1.0
to4.0
.
- author object
-
Note’s creator.
- first_name string
- Creator’s first name.
- last_name string
- Creator’s last name.
- documents list
- Documents attached to this note.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last update time.
List Notes
curl https://api.jobscore.com/v2/candidates/{candidate_id}/notes \
-H 'Authorization: Token token={your_token}'
Get list of notes for a single candidate.
{
"items": [
{
"id": "atu_NUEoir6Qd-dK3BIXoC",
"content_html": "<p>What do you think of this candidate? Please decline or move to offer</p>",
"is_private": false,
"job_id": "b5gW8AbWPa-RINe8is3Zc1",
"application_id": "auZUyIchLpcljbrWCLG-7e",
"type": "note",
"ratings": [],
"user": {
"id": "ctr_o09der3j-maawpx6zm",
"first_name": "Buster",
"last_name": "Wegley"
},
"documents": [],
"created_on": "2022-05-03T14:05:50Z",
"updated_on": "2022-10-20T13:41:52Z"
},
{
"id": "dad8YwC1Kr6OE-dK3BIXoC",
"content_html": "<p>What do you think of this candidate? Please decline or move to schedule recruiter screen.</p>",
"is_private": false,
"job_id": "b5gW8AbWPa-RINe8is3Zc1",
"application_id": "auZUyIchLpcljbrWCLG-7e",
"type": "note",
"ratings": [],
"user": {
"id": "ctr_o09der3j-maawpx6zm",
"first_name": "Buster",
"last_name": "Wegley"
},
"documents": [],
"created_on": "2022-05-03T12:17:46Z",
"updated_on": "2022-10-20T13:41:52Z"
},
{
"id": "dba_zICPWr6Rq4dK3BIXoC",
"content_html": "<p>I've already reached out to this candidate to screen them. Please reply to this email if you have any specific questions you'd like me to ask them.</p>",
"is_private": false,
"job_id": null,
"application_id": null,
"type": "interview_feedback",
"ratings": [
{
"name": "Overall Recommendation",
"description": "Overall impression - how good is this candidate",
"score": 2.5
},
{
"name": "Communication skills",
"description": "Answers with the appropriate level of detail and concision",
"score": 3.2
}
],
"user": {
"id": "ctr_o09der3j-maawpx6zm",
"first_name": "Buster",
"last_name": "Wegley"
},
"documents": [],
"created_on": "2022-05-03T12:03:20Z",
"updated_on": "2022-10-20T13:41:52Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 3,
"per_page": 25
}
}
HTTP Request
GET /v2/candidates/{candidate_id}/notes
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- include_private boolean
-
Include private notes. Default is
false
. - type string
-
Filter by note type. Must be one of:
interview_feedback
ornote
. All note types are returned by default. - sort
-
Sort by attribute.
Must be one of:
created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - created_after
- Filter by notes created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by notes created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by notes updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by notes updated before a given date. Should be on
YYYY-MM-DD
format.
Get Note
curl https://api.jobscore.com/v2/notes/{note_id} \
-H 'Authorization: Token token={your_token}'
Get existing note.
{
"id": "d_n09kmOjcWRLfvpuEvJKc",
"content_html": "Interview notes, see attachment",
"is_private": false,
"job_id": "b5gW8AbWPa-RINe8is3Zc1",
"application_id": "auZUyIchLpcljbrWCLG-7e",
"type": "note",
"ratings": [],
"user": {
"id": "cQOc2oZ30r3l1_aaWPX6Zm",
"first_name": "Joe",
"last_name": "Saluzki"
},
"documents": [
{
"id": "bIHBea2mjnliyhXvxKUmMR",
"type": "note",
"filename": "file.pdf"
}
],
"created_on": "2023-04-18T10:27:59Z",
"updated_on": "2023-04-18T10:27:59Z"
}
HTTP Request
GET /v2/notes/{note_id}
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
- note_id required, uid
- Note’s unique identifier.
- include_private boolean
-
Include private notes. Default is
false
.
Create Note
curl -X POST https://api.jobscore.com/v2/candidates/{candidate_id}/notes \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"content_html": "<p>Interview notes, see attachment</p>",
"creator_id": "{user_id}",
"attachments": [{ "filename": "notes.pdf", "content": "{file_content}" }],
"visibility": {
"private": "true",
"user_ids": ["{user_id_1}", "{user_id_2}"],
"send_email_alerts": "true"
}
}
Create new note for a candidate.
HTTP Request
POST /v2/candidates/{candidate_id}/notes
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
Request Body
The note’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- content_html required, string
-
Contents of the note. HTML is expected. You may opt to send plain text, but it might present formatting issues.
Allowed HTML tags are:<a>
,<b>
,<blockquote>
,<br>
,<em>
,<h1>
,<h2>
,<h3>
,<h4>
,<h5>
,<h6>
,<i>
,<img>
,<li>
,<ol>
,<p>
,<strong>
,<u>
and<ul>
.
Allowed tag attributes are:alt
,href
,src
,target
andtitle
. - creator_id required, uid
- Creating user’s unique identifier.
- job_id uid
- Unique identifier of the job you want to associate with the note.
- attachments list
-
List of documents to attach to this note. Maximum of three attachments per note.
- filename required, string
- The name you want to have on this attachment. Extension must be accordingly to the file content.
- content required, base64-encoded string
- The contents of the file.
- visibility object
-
Note’s visibility attributes.
- private boolean
-
Whether or not this note is private. Default is
false
. - user_ids list
- Users’ unique identifiers which you want this note to be visible by.
- send_email_alerts boolean
- Whether you want or not to send email alerts to the users the note is shared with.
Offers
When you decide you want to hire a candidate, JobScore can help you create and send them an offer letter to review and sign.
The Offer Object
Attributes
- id uid
- Offer’s unique identifier.
- offer_accepted_on timestamp
- Offer acception date.
- offer_extended_on timestamp
- Offer extension date.
- start_date_on timestamp
- Date in which the candidate started the position.
- status string
-
Offer status. One of:
draft
,approved
,extended
,accepted
,rejected
,rescinded
,out_of_sync
orcanceled
. - application object
-
Application related to the offer.
- id uid
- Application unique identifier.
- status string
-
Application status. One of:
new
,active
,declined
,withdrawn
orhired
. - stage string
- Current workflow stage this application is in.
- job object
-
Job related to the application.
- id uid
- Job unique identifier.
- title string
- Job title.
- internal_title string
- Job internal title.
- requisition_number string
- Job requisition number.
- status string
-
Job status. One of:
draft
,internal
,open
,on_hold
,closed
orfilled
.
- candidate object
-
Candidate related to the application.
- id uid
- Candidate unique identifier.
- first_name string
- Candidate first name.
- last_name string
- Candidate last name.
- fields list
-
Offer fields.
- name string
- Offer field name.
- value string
- Offer field value.
- type string
-
Offer field type. Can be one of:
text
,currency
,date
,multiple_choice
,number
,section
oresignature_token
.
- created_on timestamp
- Record creation time.
- updated_on timestamp
- Record last update time.
List Offers
curl https://api.jobscore.com/v2/offers \
-H 'Authorization: Token token={your_token}'
Get list of offers.
{
"items": [
{
"id": "c_EzwOknGr6P4wdK3BIXoC",
"offer_accepted_on": "2022-05-02T12:56:51Z",
"offer_extended_on": "2022-05-02T11:55:27Z",
"start_date_on": "2022-05-02T15:15:01Z",
"status": "accepted",
"application": {
"id": "aMA-wkvgOr3OP1eJe4aGWH",
"status": "hired",
"stage": null,
"candidate": {
"id": "cxTu8__JzghODU3KzP-Oq2",
"first_name": "Robert",
"last_name": "Jennings"
},
"job": {
"id": "anOh8-vgar3PNeeJe4aGWH",
"title": "Marketing Manager",
"internal_title": null,
"requisition_number": "0009",
"status": "filled"
}
},
"values": [
{
"name": "Today's Date",
"value": "12/27/2019"
},
{
"name": "Anticipated Start Date",
"value": "12/28/2019"
},
{
"name": "Candidate Full Name",
"value": "Robert Paulson"
},
{
"name": "Job Title",
"value": "Marketing Manager"
},
{
"name": "Hiring Manager",
"value": "Jack Kennedy"
},
{
"name": "Hiring Manager Title",
"value": "Director of Marketing"
},
{
"name": "Office Location - City, State",
"value": "New York, NY"
},
{
"name": "Compensation Interval",
"value": "per day"
},
{
"name": "Compensation Amount",
"value": "$ 40.00"
},
{
"name": "Headquarter Location - State",
"value": "CA"
},
{
"name": "Company Name",
"value": "Revel"
}
],
"created_on": "2022-05-02T12:02:19Z",
"updated_on": "2022-05-02T12:02:25Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1,
"per_page": 25
}
}
HTTP Request
GET /v2/offers
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
created_on
orupdated_on
. The default iscreated_on
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isdesc
. - created_after
- Filter by offers created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by offers created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by offers updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by offers updated before a given date. Should be on
YYYY-MM-DD
format.
Get Offer
curl https://api.jobscore.com/v2/offers/{offer_id} \
-H 'Authorization: Token token={your_token}'
Get existing offer.
{
"id": "c_EzwOknGr6P4wdK3BIXoC",
"offer_accepted_on": "2022-05-02T12:56:51Z",
"offer_extended_on": "2022-05-02T11:55:27Z",
"start_date_on": "2022-05-02T15:15:01Z",
"status": "accepted",
"application": {
"id": "aMA-wkvgOr3OP1eJe4aGWH",
"status": "hired",
"stage": null,
"candidate": {
"id": "cxTu8__JzghODU3KzP-Oq2",
"first_name": "Robert",
"last_name": "Jennings"
},
"job": {
"id": "anOh8-vgar3PNeeJe4aGWH",
"title": "Marketing Manager",
"internal_title": null,
"requisition_number": "0009",
"status": "filled"
}
},
"values": [
{
"name": "Today's Date",
"value": "12/27/2019"
},
{
"name": "Anticipated Start Date",
"value": "12/28/2019"
},
{
"name": "Candidate Full Name",
"value": "Robert Paulson"
},
{
"name": "Job Title",
"value": "Marketing Manager"
},
{
"name": "Hiring Manager",
"value": "Jack Kennedy"
},
{
"name": "Hiring Manager Title",
"value": "Director of Marketing"
},
{
"name": "Office Location - City, State",
"value": "New York, NY"
},
{
"name": "Compensation Interval",
"value": "per day"
},
{
"name": "Compensation Amount",
"value": "$ 40.00"
},
{
"name": "Headquarter Location - State",
"value": "CA"
},
{
"name": "Company Name",
"value": "Revel"
}
],
"created_on": "2022-05-02T12:02:19Z",
"updated_on": "2022-05-02T12:02:25Z"
}
HTTP Request
GET /v2/offers/{offer_id}
Parameters
- offer_id required, uid
- Offer’s unique identifier.
List Candidate Offers
curl https://api.jobscore.com/v2/candidates/{candidate_id}/offers \
-H 'Authorization: Token token={your_token}'
Get list of offers for a specific candidate.
{
"items": [
{
"id": "btcu0HCBDhCO3Y8-NHwlaI",
"offer_accepted_on": "2023-05-23T04:00:00Z",
"offer_extended_on": "2023-05-22T04:00:00Z",
"start_date_on": "2023-09-30T04:00:00Z",
"status": "draft",
"values": [
{
"name": "Today's Date",
"value": "09/29/2022"
},
{
"name": "Candidate Full Name",
"value": "Darwin Eisner"
},
{
"name": "Company Name",
"value": "Revel"
},
{
"name": "Job Title",
"value": "Truck Driver"
},
{
"name": "Hiring Manager",
"value": "title"
},
{
"name": "Hiring Manager Title",
"value": "manager"
},
{
"name": "Anticipated Start Date",
"value": "09/30/2022"
},
{
"name": "Compensation Amount",
"value": "$0.04"
},
{
"name": "Compensation Interval",
"value": "per week"
},
{
"name": "Headquarter Location - State",
"value": "NY"
}
],
"created_on": "2022-09-29T13:17:53Z",
"updated_on": "2022-09-29T13:17:53Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1,
"per_page": 25
}
}
HTTP Request
GET /v2/candidates/{candidate_id}/offers
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
Get Candidate Offer
curl https://api.jobscore.com/v2/applications/{application_id}/offer \
-H 'Authorization: Token token={your_token}'
{
"id": "btcu0HCBDhCO3Y8-NHwlaI",
"offer_accepted_on": "2023-05-23T04:00:00Z",
"offer_extended_on": "2023-05-22T04:00:00Z",
"start_date_on": "2023-09-30T04:00:00Z",
"status": "draft",
"values": [
{
"name": "Today's Date",
"value": "09/29/2022"
},
{
"name": "Candidate Full Name",
"value": "Darwin Eisner"
},
{
"name": "Company Name",
"value": "Revel"
},
{
"name": "Job Title",
"value": "Truck Driver"
},
{
"name": "Hiring Manager",
"value": "title"
},
{
"name": "Hiring Manager Title",
"value": "manager"
},
{
"name": "Anticipated Start Date",
"value": "09/30/2022"
},
{
"name": "Compensation Amount",
"value": "$0.04"
},
{
"name": "Compensation Interval",
"value": "per week"
},
{
"name": "Headquarter Location - State",
"value": "NY"
}
],
"created_on": "2022-09-29T13:17:53Z",
"updated_on": "2022-09-29T13:17:53Z"
}
Get existing offer to a specific candidate.
HTTP Request
GET /v2/applications/{application_id}/offer
Parameters
- application_id required, uid
- Application’s unique identifier.
Tags
Tags are an easy way to organize candidates into groups during pre-interview sourcing and post-interview candidate relationship management.
Each of your candidates can have multiple tags (e.g. future prospects
, intern
, sales
), but your company shares a single set of tags which are visible by and usable by everyone.
The Tag Object
- name string
- Tag name.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
List Tags
curl https://api.jobscore.com/v2/tags \
-H 'Authorization: Token token={your_token}'
Get list of tags.
{
"items": [
{
"name": "admin",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "branch",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "flash",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "front end",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "java",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "junior",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "marketing",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "no travel",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "recruiting",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
},
{
"name": "sales",
"created_on": "2024-01-01T00:00:00Z",
"updated_on": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 10,
"per_page": 25
}
}
HTTP Request
GET /v2/tags
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
name
,created_on
orupdated_on
. The default isname
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by tag created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by tag created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by tag updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by tag updated before a given date. Should be on
YYYY-MM-DD
format.
Add Tag to Candidate
curl -X POST https://api.jobscore.com/v2/candidates/{candidate_id}/tags \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"tags": ["developer", "intern"]
}
Adds tag(s) to a candidate.
HTTP Request
POST /v2/candidates/{candidate_id}/tags
Parameters
- candidate_id required, uid
- Candidate’s unique identifier.
Request Body
The tags you are about to add must be sent via Request Body as a JSON-formatted object.
- tags required, list
- List of tag names. Tags must already exist in the system. By convention, tags must be all lowercase.
Users
Every team member that participates in the hiring process, including those who refer and interview candidates, is invited to use JobScore and added as a user.
The User Object
- first_name string
- First name.
- last_name string
- Last name.
- email string
- Email address.
- access_level string
-
User’s access level, must be one of:
limited
,standard
,extended
,admin
orowner
. - created_on timestamp, readonly
- User creation date.
- updated_on timestamp, readonly
- User most recent update date.
List Users
curl https://api.jobscore.com/v2/users \
-H 'Authorization: Token token={your_token}'
List all users in your company.
{
"items": [
{
"id": "agHO1WZFSr3lNCaaWPX6Zm",
"first_name": "Charlotte",
"last_name": "Friendly",
"email": "cfriendly@yourcompany.com",
"access_level": "admin",
"created_on": "2022-04-21T02:52:37Z",
"updated_on": "2023-02-22T12:46:00Z"
},
{
"id": "ctr_o09der3j-maawpx6zm",
"first_name": "Buster",
"last_name": "Wegley",
"email": "demo@yourcompany.com",
"access_level": "owner",
"created_on": "2022-04-21T15:45:44Z",
"updated_on": "2023-02-22T12:46:18Z"
},
{
"id": "cutslwanur3ysiaawptx0b",
"first_name": "Jeffrey",
"last_name": "Guzman",
"email": "jguzman@yourcompany.com",
"access_level": "owner",
"created_on": "2022-04-21T19:52:40Z",
"updated_on": "2023-03-02T11:26:29Z"
},
{
"id": "cyrqqkvger3pneeje4agwh",
"first_name": "Wilbur",
"last_name": "Williamson",
"email": "wwilliamson@yourcompany.com",
"access_level": "extended",
"created_on": "2022-04-26T09:54:02Z",
"updated_on": "2022-05-04T00:59:59Z"
},
{
"id": "datu40vger3pneeje4agwh",
"first_name": "Jennifer",
"last_name": "Goodsmith",
"email": "jgoodsmith@yourcompany.com",
"access_level": "limited",
"created_on": "2022-04-26T09:54:03Z",
"updated_on": "2022-05-04T01:00:01Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 5,
"per_page": 25
}
}
HTTP Request
GET /v2/users
Parameters
- email_addresses[] list
- Filter by users’ emails.
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
full_name
,created_on
orupdated_on
. The default isfull_name
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by users created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by users created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by users updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by users updated before a given date. Should be on
YYYY-MM-DD
format.
Filter examples
Filtering by email addresses:
curl "https://api.jobscore.com/v2/users?email_addresses[]=john.marston@gmail.com&email_addresses[]=arthur.morgan@outlook.com" \
-H 'Authorization: Token token={your_token}'
See some filtering examples on the right panel.
Get User
curl https://api.jobscore.com/v2/users/{user_id} \
-H 'Authorization: Token token={your_token}'
Get existing user.
{
"id": "agHO1WZFSr3lNCaaWPX6Zm",
"first_name": "Charlotte",
"last_name": "Friendly",
"email": "cfriendly@yourcompany.com",
"access_level": "admin",
"created_on": "2022-04-21T02:52:37Z",
"updated_on": "2023-02-22T12:46:00Z"
}
HTTP Request
GET /v2/users/{user_id}
Parameters
- user_id required, uid
- User’s unique identifier.
Get Current User
curl https://api.jobscore.com/v2/users/me \
-H 'Authorization: Token token={your_token}'
Get current user.
{
"id": "cQOc2oZ30r3l1_aaWPX6Zm",
"first_name": "Joe",
"last_name": "Saluzki",
"email": "admin@yourcompany.com",
"access_level": "account",
"created_on": "2022-04-21T03:22:07Z",
"updated_on": "2023-04-24T17:55:03Z"
}
HTTP Request
GET /v2/users/me
Sources
List Databases
curl https://api.jobscore.com/v2/sources/databases \
-H 'Authorization: Token token={your_token}'
Get list of databases to be used as sources.
{
"items": [
{
"name": "Google"
},
{
"name": "LinkedIn"
},
{
"name": "Zoominfo"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 3,
"per_page": null
}
}
HTTP Request
GET /v2/sources/databases
Parameters
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
List Events
curl https://api.jobscore.com/v2/sources/events \
-H 'Authorization: Token token={your_token}'
Get list of events to be used as sources.
{
"items": [
{
"name": "Hackathon 2023"
},
{
"name": "San Francisco Hiring Event"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 2,
"per_page": null
}
}
HTTP Request
GET /v2/sources/events
Parameters
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
List Job Boards
curl https://api.jobscore.com/v2/sources/job_boards \
-H 'Authorization: Token token={your_token}'
Get list of job boards to be used as sources.
{
"items": [
{
"name": "Craigslist"
},
{
"name": "Glassdoor"
},
{
"name": "Google for jobs"
},
{
"name": "Indeed"
},
{
"name": "LinkedIn Limited"
},
{
"name": "ZipRecruiter"
},
"..."
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 78,
"per_page": null
}
}
HTTP Request
GET /v2/sources/job_boards
List Search Firms
curl https://api.jobscore.com/v2/sources/search_firms \
-H 'Authorization: Token token={your_token}'
Get list of search firms to be used as sources.
{
"items": [
{
"id": "aGr7vFMY9gm5TMFt2XECpW",
"name": "ABC Recruiting",
"created_on": 1683916410,
"updated_on": 1683916410
},
{
"id": "a245S8eKHa7iXh-sT5XONQ",
"name": "Revel Recruiting",
"created_on": 1683916448,
"updated_on": 1683916448
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 2,
"per_page": 25
}
}
HTTP Request
GET /v2/sources/search_firms
Parameters
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
name
,created_on
orupdated_on
. The default isname
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
.
List Search Firm Recruiters
curl https://api.jobscore.com/v2/sources/search_firms/{search_firm_id}/recruiters \
-H 'Authorization: Token token={your_token}'
Get list of search firm recruiters to be used as sources.
{
"items": [
{
"id": "cDrry0X1HdBy5LcxgKlF8n",
"first_name": "John",
"last_name": "Williams",
"email": "john.williams@abcrecruiting.com",
"created_on": 1683916410,
"updated_on": 1683916410
},
{
"id": "dIFFDN2i5op5iuvbJV5t-3",
"first_name": "William",
"last_name": "Phelps",
"email": "william.phelps@abcrecruiting.com",
"created_on": 1683916410,
"updated_on": 1683916410
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 2,
"per_page": 25
}
}
HTTP Request
GET /v2/sources/search_firms/{search_firm_id}/recruiters
Parameters
- search_firm_id
- The search firm ID for which you want to fetch recruiters for.
- page
- Page number. Defaults to 1.
- per_page
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
full_name
,created_on
orupdated_on
. The default isfull_name
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
.
Stages
Workflow stages are the steps in your hiring process. All candidates that are assigned to a job have a workflow stage. Stages may be customized per-job.
- The first status for a candidate is always
new
; - Candidates can be moved through a configurable set of
active
stages likescreening
,interviewing
oroffer
; - There are three “ending” statuses for candidates:
declined
,withdrawn
andhired
.
Workflow stages only indicate where a candidate is active in the hiring process right now. Candidate activity is recorded separately as emails (correspondence between your team and the candidate), tasks (for scheduled events like phone screens and interviews) and notes (feedback entered by users about the candidate).
The Workflow Stage Object
Attributes
- id uid
- Workflow stage’s unique identifier.
- name string
- Workflow stage name.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
List Workflow Stages
curl https://api.jobscore.com/v2/jobs/{job_id}/workflow_stages \
-H 'Authorization: Token token={your_token}'
Get list of workflow stages. As stages may be customized per job, you must build a list of stages for a specific job.
{
"items": [
{
"id": "bRiUvssNjljzjMEMG2xS-r",
"name": "Schedule Recruiter Screen",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "azTLMW8Avgq4ZkYHwSCLLT",
"name": "Recruiter Screen",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "aXG9b1jdXgfkhLDYN7eDOo",
"name": "Schedule Phone Interview",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "dEepSdvBHfGB-AYZadBHzJ",
"name": "Phone Interview",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "bvgl82vxHgBR1w9eBZ7LG8",
"name": "Schedule Onsite Interview",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "coknBjNhLkWBra2ne35RaV",
"name": "Team Interview",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "cFz4jckCfhA47spn6x35Tx",
"name": "Check References",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "cCDMb3BPbhwjiToJggXouZ",
"name": "Offer",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
},
{
"id": "d2aXOoPqji_z__xlMVGUDv",
"name": "On Hold",
"created_on": "2024-01-01T12:00:00Z",
"updated_on": "2024-01-01T12:00:00Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 9,
"per_page": 25
}
}
HTTP Request
GET /v2/jobs/{job_id}/workflow_stages
Parameters
- job_id required, uid
- Job’s unique identifier.
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- sort
-
Sort by attribute.
Must be one of:
position
,created_on
orupdated_on
. The default isposition
. - order
-
Order of the sorting.
Must be
asc
ordesc
. The default isasc
. - created_after
- Filter by stage created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by stage created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by stage updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by stage updated before a given date. Should be on
YYYY-MM-DD
format.
Webhooks
Webhooks allow you to listen for specific events in JobScore. Once the event happens, we’ll deliver a POST
HTTP request to a URL you’ve given to us.
Webhooks can be created and activated via API or in the JobScore web UI. Currently, you can create webhooks for the following events in JobScore:
candidate_applied
: sent when a candidate applies for a job;candidated_hired
: sent when a candidate is hired.job_added
: sent when a job is added;job_status_changed
: sent when a job’s status is changed;task_added
: sent when tasks are created;candidate_stage_changed
: sent when a candidate’s workflow stage is changed;
Technical Details
Validating the Secret
request_signature = request.headers['X-Signature']
calculated_signature = OpenSSL::HMAC.hexdigest('sha256', '{your_secret}', request.raw_post)
request_signature == calculated_signature
After creating a webhook endpoint, JobScore will return you a randomly generated secret associated with this webhook. It looks like this:
BqlnkciDAsSax-Hk5Gxx-h3QGQuukA
As an additional and optional security step, you can use this secret to
validate if the request originated from JobScore, and reject it otherwise.
To do so, calculate the HMAC digest and check if it’s equal to the one
informed on the X-Signature
HTTP header of the request.
See Ruby example on the right panel.
Timeout
We’ll wait up to 10 seconds for a response from your server. If we don’t get a response within this time, we’ll consider the delivery as failed. It’s recommended that your system enqueue the events to process them asynchronously if possible.
Retry Policy
In case of failure, we retry each webhook until it succeedes up to 5 times, using an exponential back-off algorithm with the following intervals:
- 5 minutes
- 30 minutes
- 1 hour
- 3 hours
- 6 hours
If it fails for the fifth time, we’ll send an email notifying the user that created the subscription about the failure, but we limit this email to one within 24 hours per subscription.
Disable Policy
If a webhook fails all delivery attempts for 60 days, we’ll automatically disable it. The user that created the webhook will be notified by email.
Also, if we receive a status code of 410 Gone
we’ll automatically
disable the webhook.
The Webhook Object
Attributes
- id uid
- Webhook unique identifier.
- target_url string
- The target which JobScore is going to POST the events payload to.
- secret string, readonly
- Secret. This is only exposed upon creation.
- event_types list
- The event list which JobScore will notify you about.
- user object, readonly
-
Object representation of webhook’s creator.
- id uid
- User unique identifier.
- first_name string
- First name.
- last_name string
- Last name.
- email string
- Primary email.
- created_on timestamp, readonly
- Record creation time.
- updated_on timestamp, readonly
- Record last updated time.
List Webhooks
curl https://api.jobscore.com/v2/webhooks \
-H 'Authorization: Token token={your_token}'
Get list of webhooks.
{
"items": [
{
"id": "akxBs3DfXiW6VOgLWIlhf8",
"target_url": "https://www.example.com/webhooks",
"event_types": [
"task_added"
],
"user": {
"id": "cQOc2oZ30r3l1_aaWPX6Zm",
"first_name": "Joe",
"last_name": "Saluzki",
"email": "admin@jobscore.com"
},
"created_on": "2023-05-18T16:17:51Z",
"updated_on": "2023-05-18T17:19:23Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"total_pages": 1,
"total_records": 1,
"per_page": 25
}
}
HTTP Request
GET /v2/webhooks
Parameters
- page integer
- Page number. Defaults to 1.
- per_page integer
- Number of records returned per page. Defaults to 25. Must be a maximum of 100.
- created_after
- Filter by webhooks created starting on a given date. Should be on
YYYY-MM-DD
format. - created_before
- Filter by webhooks created before a given date. Should be on
YYYY-MM-DD
format. - updated_after
- Filter by webhooks updated starting on a given date. Should be on
YYYY-MM-DD
format. - updated_before
- Filter by webhooks updated before a given date. Should be on
YYYY-MM-DD
format.
Create Webhook
curl -X POST https://api.jobscore.com/v2/webhooks \
-H 'Authorization: Token token={your_token}' \
-H "Content-Type: application/json" \
-d '{json_body}'
Example representation of
{json_body}
object:
{
"target_url": "https://www.example.com/webhooks",
"event_types": ["job_added", "job_status_changed"]
}
Create a new webhook.
HTTP Request
POST /v2/webhooks
Request Body
The webhook’s data you are about to create must be sent via Request Body as a JSON-formatted object.
Parameters
- target_url required, string
- The target which JobScore is going to POST the events payload to.
- event_types required, list
- A list of event types which JobScore will notify you about. Refer to Webhooks section for a list of valid options.
Delete Webhook
curl -X DELETE https://api.jobscore.com/v2/webhooks/{webhook_id} \
-H 'Authorization: Token token={your_token}'
Deletes an existing webhook.
HTTP Request
DELETE /webhooks/{webhook_id}
The Webhook Event Object
Attributes
- event_type string
- Event type.
- detail object
- Event details, when applicable.
- job object
- Job related to the event, when applicable.
- candidate object
- Candidate related to the event, when applicable.
- task object
- Task related to the event, when applicable.
Candidate Stage Changed
{
"event_type": "candidate_stage_changed",
"detail": {
"previous_status": "new",
"previous_stage": null,
"new_status": "declined",
"new_stage": null
},
"job": {
"id": "aa1afdb40b33403ea8f747",
"title": "Software Architect",
"internal_title": null,
"requisition_number": "0001",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-19T14:31:26Z",
"updated_on": "2023-05-19T14:31:26Z"
},
"location": {
"id": "18ef0c992d7fdfbe63e56c",
"country": "US",
"state": "CA",
"city": "Sunnyvale",
"postal_code": "94105",
"street1": "701 First Avenue",
"street2": null,
"latitude": 34.07871,
"longitude": -118.2161,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-19T14:31:26Z",
"updated_on": "2023-05-19T14:31:26Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:03-02:00",
"updated_on": "2001-12-15T00:59:03-02:00"
},
"candidate": {
"id": "e1d048c34edc0d4f88bec8",
"first_name": "Tom",
"last_name": "Jamison",
"source_type": "website",
"source_detail": {},
"tags": [],
"address": {
"country": "US",
"state": "CA",
"city": "Rohnert Park",
"postal_code": "94928",
"street1": "400 Sonoma Blvd.",
"street2": "BOX 123",
"latitude": 38.347,
"longitude": -122.6941
},
"email_addresses": [
{
"type": "personal",
"address": "tom@tomjamison.com"
},
{
"type": "work",
"address": "tom@tomjamisonwork.com"
}
],
"phone_numbers": [
{
"type": "home",
"number": "707-756-1553"
},
{
"type": "mobile",
"number": "707-756-1552"
}
],
"profile_links": [
{
"type": "facebook",
"url": "http://www.facebook.com/tom_jobseeke"
},
{
"type": "twitter",
"url": "http://www.twitter.com/tom_jobseeke"
}
],
"employment": [
{
"id": "0000000000000000000003",
"employer": "Current Employer",
"positions": [
{
"id": "0000000000000000000004",
"title": "Current Employer title One",
"start_date": "2004-01-01",
"end_date": "to_present"
},
{
"id": "0000000000000000000005",
"title": "Current Employer Title Two",
"start_date": "2003-01-01",
"end_date": "to_present"
}
]
},
{
"id": "0000000000000000000004",
"employer": "Previous Employer",
"positions": [
{
"id": "0000000000000000000006",
"title": "Previous Employer Title One",
"start_date": "2000-01-01",
"end_date": "2002-12-31"
}
]
},
{
"id": "5cc17c0ecf503ac539d66e",
"employer": "Lotus Development Corp",
"positions": [
{
"id": "624db07c99287f5a2bfa21",
"title": "Sr. Product Planning Manager",
"start_date": "1998-01-01",
"end_date": "2000-12-31"
}
]
},
{
"id": "ca49ba5eb6b228d98407d7",
"employer": "InterGO Communications",
"positions": [
{
"id": "5ae6711b68c89caae00ea6",
"title": "Sr. Dir Product Management",
"start_date": "1995-01-01",
"end_date": "1998-12-31"
},
{
"id": "1761f46eb55c7e7b83812a",
"title": "Group Product Manager",
"start_date": "1993-01-01",
"end_date": "1994-12-31"
}
]
},
{
"id": "aec53185fa9e7af69d9793",
"employer": "Microsoft Corp",
"positions": [
{
"id": "b0a4916a388fd134ffac88",
"title": "Product Manager",
"start_date": "1989-01-01",
"end_date": "1992-12-31"
}
]
},
{
"id": "4d19157bc51e5585e002bf",
"employer": "Enfish Technology",
"positions": [
{
"id": "a5db8becd98449b6999a3d",
"title": "Product Planner",
"start_date": "1986-01-01",
"end_date": "1988-12-31"
},
{
"id": "ec5d915d3f74fb2fa48aae",
"title": "Channel Mkg Director",
"start_date": "1983-01-01",
"end_date": "1985-12-31"
},
{
"id": "4ecaf7334fdcabfcfe6370",
"title": "Channel Marketing Coordinator",
"start_date": "1980-01-01",
"end_date": "1982-12-31"
}
]
}
],
"education": [
{
"id": "56349356a880560ebb65c5",
"school_name": "Standford",
"graduation_date": "2000-12-15",
"degree": "Masters",
"degree_major": "Computer Science"
},
{
"id": "2810c7fef73659d2dcba1e",
"school_name": "Cal Poly San Luis Obispo",
"graduation_date": "1995-12-15",
"degree": "Bachelors",
"degree_major": "Computer Science"
}
],
"created_on": "2006-06-27T02:00:06Z",
"updated_on": "2006-06-27T02:00:06Z"
},
"task": null
}
- event_type string
-
candidate_stage_changed
. - detail object
-
- previous_status string
- The former candidate status.
- previous_stage object
- The former workflow stage.
- new_status string
- The updated candidate status.
- new_stage object
- The updated workflow stage.
- job object
- Job associated with the candidate.
- candidate object
- Candidate which the workflow stage was changed.
- task object
-
null
. Not applicable for this webhook.
Task Added
{
"event_type": "task_added",
"detail": {},
"job": {
"id": "307d86b7fe4234991026b5",
"title": "Release Engineer",
"internal_title": null,
"requisition_number": "0005",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"location": {
"id": "66ef449af728c20b52a532",
"country": "US",
"state": "CA",
"city": "SF",
"postal_code": "94103",
"street1": "613 Main St.",
"street2": null,
"latitude": null,
"longitude": null,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:05-02:00",
"updated_on": "2001-12-15T00:59:05-02:00"
},
"candidate": {
"id": "e1d048c34edc0d4f88bec8",
"first_name": "Tom",
"last_name": "Jamison",
"source_type": "website",
"source_detail": {},
"tags": [],
"address": {
"country": "US",
"state": "CA",
"city": "Rohnert Park",
"postal_code": "94928",
"street1": "400 Sonoma Blvd.",
"street2": "BOX 123",
"latitude": 38.347,
"longitude": -122.6941
},
"email_addresses": [
{
"type": "personal",
"address": "tom@tomjamison.com"
},
{
"type": "work",
"address": "tom@tomjamisonwork.com"
}
],
"phone_numbers": [
{
"type": "home",
"number": "707-756-1553"
},
{
"type": "mobile",
"number": "707-756-1552"
}
],
"profile_links": [
{
"type": "facebook",
"url": "http://www.facebook.com/tom_jobseeke"
},
{
"type": "twitter",
"url": "http://www.twitter.com/tom_jobseeke"
}
],
"employment": [
{
"id": "0000000000000000000003",
"employer": "Current Employer",
"positions": [
{
"id": "0000000000000000000004",
"title": "Current Employer title One",
"start_date": "2004-01-01",
"end_date": "to_present"
},
{
"id": "0000000000000000000005",
"title": "Current Employer Title Two",
"start_date": "2003-01-01",
"end_date": "to_present"
}
]
},
{
"id": "0000000000000000000004",
"employer": "Previous Employer",
"positions": [
{
"id": "0000000000000000000006",
"title": "Previous Employer Title One",
"start_date": "2000-01-01",
"end_date": "2002-12-31"
}
]
},
{
"id": "5cc17c0ecf503ac539d66e",
"employer": "Lotus Development Corp",
"positions": [
{
"id": "624db07c99287f5a2bfa21",
"title": "Sr. Product Planning Manager",
"start_date": "1998-01-01",
"end_date": "2000-12-31"
}
]
},
{
"id": "ca49ba5eb6b228d98407d7",
"employer": "InterGO Communications",
"positions": [
{
"id": "5ae6711b68c89caae00ea6",
"title": "Sr. Dir Product Management",
"start_date": "1995-01-01",
"end_date": "1998-12-31"
},
{
"id": "1761f46eb55c7e7b83812a",
"title": "Group Product Manager",
"start_date": "1993-01-01",
"end_date": "1994-12-31"
}
]
},
{
"id": "aec53185fa9e7af69d9793",
"employer": "Microsoft Corp",
"positions": [
{
"id": "b0a4916a388fd134ffac88",
"title": "Product Manager",
"start_date": "1989-01-01",
"end_date": "1992-12-31"
}
]
},
{
"id": "4d19157bc51e5585e002bf",
"employer": "Enfish Technology",
"positions": [
{
"id": "a5db8becd98449b6999a3d",
"title": "Product Planner",
"start_date": "1986-01-01",
"end_date": "1988-12-31"
},
{
"id": "ec5d915d3f74fb2fa48aae",
"title": "Channel Mkg Director",
"start_date": "1983-01-01",
"end_date": "1985-12-31"
},
{
"id": "4ecaf7334fdcabfcfe6370",
"title": "Channel Marketing Coordinator",
"start_date": "1980-01-01",
"end_date": "1982-12-31"
}
]
}
],
"education": [
{
"id": "56349356a880560ebb65c5",
"school_name": "Standford",
"graduation_date": "2000-12-15",
"degree": "Masters",
"degree_major": "Computer Science"
},
{
"id": "2810c7fef73659d2dcba1e",
"school_name": "Cal Poly San Luis Obispo",
"graduation_date": "1995-12-15",
"degree": "Bachelors",
"degree_major": "Computer Science"
}
],
"created_on": "2006-06-27T02:00:06Z",
"updated_on": "2006-06-27T02:00:06Z"
},
"task": {
"id": "e3fb7358a8265aae934859",
"subject": "Example Task",
"category": "Call",
"assignee": {
"type": "user",
"record": {
"id": "78e5caeb1ad414ff5540bc",
"first_name": "Margaret",
"last_name": "Cho"
}
},
"due_on": "2023-01-01T09:00:00Z",
"duration_in_minutes": "30",
"timezone": "Pacific Time (US & Canada)",
"created_on": "2023-01-01T09:00:00Z"
}
}
- event_type string
-
task_added
. - detail object
-
null
. Not applicable for this webhook. - job object
-
Job associated with the task, or
null
if not available. - candidate object
-
Candidate associated with the task, or
null
if not available. - task object
- Object representation of the added task.
Candidate Applied
{
"event_type": "candidate_applied",
"detail": {},
"job": {
"id": "aa1afdb40b33403ea8f747",
"title": "Software Architect",
"internal_title": null,
"requisition_number": "0001",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"location": {
"id": "18ef0c992d7fdfbe63e56c",
"country": "US",
"state": "CA",
"city": "Sunnyvale",
"postal_code": "94105",
"street1": "701 First Avenue",
"street2": null,
"latitude": 34.07871,
"longitude": -118.2161,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:03-02:00",
"updated_on": "2001-12-15T00:59:03-02:00"
},
"candidate": {
"id": "e1d048c34edc0d4f88bec8",
"first_name": "Tom",
"last_name": "Jamison",
"source_type": "website",
"source_detail": {},
"tags": [],
"address": {
"country": "US",
"state": "CA",
"city": "Rohnert Park",
"postal_code": "94928",
"street1": "400 Sonoma Blvd.",
"street2": "BOX 123",
"latitude": 38.347,
"longitude": -122.6941
},
"email_addresses": [
{
"type": "personal",
"address": "tom@tomjamison.com"
},
{
"type": "work",
"address": "tom@tomjamisonwork.com"
}
],
"phone_numbers": [
{
"type": "home",
"number": "707-756-1553"
},
{
"type": "mobile",
"number": "707-756-1552"
}
],
"profile_links": [
{
"type": "facebook",
"url": "http://www.facebook.com/tom_jobseeke"
},
{
"type": "twitter",
"url": "http://www.twitter.com/tom_jobseeke"
}
],
"employment": [
{
"id": "0000000000000000000003",
"employer": "Current Employer",
"positions": [
{
"id": "0000000000000000000004",
"title": "Current Employer title One",
"start_date": "2004-01-01",
"end_date": "to_present"
},
{
"id": "0000000000000000000005",
"title": "Current Employer Title Two",
"start_date": "2003-01-01",
"end_date": "to_present"
}
]
},
{
"id": "0000000000000000000004",
"employer": "Previous Employer",
"positions": [
{
"id": "0000000000000000000006",
"title": "Previous Employer Title One",
"start_date": "2000-01-01",
"end_date": "2002-12-31"
}
]
},
{
"id": "5cc17c0ecf503ac539d66e",
"employer": "Lotus Development Corp",
"positions": [
{
"id": "624db07c99287f5a2bfa21",
"title": "Sr. Product Planning Manager",
"start_date": "1998-01-01",
"end_date": "2000-12-31"
}
]
},
{
"id": "ca49ba5eb6b228d98407d7",
"employer": "InterGO Communications",
"positions": [
{
"id": "5ae6711b68c89caae00ea6",
"title": "Sr. Dir Product Management",
"start_date": "1995-01-01",
"end_date": "1998-12-31"
},
{
"id": "1761f46eb55c7e7b83812a",
"title": "Group Product Manager",
"start_date": "1993-01-01",
"end_date": "1994-12-31"
}
]
},
{
"id": "aec53185fa9e7af69d9793",
"employer": "Microsoft Corp",
"positions": [
{
"id": "b0a4916a388fd134ffac88",
"title": "Product Manager",
"start_date": "1989-01-01",
"end_date": "1992-12-31"
}
]
},
{
"id": "4d19157bc51e5585e002bf",
"employer": "Enfish Technology",
"positions": [
{
"id": "a5db8becd98449b6999a3d",
"title": "Product Planner",
"start_date": "1986-01-01",
"end_date": "1988-12-31"
},
{
"id": "ec5d915d3f74fb2fa48aae",
"title": "Channel Mkg Director",
"start_date": "1983-01-01",
"end_date": "1985-12-31"
},
{
"id": "4ecaf7334fdcabfcfe6370",
"title": "Channel Marketing Coordinator",
"start_date": "1980-01-01",
"end_date": "1982-12-31"
}
]
}
],
"education": [
{
"id": "56349356a880560ebb65c5",
"school_name": "Standford",
"graduation_date": "2000-12-15",
"degree": "Masters",
"degree_major": "Computer Science"
},
{
"id": "2810c7fef73659d2dcba1e",
"school_name": "Cal Poly San Luis Obispo",
"graduation_date": "1995-12-15",
"degree": "Bachelors",
"degree_major": "Computer Science"
}
],
"created_on": "2006-06-27T02:00:06Z",
"updated_on": "2006-06-27T02:00:06Z"
},
"task": null
}
- event_type string
-
candidate_applied
. - detail object
-
null
. Not applicable for this webhook. - job object
- Job to which this candidate applied.
- candidate object
- Candidate which applied.
- task object
-
null
. Not applicable for this webhook.
Job Added
{
"event_type": "job_added",
"detail": {},
"job": {
"id": "aa1afdb40b33403ea8f747",
"title": "Software Architect",
"internal_title": null,
"requisition_number": "0001",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"location": {
"id": "18ef0c992d7fdfbe63e56c",
"country": "US",
"state": "CA",
"city": "Sunnyvale",
"postal_code": "94105",
"street1": "701 First Avenue",
"street2": null,
"latitude": 34.07871,
"longitude": -118.2161,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:03-02:00",
"updated_on": "2001-12-15T00:59:03-02:00"
},
"candidate": null,
"task": null
}
- event_type string
-
job_added
. - detail object
-
null
. Not applicable for this webhook. - job object
- Object representation of the added job.
- candidate object
-
null
. Not applicable for this webhook. - task object
-
null
. Not applicable for this webhook.
Job Status Changed
{
"event_type": "job_status_changed",
"detail": {
"previous_status": "draft",
"new_status": "open"
},
"job": {
"id": "aa1afdb40b33403ea8f747",
"title": "Software Architect",
"internal_title": null,
"requisition_number": "0001",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"location": {
"id": "18ef0c992d7fdfbe63e56c",
"country": "US",
"state": "CA",
"city": "Sunnyvale",
"postal_code": "94105",
"street1": "701 First Avenue",
"street2": null,
"latitude": 34.07871,
"longitude": -118.2161,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-18T17:36:13Z",
"updated_on": "2023-05-18T17:36:13Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:03-02:00",
"updated_on": "2001-12-15T00:59:03-02:00"
},
"candidate": null,
"task": null
}
- event_type string
-
job_status_changed
. - detail object
-
- previous_status object
- The former job status.
- new_status object
- The updated job status.
- job object
- Job which the status was changed.
- candidate object
-
null
. Not applicable for this webhook. - task object
-
null
. Not applicable for this webhook.
Candidate Hired
{
"event_type": "candidate_hired",
"detail": {
"offer_extended_on": null,
"offer_accepted_on": null,
"start_date_on": null,
"offer": {
"id": "3ce6ca1ff1c639971d4bd4",
"status": "draft",
"values": [
{
"name": "Job Position",
"value": "Yahoo Job"
},
{
"name": "Salary",
"value": "$ 1,000.00"
},
{
"name": "Salary Frequency",
"value": "Monthly"
},
{
"name": "Offered Expiration Date",
"value": "10/05/2018"
},
{
"name": "Compensation Amount",
"value": "$2,500.00"
},
{
"name": "Recruiter Fee",
"value": "$3,150.50"
},
{
"name": "Start Date",
"value": "02/26/2018"
},
{
"name": "Offered Hours per week",
"value": "12345"
},
{
"name": "Bonus (percentage)",
"value": "50"
}
],
"created_on": "2018-01-28T15:00:00-02:00",
"updated_on": "2018-01-28T15:00:00-02:00"
}
},
"job": {
"id": "aa1afdb40b33403ea8f747",
"title": "Software Architect",
"internal_title": null,
"requisition_number": "0001",
"department": {
"id": "1234567890123456789002",
"name": "Administrative",
"created_on": "2023-05-22T16:52:26Z",
"updated_on": "2023-05-22T16:52:26Z"
},
"location": {
"id": "18ef0c992d7fdfbe63e56c",
"country": "US",
"state": "CA",
"city": "Sunnyvale",
"postal_code": "94105",
"street1": "701 First Avenue",
"street2": null,
"latitude": 34.07871,
"longitude": -118.2161,
"internal_name": null,
"external_name": null,
"created_on": "2023-05-22T16:52:26Z",
"updated_on": "2023-05-22T16:52:26Z"
},
"job_types": ["full_time"],
"status": "open",
"created_on": "2001-12-13T16:59:03-02:00",
"updated_on": "2001-12-15T00:59:03-02:00"
},
"candidate": {
"id": "31a2769f76ef537af2066a",
"first_name": "Harry",
"last_name": "Jobseeker",
"source_type": "website",
"source_detail": {},
"tags": [],
"address": {
"country": "US",
"state": null,
"city": null,
"postal_code": "94042",
"street1": null,
"street2": null,
"latitude": null,
"longitude": null
},
"email_addresses": [
{
"type": "personal",
"address": "harry@needajob.com"
}
],
"phone_numbers": [
{
"type": "home",
"number": "415-756-1553"
},
{
"type": "mobile",
"number": "415-756-1552"
}
],
"profile_links": [],
"employment": [],
"education": [
{
"id": "2226dc23078f800e171499",
"school_name": "Standford",
"graduation_date": "1999-12-31",
"degree": "Masters",
"degree_major": "Computer Science"
}
],
"created_on": "2006-06-28T02:00:08Z",
"updated_on": "2006-06-28T02:00:08Z"
},
"task": null
}
- event_type string
-
candidate_hired
. - detail object
-
- offer_extended_on timestamp
- Date which offer was extended to the candidate.
- offer_accepted_on timestamp
- Date which offer was accepted by the candidate.
- start_date_on timestamp
- Date which the candidate started working on the position.
- offer object
-
Offer associated with the candidate application.
- id uid
- Offer’s unique identifier.
- status object
-
Offer status.
- id integer
- Offer status’ unique identifier.
- name string
- Offer status’ name.
- values list
-
Offer values.
- name string
- Offer value name.
- value string
- Offer value input.
- created_on timestamp
- Offer creation date.
- updated_on timestamp
- Offer most recent update date.
- job object
- Job associated with the candidate.
- candidate object
- The hired candidate.
- task object
-
null
. Not applicable for this webhook.
HRIS Onboarding
This section outlines the steps required to integrate an HRIS or onboarding system with JobScore.
JobScore’s API supports new-hire onboarding integrations with many leading HRIS and Onboarding platforms. Partner platforms receive real-time notification of, and detailed information about new hires by means of JobScore’s webhooks infrastructure. JobScore also provides multiple API endpoints for further lookup and action. This section outlines the basic steps to get a new-hire integration up and running, along with technical details required to connect your system.
Creating an API Key
The Integrations > JobScore API & Webhooks page is where customer admins configure everything API related inside their JobScore account. API keys and webhooks subscriptions can be created on this page. Webhook subscriptions can also be created via API for auto-provisioning cases, see Create Webhook and related endpoints above.
When a webhook subscription is created, the system will provide the creator with a secret
value.
You may opt to save this value to perform validations on the webhook requests sent by JobScore, as an extra safety measure.
See Validating the Secret for more information.
Subscribing to a Webhook
To create webhook subscriptions, your organization must provide a secure HTTP POST endpoint, and select the event types for which the endpoint will receive notifications.
New hire onboarding systems will make use of the candidate_hired
event.
Webhooks Workflow
Once subscribed to the candidate_hired
webhook, the subscribing system will be informed about your organization’s new hires within JobScore.
A webhook with this event is triggered every time a candidate inside JobScore is moved to the Hired stage.
Information about the candidate, job, offer, and other relevant aspects is contained inside the payload delivered. Refer to Candidate Hired for a full list of attributes in the payload.