NAV 3 gray stripes for navigation bar

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.

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.

The Application Object

Attributes

status string
Candidate status. One of: new, active, declined, withdrawn or hired.
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 or updated_on. The default is created_on.
order
Order of the sorting. Must be asc or desc. The default is desc.
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 or withdrawn. (hired is not allowed in this action).
stage_id uid
A workflow stage‘s unique identifier. Only applicable (and required) if status is active.
disposition_code uid
Disposition code’s unique identifier. Required if workflow status is either withdrawn or declined 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.

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 or other.
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:

  1. 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.
  2. 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 or Twitter.
referral_first_name string
Referrer first name.
referral_last_name string
Referrer last name.
referral_email string
Referrer email address.
Email
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.

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 or other.
If omitted, other will be assigned by default, with API 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 or work. 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 or other. 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 or postdoctorate.
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:

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 or other.
If omitted, other will be assigned by default, with API 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 or work. 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 or other. 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 or postdoctorate.
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.

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 or updated_on. The default is name.
order
Order of the sorting. Must be asc or desc. The default is desc.
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 or withdrawn.
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.

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 or other.
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 or updated_on. The default is created_on.
order
Order of the sorting. Must be asc or desc. The default is desc.
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 or other.
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.

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 or filled.
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 and per 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 and per 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 or updated_on. The default is title.
order
Order of the sorting. Must be asc or desc. The default is asc.
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.

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 or updated_on. The default is address.
order
Order of the sorting. Must be asc or desc. The default is asc.
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.

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 or interview_feedback.
ratings list
Ratings information. Only applicable when type is interview_feedback.
name string
Rating name.
description string
Rating description.
score float
Rating score. Ranges from 1.0 to 4.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 or note. All note types are returned by default.
sort
Sort by attribute. Must be one of: created_on or updated_on. The default is created_on.
order
Order of the sorting. Must be asc or desc. The default is desc.
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 and title.
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 or canceled.
application object
Application related to the offer.
id uid
Application unique identifier.
status string
Application status. One of: new, active, declined, withdrawn or hired.
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 or filled.
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 or esignature_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 or updated_on. The default is created_on.
order
Order of the sorting. Must be asc or desc. The default is desc.
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 or updated_on. The default is name.
order
Order of the sorting. Must be asc or desc. The default is asc.
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 or owner.
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 or updated_on. The default is full_name.
order
Order of the sorting. Must be asc or desc. The default is asc.
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 or updated_on. The default is name.
order
Order of the sorting. Must be asc or desc. The default is asc.

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 or updated_on. The default is full_name.
order
Order of the sorting. Must be asc or desc. The default is asc.

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.

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 or updated_on. The default is position.
order
Order of the sorting. Must be asc or desc. The default is asc.
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:

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:

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.