NAV

Overview

The GoodHire API is a web service that allows customers to order employment background checks on candidates and view the results of these ordered checks.

The API is accessed via HTTPS, and resources are operated upon using the GET and POST methods.

There are two base endpoints for the API that all methods are appended to:

Test Endpoint: https://api-sandbox.goodhire.com/v1/

Production Endpoint: https://api.goodhire.com/v1/

The test endpoint can be used while you are building your application, and all background checks ordered via its methods will return dummy data. When you are ready to begin ordering real background checks, change your base endpoint to the production endpoint above and contact api@goodhire.com to receive a production API key.

Getting Started

Below is the process for setting up an API account and ordering a test background check:

  1. Create a developer account
  2. Create a report
  3. Retrieve a report

All examples provided use the test base endpoint:

https://api-sandbox.goodhire.com/v1/

Create a developer account

Visit the sandbox API developer dashboard here and create an account. Once you’ve created your account, you’ll see your test API key displayed on the dashboard. Use this value in your API calls as you build your integration.

Create a report

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-sandbox.goodhire.com/v1/Report \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}'

Within the GoodHire API, background checks are ordered by creating a report object. The report contains information on the candidate being screened as well as the type of GoodHire background check being run.

To create a report, make a POST to:

https://api-sandbox.goodhire.com/v1/Report

Response

{
    "Id":"283397e8-1323-49dc-9116-b483a2842d2f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Status":"New",
    "StatusDetails":"New",
    "SectionsContainingAlerts":[

    ],
    "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cnduid=a6bd5796-46a2-4828-bc2b-fb9a1d2019a1",
    "RequiredReportActions":[

    ]
}

The API will respond with an HTTP 201 Created and your report. The Id field in the body of the response is the unique id of your report. Save this value for use later.

Retrieve a report

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-sandbox.goodhire.com/v1/Report/2930ed9b-394b-4ca9-9aeb-1aa08b695ffa
HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Id":"283397e8-1323-49dc-9116-b483a2842d2f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
   "Status":"MissingInput",
   "StatusDetails":"AwaitingInput",
   "SectionsContainingAlerts":[

   ],
   "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cndid=7412",
   "RequiredReportActions":[{
        "Description":"Candidate information is incomplete (candidate has been notified to provide info thru self-complete flow)",
        "Type":"IncompleteCandidateInfo",
        "Url":"https://sandbox.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://sandbox.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104"
    },
    {
        "Description":"Candidate consent is missing (candidate has been notified to provide consent thru self-complete flow)",
        "Type":"MissingCandidateConsent",
        "Url":"https://sandbox.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://sandbox.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104&showConsent=1"
    }]
}

Now that you have ordered your first background check, you can use the API to view its status and results.

To do this, make a GET to:

https://api-sandbox.goodhire.com/v1/Report/:report_id

Where report_id is the Id of your report.

The API will return a report object with information on the GoodHire background check tied to the report you created. The report contains the current status of your background check (Processing, MissingInfo, CompletedClear, etc.), a description of actions (if any) required for the report to run, and a URL to view the complete check on GoodHire.com.

If your candidate has not yet provided consent via the sent email, your response will look similar to the one on the right. Once your candidate has completed these steps, the Status field of the response will be updated to “Processing” and then “CompletedClear” or ”CompletedAlert” depending on if any sections of the background report returned alerts.

If you have any questions, please email: api@goodhire.com

Authentication

curl -i -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-sandbox.goodhire.com/v1/

The GoodHire API uses HTTP Basic Auth. Your API key consists of a token passed in the Authorization header of your requests:

Authorization: ApiKey YOUR_API_KEY

Where YOUR_API_KEY is your test or production API key.

Click Here to create a sandbox developer dashboard account and obtain a test API key.

For security, all requests must be made via HTTPS.

Webhooks

{
  "Id": "aced418a-0fbf-4d46-a63d-6d499b9eff95",
  "ReportStatus": {
    "Id":"e93a6cc9-82b4-4974-b9ed-f6364af8820f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Status":"CompletedAlert",
    "StatusDetails":"Alert",
    "SectionsContainingAlerts":[
        "Sex Offender List Check",
        "National Criminal Records Check",
        "Misc Court Records",
        "SSN Trace + Address History"
    ],
    "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cndid=9629",
    "RequiredReportActions":[]
  }
}

Whenever the status of a resource changes in the API, we will submit a POST request to a URL you provide with information on the new status. To set up a listening webhook URL for your account, visit the API configuration section of the developer dashboard and edit the Webhook URL field.

In response to a Webhook notification, your server should return a 200 response status code. If our system receives a non-200 code, we will continue trying to send the webhook with an increasing delay of 2 hours, 4 hours, 6 hours, 8 hours and 12 hours thereafter, for up to 10 days.

Security

