Companies
  • 18 Jan 2022
  • Dark
    Light
  • PDF

Companies

  • Dark
    Light
  • PDF

Create a Company


This API is for our HR business partners to signup new companies within GoodHire. If you are single company using GoodHire directly, you will not need to impliment this.

Whenever a new employer wants to start running background reports, a company and requestor must be created. This is a one-time process per employer.

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

HTTP Request

POST v1/Company

Request Body Paramaters

Name Requried Format Description
Name x 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 x string Street address
City x string
State x string 2-letter state abbreviation
Zip x 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
NumberEmployees string Number of employees
ExactChecksPerYear integer Number of expected checks annually
WebsiteUrl string Company website url
Industry string Business industry type. See Industry Values
The name, address, and TaxID are used to determine if the company already exists inour system. See Duplicate Resources for more information.

Industry Values


Industry 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

Request Example:

curl -i -X POST -H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api-sandbox.goodhire.com/v1/Company \
-d '{
  "name": "Test Inc.",
  "phone": "800-555-5555",
  "phoneExt": "12345",
  "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": "25"
}'

Response

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

Response Example

{
  "Status": "ReadyForVerification",
  "IsApproved": 0,
  "Id": "328d3016-71f3-4485-af20-06ce8044da18",
  "Name": "Test Inc.",
  "Phone": "800-555-5555",
  "PhoneExt": "12345",
  "StateOfIncorporation": "CA",
  "DBAName": "Doing Business As, Inc",
  "WebsiteURL": "www.testInc.com",
  "Industry": "Engineering",
  "NumberEmployees": "25",
  "Address": "123 Company St",
  "City": "Mountain View",
  "State": "CA",
  "Zip": "94043"
}

Response Attributes

Name Format Description
Status string Current verification status of a company. See Company Verification Status
IsApproved Integer Flag indicating if company verification process has been completed successfully (“1” – verification completed successfully)
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
NumberEmployees string Number of employees
ExactChecksPerYear integer Number of expected checks annually
WebsiteUrl string Company website url
Industry string Business industry type

Company Verification Status

  • ReadyForVerification - 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)
  • On-Hold - Verification process couldn’t be completed due to missing info and company/employer couldn’t be reached
  • Verified - Verification completed successfully

Retrieve a Company


This endpoint retrieves an existing company.

HTTP Request

GET v1/Company/:company_id

URL Parameters

Parameter Description
company_id The id of the company to retreive

Requset Example:

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

Response

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

Response Example:

{
  "Status": "ReadyForVerification",
  "IsApproved": 0,
  "Id": "328d3016-71f3-4485-af20-06ce8044da18",
  "Name": "Test Inc.",
  "Phone": "800-555-5555",
  "PhoneExt": "12345",
  "StateOfIncorporation": "CA",
  "DBAName": "Doing Business As, Inc",
  "WebsiteURL": "www.testInc.com",
  "Industry": "Engineering",
  "NumberEmployees": "25",
  "Address": "123 Company St",
  "City": "Mountain View",
  "State": "CA",
  "Zip": "94043"
}

Response Attributes

Name Format Description
Status string Current verification status of a company. See Company Verification Status listed above
IsApproved Integer Flag indicating if company verification process has been completed successfully (“1” – verification completed successfully)
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
NumberEmployees string Number of employees
ExactChecksPerYear integer Number of expected checks annually
WebsiteUrl string Company website url
Industry string Business industry type

Next Steps


Create a user - Requestors
Create a report - Reports


Was this article helpful?

What's Next