NAV

API

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

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-pre.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 reports ordered via its methods will return dummy data. When you are ready to begin ordering real background reports, change your base endpoint to the production endpoint above and contact api@goodhire.com to receive a production API key.

Getting Started

These guides will walk you through the process of setting up the GoodHire API and running a background report. All examples provided use the test base endpoint:

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

Authentication

Make sure to replace YOUR_API_KEY with your actual API key in the code snippets below.

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

Click here to request a test API key if you haven’t already done so.

Integration types

There are two types of integrations in the GoodHire API, each with its own getting started guide:

Customer guide

This guide will walk you through the process of setting up a direct customer API integration and running a test background report:

Setup

Before you get started ordering reports, you must first create your company and requestor. This is a one-time process.

Create a company

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company \
-d '{ 
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100"
}'

All report requests in the GoodHire API are tied to a company object. The company represents your company that will be running background reports.

To create your company, make a POST with your company’s information to:

https://api-pre.goodhire.com/v1/Company

Response

{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100",
    "Status": "new",
    "IsApproved": 0
}

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

Create a requestor

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor \
-d '{ 
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "RoleType": "employerAdmin",
    "Phone": "(415)1112222",
    "Title": "HR Manager"
}'

All reports in the GoodHire API are also associated with a requestor object. The requestor represents the employee at your company who is running the background report on the candidate. There can be multiple requestors per company corresponding to the different employees who will be running background reports.

To create your requestor, make a POST with the requestor’s information to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor

Where :company_id is the id of the company that you created above.

Response

{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager"
}

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

Complete account setup email

Once your requestor has been created, he/she will receive an email from support@goodhire.com with the subject “Action Required: Complete Registration”. Click on the link within this email to set the requestor’s GoodHire.com password and finish the account setup process.

Create a report order

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Report \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "YOUR_EMAIL"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}'

Now that you have created a company and requestor, you are ready to order your first background report. Within the GoodHire API, background reports are ordered by creating a report order object. The report order contains information on the candidate being screened as well as the type of GoodHire background report being run.

To create a report order, make a POST to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor/:requestor_id/Report

Where :company_id is the id of your company and :requestor_id is the id of your requestor.

Response

{ 
    "Id": "2930ed9b-394b-4ca9-9aeb-1aa08b695ffa", 
    "Candidate":{
        "FirstName": "Test",
        "FastName": "Candidate",
        "Email": "YOUR_EMAIL"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    },
    "RequestOptions": {
        "SendPurchaseReceipt": true,
        "PaymentType": "InvoiceImitation",
        "SendSelfCompleteCandidateEmails": true
    }
}

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

Retrieve a report status

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Report/2930ed9b-394b-4ca9-9aeb-1aa08b695ffa
HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Id": "2930ed9b-394b-4ca9-9aeb-1aa08b695ffa",
   "Status":"MissingInput",
   "SectionsContainingAlerts":[

   ],
   "ReportViewerUrl":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104&showConsent=1"
    }]
}

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

To do this, make a GET to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor/:requestor_id/Report/:report_order_id

Where :company_id is the id of your company, :requestor_id is the id of your requestor, and report_order_id is the id of your report order.

The API will return a report status object with information on the GoodHire background report tied to the report order you created. The report status contains the current status of your background report (Processing, MissingInfo, CompletedClear, etc.), a description of actions (if any) required for the report to run, and a URL to view the complete report 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

Partner guide

This guide will walk you through the process of setting up a partner API integration and running a test background report on behalf of an employer in your system:

Setup

Whenever a new employer on your platform wants to start running background reports, you must first create a company and requestor for that employer. This is a one-time process per employer.

Create a company

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company \
-d '{ 
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100"
}'

All report requests in the GoodHire API are tied to a company object. The company represents the employer on your platform that will be ordering background reports.

To create a company, make a POST with the company’s information to:

https://api-pre.goodhire.com/v1/Company

Response

{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100",
    "Status": "new",
    "IsApproved": 0
}

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