All webhooks include a hash signature in the X-Goodhire-Signature header. To verify the identity of an inbound webhook, compute the SHA-256 HMAC hash of the webhook body using your API key as the secret key and compare this value to the signature hash.

Attributes

Name Format Description
Id string Unique identifier for the webhook
ReportStatus object The updated report object

Check Types

When creating a report, the product array within the offer object should contain one value from the “Primary Checks” section below. This is the type of GoodHire background check that will be ordered. The product array can also contain multiple values from the “Additional Checks” section. These are additional checks that will be added to the primary check.

Primary Checks:

Additional Checks:

Test Data

By default, the report returned for all background checks run in the sandbox environment will have a status of “clear”. To test responses for background checks with alerts, pass in one of the below values in the lastName field of the candidate when creating a report.

Value Result
Alert All report sections will come back with “alerts” (“criminal check” will contain criminal records, employment verification will contain warnings, etc.)
AlertSsnValid Only “SSN trace” report section will contain alert, stating that SSN number is valid, but didn’t contain or didn’t match candidate info
AlertSsn Only “SSN trace” report section will contain alert, stating that SSN number could not be verified

HTTP Response Codes

The GoodHire API uses HTTP status codes to indicate the success or failure of API requests. 2xx codes indicate that the request was processed successfully, while 4xx codes indicate an error. Below is a list of status codes returned by the API:

HTTP Status Code Meaning
200 Ok - Successful request
201 Created - Resource was created succesfully
400 Bad Request - Invalid parameter or argument
401 Unauthorized - Invalid API key
403 Forbidden - Customer’s account is flagged for review
404 Not Found - Resource not found
409 Conflict - Resource has already been linked to your API account
500 Internal Server Error - Internal server error, please try again later

Errors

Requests that generate errors will return 4xx status codes and the body of the response will contain an error object with the following format:

{
   "StatusCode": "BadRequest",
   "StatusMessage": "Employer creation errors",
   "AdditionalInfo":    {
        "ErrorText": "Model errors",
        "FieldErrors": [{
                "Name": "Phone",
                "ErrorText": "company: Invalid phone/fax format (222-333-4444)"
        }]
   }
}

Attributes

Name Format Description
StatusCode string A description of the HTTP error code of the response.
StatusMessage string A high-level description of the error.
AdditionalInfo object see additional info object

Additional Info

{
    "ErrorText": "Model errors",
    "FieldErrors": [{
            "Name": "Phone",
            "ErrorText": "company: Invalid phone/fax format (222-333-4444)"
    }]
}

Attributes

Name Format Description
ErrorText string Information on what caused the error.
FieldErrors array of objects see field error object

Field Error

{
    "Name": "Phone",
    "ErrorText": "company: Invalid phone/fax format (222-333-4444)"
}

Attributes

Name Format Description
Name string The name of the field that was invalid.
ErrorText string Detail on why the field was invalid.

Resources

Report

A report represents a background check to be run on a specific candidate.

{
    "Id":"283397e8-1323-49dc-9116-b483a2842d2f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Status":"New",
    "StatusDetails":"New",
    "SectionsContainingAlerts":[

    ],
    "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cnduid=a6bd5796-46a2-4828-bc2b-fb9a1d2019a1",
    "RequiredReportActions":[

    ]
}

Attributes

Name Format Description
Id string The unique id for the report.
Candidate object see candidate object
Status string The current status of the ordered report on GoodHire. It can take one of the following values:
  • RequiresAdditionalInfo – Report is awaiting action from user or GH member services.
  • MissingInput – Candidate data is invalid/incomplete.
  • Processing – Report is currently being processed (certain report sections may take several days to complete).
  • Canceled – Report processing was aborted by request.
  • Expired – Report processing was aborted due to invalid/incomplete candidate information.
  • CompletedAlert – Report processing completed, and the report contains alerts.
  • CompletedClear – Report execution completed, and all sections are clear.
StatusDetails string More details on the report status:
  • AwaitingInput – The employer has asked the candidate to provide information and is waiting for the request to be completed
  • MissingInfo – The employer did not provide candidate information.
  • AwaitingConfirmation – The employer or candidate needs to confirm the candidate’s information.
  • AwaitingConsent – The employer or candidate needs to provide the candidate’s consent.
  • AwaitingConsentReview – Consent form was uploaded by the employer and needs to be reviewed by GoodHire member services.
  • AwaitingCountyFee – The employer needs to accept/reject the additional county fee imposed by the county court.
  • AwaitingDrugTestScheduling – The candidate needs to schedule their drug screening test.
  • Clear – The report completed without alerts.
  • Alert – The report completed with alerts.
  • CanceledOrExpired – The report was canceled or expired (expiration may occur if candidate info hasn’t been provided w/in 30 days)
  • Locked – The report has been locked. GoodHire member services will contact the customer directly.
  • NotVerified – The employer/company has not been verified to run reports.
