Companies

Updated on 18 Jan 2022

Print
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

Requestors