Create a requestor

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor \
-d '{ 
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "RoleType": "employerAdmin",
    "Phone": "(415)1112222",
    "Title": "HR Manager"
}'

All reports in the GoodHire API are also associated with a requestor object. The requestor represents the employee of the employer on your platform who will be running background reports. There can be multiple requestors per company corresponding to the multiple user accounts under a single employer that exist on your platform.

To create your requestor, make a POST with the requestor’s information to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor

Where :company_id is the id of the company that you created above.

Response

{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager"
}

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

Complete account setup email

Once your requestor has been created, he/she will receive an email from support@goodhire.com with the subject “Action Required: Complete Registration”. Click on the link within this email to set the requestor’s GoodHire.com password and finish the account setup process.

Request a redirect URL

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/PartnerAppAccess/StepSelectReport \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "YOUR_EMAIL"
    },
    "Offer":{
        "Products": ["GHAPIBIZPARTNERFLOW"]
    }
}'

Now that you have created a company and requestor for the user on your platform, the user can start ordering background reports.

In partner integrations, background reports are ordered by making a request to one of the Partner Access endpoints. In this example, we will use the Select Report endpoint.

To order a report for the employer, make a POST with a report order object to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor/:requestor_id/PartnerAppAccess/StepSelectReport

Where :company_id is the id of the employer’s company and :requestor_id is the id of the employer’s requestor that you created above.

Response

{
    "Url":"https://staging.goodhire.com/member/?_act=partnerAppAccess&accesstoken=540e9275-cef9-4160-be07-b259bd2d5f5b&_oid=08be4b0b-892a-4ca3-ab97-8179913604ee&_page=businessPartnerSelectReport",
    "Report":{
      "Id":"08be4b0b-892a-4ca3-ab97-8179913604ee",
      "Candidate":{
         "FirstName":"Test",
         "LastName":"Candidate",
         "Email":"YOUR_EMAIL"
      },
      "Offer":{
         "Products":[
            "GHAPIBIZPARTNERFLOW"
         ]
      },
      "RequestOptions": {
        "PaymentType": "Website",
        "IsAllowedToUpdateOffer": false,
        "ShowLoadingIcon": false
      }
    }
}

The API will respond with an HTTP 200 Ok. The body of the response will contain the submitted report order. The id field within the report is the unique id of your report order. Save this value for use later.

The response body will also contain a url field. This is a tokenized URL to the purchase flow on GoodHire.com.

Redirect to the purchase flow

Use the tokenized URL that you received in the previous step to redirect the employer on your platform to the partner purchase flow on GoodHire.com. In the partner purchase flow, the employer can select their report type, complete the purchase, and configure how they will collect the candidates information/consent.

To complete a checkout in our test environment, you can use the dummy credit card information listed in the test data section.

Retrieve a report status

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Report/08be4b0b-892a-4ca3-ab97-8179913604ee

Now that that the employer on your platform has ordered a background report, you can use the API to view the report’s status and results.

To do this, make a GET to:

https://api-pre.goodhire.com/v1/Company/:company_id/Requestor/:requestor_id/Report/:report_order_id

Where :company_id is the id of the employer’s company, :requestor_id is the id of the employer’s user/requestor, and report_order_id is the id of the user’s report order.

Response

{
   "Id":"08be4b0b-892a-4ca3-ab97-8179913604ee",
   "Status":"MissingInput",
   "SectionsContainingAlerts":[

   ],
   "ReportViewerUrl":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104&showConsent=1"
    }]
}

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

If the employer’s candidate has not yet provided consent via the sent email, your response will look similar to the one on the right. Once the candidate has completed these steps, the Status field of the response will be updated to “Processing” and then “Completed” when the report is finished.

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

Authentication

curl -i -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.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 request 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",
    "Status":"CompletedAlert",
    "StatusDetails":"Alert",
    "SectionsContainingAlerts":[
        "Sex Offender List Check",
        "National Criminal Records Check",
        "Misc Court Records",
        "SSN Trace + Address History"
    ],
    "ReportViewerUrl":"https://staging.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, email api@goodhire.com.

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 status object
Company object The updated company object
SubscriptionStatus object The updated subscription object