ReportViewerUrl string URL for the employer to view the background check on GoodHire.com
CandidateUrl string URL for the candidate to view the background check on GoodHire.com
SectionsContainingAlerts array of strings List of report sections that contain “alerts”
RequiredReportActions array of objects See required report actions object
ReportData object The detailed results and status of each section of the background check. (Only displayed if the ConsentReceived and IncludeReportData flags are set to “true” in the initial report creation request)

Candidate

{
    "FirstName": "Test",
    "LastName": "Candidate",
    "DateOfBirth": "01/01/1975",
    "SSN": "123-45-6789",
    "Email": "candidate@example.com",
    "Address": "123 Easy St",
    "City": "Ocala",
    "State": "FL",
    "Zip": "34470",
    "CandidateDriverRecords":[{
        "DriverLicenseNum": "B534-556-87-844-0",
        "DriverLicenseState": "FL"
    }]
 }

Attributes

Name Format Description
FirstName string
LastName string
Email string
DateOfBirth string In YYYY-MM-DD format
SSN string Social security number (with or without dashes)
Address string Street address
City string
State string 2-letter state abbreviation
Zip string 5 or 5+4 zip
CandidateDriverRecords array see candidate driver record object

Candidate Driver Record

{
    "DriverLicenseNum": "B53455687",
    "DriverLicenseState": "FL"
}

Attributes

Name Format Description
DriverLicenseNum string License number
DriverLicenseState string 2-letter state abbreviation

Create a report

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-sandbox.goodhire.com/v1/Report \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}'

This endpoint is used to order a GoodHire background check on the supplied candidate.

HTTP Request

POST /report

Request Body Parameters

Name Required Format Description
Candidate X object see candidate parameters below
Offer X object see offer parameters below
RequestOptions object see request options parameters below

Candidate Parameters

Name Required Format Description
FirstName X string
LastName X string
Email X string
DateOfBirth string In YYYY-MM-DD format
SSN string Social security number (with or without dashes)
Address string Street address
City string
State string 2-letter state abbreviation
Zip string 5 or 5+4 zip
CandidateDriverRecords array see candidate driver record parameters

Candidate Driver Record Parameters

Name Required Format Description
DriverLicenseNum string License number
DriverLicenseState string 2-letter state abbreviation

Offer parameters

Name Required Format Description
Products X array of strings Array of products being purchased. See Report Types.

Request Options parameters

Name Required Format Description
SendPurchaseReceipt boolean Specifies if email receipt will be sent to requestor after purchase. (default is true)
UrlCancel string URL where user will be redirected in case he/she decides to exist purchase flow (URL used on “cancel” buttons). If URL is not provided, “cancel” buttons will not be shown and user may simply exit the flow by closing the browser window.
UrlCallback string URL where user will be redirected when purchase is completed (URL used on “finish” buttons). If URL is not provided, “finish” buttons will not be shown and user may simply exit the flow by closing the browser window.
AffiliateId integer Affiliate account id
IsAllowedToUpdateOffer boolean Whether or not the user can navigate back to the “Select Report” page and change products that he/she will buy. (Only applies to the Partner Access “StepCheckout” endpoint)
SuppressCandidateSelfCompleteEmails boolean Whether or not emails to collect information from the candidate are disabled. (defaults to false)
SuppressCandidateConsentEmails boolean Whether or not emails to collect background check consent from the candidate are disabled. (defaults to false)
SuppressCandidatePHMConsentEmails boolean Whether or not emails to collect post-hire monitoring consent from the candidate are disabled. (defaults to false)
SuppressCandidateDrugConsentEmails boolean Whether or not emails to collect drug test consent from the candidate are disabled. (defaults to false)
ConsentReceived boolean Certification that you have already collected consent for the background check being ordered. Required to retrieve background check data as JSON via the API. (defaults to false)
IncludeReportData boolean Whether or not the results of the background check will be included as JSON in the created report object. (defaults to false)

Response

HTTP/1.1 201 Created
Content-Type: application/json
{
    "Id":"283397e8-1323-49dc-9116-b483a2842d2f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Status":"New",
    "StatusDetails":"New",
    "SectionsContainingAlerts":[

    ],
    "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cnduid=a6bd5796-46a2-4828-bc2b-fb9a1d2019a1",
    "RequiredReportActions":[

    ]
}

The API will respond with an HTTP 201 Created and the created report.

Retrieve a report

This endpoint retrieves the status of a report order and returns a report status.

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-sandbox.goodhire.com/v1/Report/2930ed9b-394b-4ca9-9aeb-1aa08b695ffa

HTTP Request

GET /report/:report_id

URL Parameters