Report Types

When creating a report order, the product array within the offer object should contain one value from the “Reports” section below. This is the type of GoodHire background report 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 GoodHire report.

Reports:

Additional Checks:

Existing Resources

The GoodHire API is designed to detect existing GoodHire customers whenever possible. This occurs in one of two ways:

Depending on whether the existing customer is linked with your API integration already or not, the response of the API will differ.

Not Linked

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "customer@example.com",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager",
    "Credits": 0
}

If the company/requestor you try to create is not already linked to your API account, the following will occur:

  1. The API will link the existing company/requestor to your API account.
  2. For security, this link will be temporarily ‘flagged’ and the user will not be able to order reports or perform GET status requests using the company/requestor id.
  3. The GoodHire integrations team will reach out to the customer, confirm the action, and unflag the account.
  4. The user will then be able to order reports normally.

Already Linked

HTTP/1.1 409 Conflict
Content-Type: application/json
{
   "StatusCode":"Conflict",
   "StatusMessage":"Unable to create customer. Customer with the same 'email' already exists under partner.",
   "AdditionalInfo":{
      "ErrorText":"",
      "FieldErrors":[

      ]
   }
}

If the company/requestor you try to create is already linked to your API account, the API will return an HTTP 409 Conflict error.

Test Data

Report Status Alerts

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

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

Partner Access Checkout

When testing Partner Access endpoints, you can use the following credit card information to simulate a checkout on Goodhire.com

Field Value
name any name
CC number 5555555555554444
CVV code any 3-digit number
expiration date any future date
zip code any 5-digit number

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

Company

The company represents the company, organization, or employer that is ordering the background report. All background reports in the GoodHire API are tied to a company.

{
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteURL": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100",
    "Status": "new",
    "isApproved": 0
}

Attributes

Name Format Description
Id string Unique identifier for the company
Name string Company name
Phone string Phone number in XXXXXXXXXX or XXX-XXX-XXXX format
PhoneExt string Phone extension
TaxId string Federal tax Id/EIN (employer identification number).
Address string Street address
City string
State string 2-letter state abbreviation
Zip string 5 or 5+4 zip code
StateOfIncorporation string 2-letter state abbreviation, where company is registered
DBAName string “doing business as” – the operating name of a company, as opposed to the legal name of the company
WebsiteUrl string Company website url
Industry string Business industry type. Should match one of the following values: Accounting, Agriculture, Architecture, Construction, Defense, Education, Energy/Utility, Engineering, Financial, Food, Beverage, Government, Healthcare, Insurance, Legal, Leisure/Hospitality, Manufacturing, Marketing/PR, Media, Non-profit, Professional services, Real estate, Retail, Security, Sharing Economy, Staffing, Technology, Transportation, Travel
NumberEmployees string Number of employees
Status string Company verification status:
  • new – Approval process hasn’t started
  • pending – Company verification in progress
  • escalation – Verification process requires additional documents (if company/employer can be contacted, GoodHire support team will reach out)
  • suspended – Verification process couldn’t be completed due to missing info and company/employer couldn’t be reached
  • verified – Verification completed successfully
IsApproved integer Flag indicating if company verification process has been completed successfully (“1” – verification completed successfully)

Create a company

This endpoint creates a company.

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company \
-d '{ 
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100"
}'

HTTP Request

POST /company

Arguments

Name Requried Format Description
Name X string Company name
Phone X string Phone number in XXXXXXXXXX or XXX-XXX-XXXX format
PhoneExt string Phone extension
TaxId string Federal tax Id/EIN (employer identification number)
Address X string Street address
City X string
State X string 2-letter state abbreviation
Zip X string 5 or 5+4 zip code
StateOfIncorporation X string 2-letter state abbreviation, where company is registered
DBAName string “doing business as” – the operating name of a company, as opposed to the legal name of the company
WebsiteUrl string Company website url
Industry string Business industry type. Should match one of the following values: Accounting, Agriculture, Architecture, Construction, Defense, Education, Energy/Utility, Engineering, Financial, Food, Beverage, Government, Healthcare, Insurance, Legal, Leisure/Hospitality, Manufacturing, Marketing/PR, Media, Non-profit, Professional services, Real estate, Retail, Security, Sharing Economy, Staffing, Technology, Transportation, Travel
NumberEmployees string Number of employees

Response

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100",
    "Status": "new",
    "IsApproved": 0
}

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

Retrieve a company

This endpoint retrieves an existing company.

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72

HTTP Request

GET /company/:company_id

URL Parameters

Parameter Description
company_id The id of the company to retrieve

Response

HTTP/1.1 200 OK
Content-Type: application/json
{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Name": "Test Inc.",
    "Phone": "800-555-5555",
    "PhoneExt": "x12345",
    "Address": "123 Company St",
    "City": "Mountain View",
    "State": "CA",
    "Zip": "94043",
    "StateOfIncorporation": "CA",
    "DBAName": "Doing Business As, Inc",
    "WebsiteUrl": "www.testInc.com",
    "Industry": "Engineering",
    "NumberEmployees": "100",
    "Status": "new",
    "IsApproved": 0
}

The API will respond with an HTTP 200 Ok and the retrieved company

Requestor

The requestor represents the employee at the hiring company who is running the background report. There can be multiple requestors per company corresponding to the different employees who run background reports.

{
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "customer@example.com ",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager",
    "Credits": 100
}

Attributes

Name Format Description
Id string Unique identifier for the requestor
Email string
FirstName string
LastName string
RoleType string Requestor’s report access privilege:
  • employerAdmin - Requestor can access all reports ordered by company
  • employerReadAndOrder - Requestor can only access reports he/she has ordered
  • employerOrderOnly - Requestor can order reports, but cannot access any reports
Phone string
Title string Position title
Credits integer The number of GoodHire credits in the requestor’s account.

Create a requestor

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor \
-d '{ 
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "RoleType": "employerAdmin",
    "Phone": "(415)1112222",
    "Title": "HR Manager"
}'

This endpoint creates a requestor.

HTTP Request

POST /company/:company_id/requestor/:requestor_id

URL Parameters

Parameter Description
company_id The id of the company to associate the requestor with

Arguments

Name Required Format Description
Email X string
FirstName X string
LastName X string
RoleType string The requestor’s report access privilege:
  • employerAdmin - Requestor can access all reports ordered by company
  • employerReadAndOrder - Requestor can only access reports he/she has ordered
  • employerOrderOnly - Requestor can order reports, but cannot access any reports
Phone string
Title string Position title

Response

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "YOUR_EMAIL",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager",
    "Credits": 0
}

The API will respond with a HTTP 201 Created and the created requestor.

In addition, the API will send an email to the newly created requestor with a link to GoodHire.com. From this link, the requestor can setup a GoodHire.com site password and provide any missing fields that are needed for the requestor’s company to be verified.

Retrieve a requestor

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72

This endpoint retrieves an existing requestor.

HTTP Request

GET /company/:company_id/requestor/:requestor_id

URL Parameters

Parameter Description
company_id The id of the requestor’s company
requestor_id The id of the requestor to retrieve

Response

HTTP/1.1 200 OK
Content-Type: application/json
{ 
    "Id": "8f9640d4-66ce-4661-8144-24695c902b72",
    "Email": "customer@example.com",
    "FirstName": "Test",
    "LastName": "Requestor",
    "Phone": "(415)1112222",
    "Title": "HR Manager",
    "Credits": 0
}

The API will respond with a HTTP 200 Ok and the retrieved requestor.

Report Order

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

{ 
    "Id": "2930ed9b-394b-4ca9-9aeb-1aa08b695ffa",
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    },
    "RequestOptions":{
        "SendPurchaseReceipt": true
    }
}

Attributes