Parameter Description
report_id The id of the report to retrieve

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
    "Id":"283397e8-1323-49dc-9116-b483a2842d2f",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Status":"New",
    "StatusDetails":"New",
    "SectionsContainingAlerts":[

    ],
    "ReportViewerUrl":"https://sandbox.goodhire.com/member/?_act=candidateReportAPI&_cnduid=a6bd5796-46a2-4828-bc2b-fb9a1d2019a1",
    "RequiredReportActions":[

    ]
}

The API will respond with an HTTP 200 Ok and the report.

Subscription

A subscription represents an Ongoing Alerts monitoring subscription on a candidate.

{
   "Id": "92e54341-710d-427b-8100-93ab4846fd8e",
   "ReportId": "9cfc505e-6d07-4af6-b416-e04c3f5cf553",
   "IsActive": true,
   "StartedOn": "2016-07-25T15:28:14.1312006-07:00",
   "LastStatus": "Clear",
   "ReportUrl": "https://sandbox.goodhire.com/member/?_act=phm_report&_cnduid=24bdd19b-c5fe-4927-b4cc-92e984dcd0e8",
   "Results": [{
        "Date": "2016-07-25T16:23:04.433-07:00",
        "Status": "Clear"
    }]
}

Attributes

Name Format Description
Id string Unique identifier for the subscription
ReportId string The id of the report order associated with the subscription
IsActive boolean Whether or not the subscription is active
StartedOn string The date when the subscription was started
LastStatus string The status of the most recent run of the subscription
ReportURL string The URL to view the subscription on GoodHire.com
Results array of objects an array of the previous runs of the subscription (see result object)

Result

A result represents a specific run of an Ongoing Alerts subscription.

{
    "Date": "2016-07-25T16:23:04.433-07:00",
    "Status": "Clear"
}

Attributes

Name Format Description
Date string The date when the run of the subscription occured
Status string The result of the subscription run

Create a subscription

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-sandbox.goodhire.com/v1/Subscription \
-d '{
    "ReportId":"9cfc505e-6d07-4af6-b416-e04c3f5cf553"
}'

This endpoint is used to order an Ongoing Alerts subscription on a candidate.

HTTP Request

POST /subscription

Request Body Parameters

Name Required Format Description
ReportId X string The id of a report order that has already been run on the candidate.

Response

HTTP/1.1 201 Created
Content-Type: application/json
{
   "Id": "2ab74118-dc99-489c-a66c-0f7a21ba8a8e",
   "ReportId": "9cfc505e-6d07-4af6-b416-e04c3f5cf553",
   "IsActive": true,
   "StartedOn": "2016-07-25T16:45:28.8176846-07:00",
   "LastStatus": "New",
   "ReportUrl": "https://sandbox.goodhire.com/member/?_act=phm_report&_cnduid=24bdd19b-c5fe-4927-b4cc-92e984dcd0e8",
   "Results": []
}

The API will respond with an HTTP 201 Created and the created subscription.

Retrieve a subscription

This endpoint retrieves the status of an Ongoing Alerts subscription.

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-sandbox.goodhire.com/v1/Subscription/2ab74118-dc99-489c-a66c-0f7a21ba8a8e

HTTP Request

GET /subscription/:subscription_id

URL Parameters

Parameter Description
subscription_id The id of the subscription to retrieve the status of

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Id": "2ab74118-dc99-489c-a66c-0f7a21ba8a8e",
   "ReportId": "9cfc505e-6d07-4af6-b416-e04c3f5cf553",
   "IsActive": true,
   "StartedOn": "2016-07-25T16:45:28.8176846-07:00",
   "LastStatus": "New",
   "ReportUrl": "https://sandbox.goodhire.com/member/?_act=phm_report&_cnduid=24bdd19b-c5fe-4927-b4cc-92e984dcd0e8",
   "Results": []
}

The API will respond with an HTTP 200 Ok and the subscription object.

Cancel a subscription

This endpoint cancels an Ongoing Alerts subscription.

curl -X "DELETE" -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-sandbox.goodhire.com/v1/subscription/2ab74118-dc99-489c-a66c-0f7a21ba8a8e

HTTP Request

DELETE /subscription/:subscription_id

URL Parameters

Parameter Description
subscription_id The id of the subscription to cancel

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Id": "92e54341-710d-427b-8100-93ab4846fd8e",
   "IsActive": false,
   "StartedOn": "2016-07-25T15:28:14.13-07:00",
   "LastStatus": "Canceled",
   "ReportUrl": "https://sandbox.goodhire.com/member/?_act=phm_report&_cnduid=24bdd19b-c5fe-4927-b4cc-92e984dcd0e8",
   "Results":[{
         "Date": "2016-07-25T16:23:04.433-07:00",
         "Status": "Canceled"
    }]
}

The API will respond with an HTTP 200 Ok and the canceled subscription object.