Name Format Description
Id string Unique identifier for the report order
Candidate object see candidate object
Offer object see offer object
RequestOptions object see request options object

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

Offer

{
    "Products": ["RPT_BASIC"]
}

Attributes

Name Format Description
CatalogId string Key of the product/ report being purchased. See Report Types.
Products array of strings Array of products being purchased. See Report Types.

Request Options

{
    "SendPurchaseReceipt": true,
    "UrlCancel":"http://www.page_if_cancel.com",
    "UrlCallback":"http://www.page_if_finish.com",
    "AffiliateId": 4,
    "IsAllowedToUpdateOffer":true,
    "CountyAdditionalFeeHandling":"AlwaysAccept",
    "SuppressCandidateSelfCompleteEmails":false,
    "SuppressCandidateConsentEmails":false,
    "SuppressCandidatePHMConsentEmails":false,
    "SuppressCandidateDrugConsentEmails":false
}

Attributes

Name Format Description
SendPurchaseReceipt boolean Specifies if email receipt will be sent to requestor after purchase. (default is true)
UrlCancel string The URL used on “cancel” buttons in the GoodHire purchase flow. If it is not provided, “cancel” buttons will not be shown and the user may simply exit the flow by closing the browser window.
UrlCallback string The URL used on the “finish” button at the end of the GoodHire purchase flow. If it is not provided, the button will not be shown and the 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)
SendSelfCompleteCandidateEmails DEPRECATED boolean Determines if GoodHire will email the candidate to provide consent and information for the ordered background report. (defaults to true)

Note: This field has been deprecated, please use the SuppressCandidate- fields instead.

Create a report order

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Report \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}'

This endpoint is used to order a background report on the supplied candidate. The API will email the candidate with a link to provide consent to the background report and to confirm his or her information.

HTTP Request

POST /company/:company_id/requestor/:requestor_id/report

URL Parameters

Parameter Description
company_id The id of the company ordering the report
requestor_id The id of the requestor ordering the 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)

Response

HTTP/1.1 201 Created
Content-Type: application/json
{ 
    "Id": "2930ed9b-394b-4ca9-9aeb-1aa08b695ffa", 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}

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

Report Status

The report status represents the current status of a background report that has been ordered via the creation of a report order object.

{
  "Id":"a6ed0d64-19b9-4073-8000-96c10a8057db",
   "Status":"MissingInput",
   "SectionsContainingAlerts":[ ],
   "ReportViewerUrl":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104&showConsent=1"
    }]
}

Attributes

Name Format Description
Id string The unique id for the report. Same as report order id.
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.
  • Completed – Report processing completed.(Partner orders only)
  • CompletedAlert – Report processing completed, and the report contains alerts that require review. (Customer orders only)
  • CompletedClear – Report execution completed, and all sections are clear. (Customer orders only)
StatusDetail 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.
  • Completed – Report processing completed. (Partner orders only)
  • Clear – The report completed without alerts. (Customer orders only)
  • Alert – The report completed with alerts. (Customer orders only)
  • 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 of the page on GoodHire site, where report can be viewed in HTML format
SectionsContainingAlerts array of strings List of report sections that contain “alerts”
RequiredReportActions array of objects See required report actions object

Required Report Actions

Attributes

Name Format Description
Type string Action type
description string Description of activity that needs to be performed
Url string URL of the page on Goodhire.com where the requestor can complete the activity
UrlCandidate string URL of the page on Goodhire.com, where the candidate can complete the activity

Retrieve a report status

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

curl -H "Authorization: ApiKey YOUR_API_KEY" \
https://api-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Report/2930ed9b-394b-4ca9-9aeb-1aa08b695ffa

HTTP Request

GET /company/:company_id/requestor/:requestor_id/report/:report_order_id

URL Parameters

Parameter Description
company_id The id of the company that ordered the report
requestor_id The id of the requestor who ordered the report
report_order_id The id of the report order to retrieve the status of

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Status":"MissingInput",
   "SectionsContainingAlerts":[

   ],
   "ReportViewerUrl":"https://staging.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://staging.goodhire.com/member/?_act=dashboard",
        "UrlCandidate":"https://staging.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://staging.goodhire.com/member/?_act=dashboard&__at=a6ed0d64-19b9-4073-8000-96c10a8057db",
        "UrlCandidate":"https://staging.goodhire.com/member/self-complete?_cnduid=9e55a103-bffd-4a92-ba83-d700ec309171&_oid=286503104&showConsent=1"
    }]
}

The API will respond with an HTTP 200 Ok and a report status for the specific report order.

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://staging.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-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Subscription \
-d '{
    "ReportId":"9cfc505e-6d07-4af6-b416-e04c3f5cf553"
}'

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

HTTP Request

POST /company/:company_id/requestor/:requestor_id/subscription

URL Parameters

Parameter Description
company_id The id of the company ordering the subscription
requestor_id The id of the requestor ordering the 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://staging.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-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/Subscription/2ab74118-dc99-489c-a66c-0f7a21ba8a8e

HTTP Request

GET /company/:company_id/requestor/:requestor_id/subscription/:subscription_id

URL Parameters

Parameter Description
company_id The id of the company that ordered the subscription
requestor_id The id of the requestor who ordered the subscription
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://staging.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-pre.goodhire.com/v1/Company/8f9640d4-66ce-4661-8144-24695c902b72/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/subscription/2ab74118-dc99-489c-a66c-0f7a21ba8a8e

HTTP Request

DELETE /company/:company_id/requestor/:requestor_id/subscription/:subscription_id

URL Parameters

Parameter Description
company_id The id of the company that ordered the subscription
requestor_id The id of the requestor who ordered the subscription
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://staging.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.

Partner Access

These endpoints allow partners to transfer employers from their platforms to purchase background reports on GoodHire.com.

All partner access endpoints return tokenized URLs to redirect the employer to purchase on GoodHire.com. These tokenized URLs are valid for one use and expire after 24 hours. If a new tokenized URL is needed, another call to the relevant partner access endpoint should be made.

Select Report

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/partnerappaccess/stepselectreport \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products":["GHAPIBIZPARTNERFLOW"]
    }
}'

This endpoint takes in a candidate’s information from the HR platform and returns a URL to redirect the user(hiring employer) to GoodHire.com. On GoodHire, the employer can select the type of background report they would like to run and checkout.

HTTP Request

POST /company/:company_id/requestor/:requestor_id/partnerappaccess/stepselectreport

URL Parameters

Parameter Description
company_id The id of the company ordering the report
requestor_id The id of the requestor ordering the report

Request Body Parameters

See Create a Report Order

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Url": "https://staging.goodhire.com/member/?_act=partnerAppAccess&accesstoken=6c8c684b-74ac-4c73-9f4c-ceb58582b8a0&_oid=91cede38-577c-4b69-ac72-55471169b071&_page=businessPartnerSelectReport",
   "Report":    {
        "Id": "4ac7744e-0360-47df-9191-78c78019ef19",
        "Candidate":{
            "FirstName": "Test",
            "LastName": "Candidate",
            "Email": "candidate@example.com"
      },
      "Offer":{
          "products":["GHAPIBIZPARTNERFLOW"]
      }
   }
}

The API will respond with an HTTP 200 Ok. The body of the response will include the created report order and a URL to direct the hiring employer to the GoodHire.com pricing page, where they can select their report type and checkout.

Checkout

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/partnerappaccess/stepcheckout \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products": ["RPT_BASIC"]
    }
}'

This endpoint takes in a candidate’s information and background report from the HR platform and returns a URL to redirect the user(hiring employer) to the checkout page of GoodHire.com. Here, the employer can complete their purchase.

HTTP Request

POST /company/:company_id/requestor/:requestor_id/partnerappaccess/stepcheckout

URL Parameters

Parameter Description
company_id The id of the company ordering the report
requestor_id The id of the requestor ordering the report

Request Body Parameters

See Create a Report Order

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Url": "https://staging.goodhire.com/member/?_act=partnerAppAccess&accesstoken=6c8c684b-74ac-4c73-9f4c-ceb58582b8a0&_oid=91cede38-577c-4b69-ac72-55471169b071&_page=businessPartnerCheckout",
   "Report":    {
      "Id": "4ac7744e-0360-47df-9191-78c78019ef19",
      "Candidate":
      {
          "FirstName": "Test",
          "LastName": "Candidate",
          "Email": "candidate@example.com"
      },
      "Offer":
      {
          "Products": ["RPT_BASIC"]
      }
   }
}

The API will respond with an HTTP 200 Ok. The body of the response will include the created report order and a URL to direct the hiring employer to the GoodHire.com checkout page, where they can select they can purchase the selected report type.

Checkout Iframe

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/partnerappaccess/stepcheckoutshortiframe \
-d '{ 
    "Candidate":{
        "FirstName": "Test",
        "LastName": "Candidate",
        "Email": "candidate@example.com"
    },
    "Offer":{
        "Products":["RPT_BASIC"]
    }
}'

This endpoint takes in a candidate’s information and background report from the HR platform and returns an iframe-friendly URL of the GoodHire.com checkout page that the partner can embed on their site. The user (hiring employer) can purchase GoodHire reports via this iframe without leaving the partner’s platform.

HTTP Request

POST /company/:company_id/requestor/:requestor_id/partnerappaccess/stepcheckoutshortiframe

URL Parameters

Parameter Description
company_id The id of the company ordering the report
requestor_id The id of the requestor ordering the report

Request Body Parameters

See Create a Report Order

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Url": "https://staging.goodhire.com/member/?_act=partnerAppAccess&accesstoken=2e188ff6-41b8-422a-8026-77c5938bf18e&_oid=aced418a-0fbf-4d46-a63d-6d499b9eff95&_page=businessPartnerCheckoutShortIframe",
   "Report":    {
      "Id": "4ac7744e-0360-47df-9191-78c78019ef19",
      "Candidate":
      {
          "FirstName": "Test",
          "LastName": "Candidate",
          "Email": "candidate@example.com"
      },
      "Offer":
      {
          "Products":["RPT_BASIC"]
      }
   }
}

The API will respond with an HTTP 200 Ok. The body of the response will include the created report order and an iframe-friendly URL that can be used to embed the GoodHire.com checkout page in an iframe on the partner’s site.

Credits

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-pre.goodhire.com/v1/Company/4fecc200-51fa-4ba0-a7c5-298aa8967768/Requestor/8f9640d4-66ce-4661-8144-24695c902b72/partnerappaccess/stepcredits \
-d '{
      "SendPurchaseReceipt": true,
      "UrlCancel": "www.goodhire.com",
      "UrlCallback": "www.goodhire.com/member",
      "AffiliateId": "75" 
}'

This endpoint takes in request options object and returns a URL to direct the employer to the credit calculator on GoodHire.com. From here the employer can purchase volume packs of credits and receive discounts.

HTTP Request

POST /company/:company_id/requestor/:requestor_id/partnerappaccess/stepcredits

URL Parameters

Parameter Description
company_id The id of the company purchasing credits
requestor_id The id of the requestor purchasing credits

Request Body Parameters

See request options object.

Response

HTTP/1.1 200 Ok
Content-Type: application/json
{
   "Url": "https://staging.goodhire.com/member/?_act=partnerAppAccess&accesstoken=4662efdd-2c9e-4de8-af28-d6573b4d2f9a&_oid=5e801e90-681b-4299-9909-1bda4a5d5876&_page=BusinessPartnerVolumePricing",
   "RequestOptions":    {
      "SendPurchaseReceipt": true,
      "UrlCancel": "www.goodhire.com",
      "UrlCallback": "www.goodhire.com/member",
      "AffiliateId": "75",
      "IsAllowedToUpdateOffer": false
   }
}

The API will respond with an HTTP 200 Ok. The body of the response will include the submitted request options as well as a URL to direct the hiring employer to the credit calculator on GoodHire.com.