GoCo Public API (1.0.0)

Download OpenAPI specification:Download

URL: https://help.goco.io License: API License Agreement

Introduction

Welcome to the GoCo API documentation. GoCo is a platform to Level-Up your HR with Flexible Employee Management Software. With our API, you can access and manipulate data related to your company, such as employees, documents, reports, notifications, time off, time tracking and more.

Our API is designed for IT professionals who want to build their own solutions, integrate with other systems, and manage their data in ways they couldn't before. You can use our API to create custom workflows, automate tasks, generate reports, and more.

Getting Started

To get started with our API, you need to generate an API key in the GoCo Marketplace, and then use that API key to authenticate your requests. You can find more details on how to do that in the Authentication section.

Our API follows the OpenAPI Specification standard, which means you can use any compatible tool or library to interact with it. You can also explore our API using the interactive documentation below, which allows you to try out different endpoints and parameters.

If you have any questions, feedback, issues, or support requests related to our API, please contact us at https://help.goco.io. We are always happy to hear from you and help you with your integration.

We hope you enjoy using our API and find it useful for your HR needs.

Authentication

To use our API, you need to authenticate your requests with a valid API key that will grant you full permissions to access and manipulate data related to your company.

You can manage your API key in the GoCo Marketplace, under the API Credentials section. You can regenerate or revoke it at any time. Only users with Full Access Admin permissions can manage the API Credentials.

To authenticate your requests, you need to use the Bearer Authentication scheme, which means you need to send an HTTP header like this:

  Authorization: Bearer <YOUR_TOKEN_HERE>

where <YOUR_TOKEN_HERE> is your API key.

For example, if your API key is 1234567890abcdef, you would send a header like this:

  Authorization: Bearer 1234567890abcdef

You need to send this header with every request you make to our API. If you don’t send it, or if you send an invalid or revoked token, you will get an error response with a 401 Unauthorized status code.

Please keep your API key secret and secure. Do not share it with anyone or expose it in public. If you suspect that your API key has been compromised, please revoke it immediately and generate a new one.

Companies

Endpoints related to Companies

Retrieve a list of companies

get/companies

Retrieve a list of companies

SecurityApiKeyAuth

Responses

200

Success

Response Schema: application/json

Array of objects (CompanySchema)

Array

id	string Unique ID of this object
name	string Name
urlName	string URL Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
"name": "Demo Company 1",
"urlName": "demo-company-1"
}
]
}

Retrieve a list of custom fields for a company

get/companies/{companyUrlName}/custom_fields

Retrieve a list of custom fields for a company

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Responses

200

Success

Response Schema: application/json

Array of objects (CompanyCustomFieldsSchema)

Array

	Array of objects (CustomFieldDefinitionSchema) Custom Fields
name	string Section Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"fields": [{"description": "Sanitation",
"id": "AF4CT0nTHFVqawpAkuStgfQAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQzQJJuO92T-KiKqJ3NzoIfg",
"identifier": "cf__jyn_erso_kamino_molestiae",
"name": "Jyn Erso Kamino molestiae",
"possibleValues": [ ],
"type": "CURRENCY"
},
{"description": "I can’t abide these Jawas. Disgusting creatures.",
"id": "AGVDqEUSkLDhAYD56K1IpOUAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQcsm1IdOASXSETdHlU_oyuw",
"identifier": "cf__jango_fett_kamino_sunt",
"name": "Jango Fett Kamino sunt",
"possibleValues": [{"id": "AL7yWiK0xhdFdNtWOGA5GIIAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQ0BgwbpLHR1uOFTpzq7oGoA",
"title": "Option 1",
"value": 1
},
{"id": "AAMDMjE08_X2Bl7rbZNTyhAAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQTMnEv_SiR3mk4uDYwDQeSg",
"title": "Option 2",
"value": 2
},
{"id": "ABgA3IYM8rEM2yDmE1M8pFgAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQJvdSbXBrTqOeextBrgl2Ew",
"title": "Weird, Option 3",
"value": 3
}
],
"type": "DROPDOWN"
}
],
"name": ""
},
{"fields": [{"description": "I will start my operations here, and pull the rebels apart piece by piece.",
"id": "ANf-u6LgTWZI5TiI1h1odmkAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQVeXvVpHWSIqjPMAD6PEJ0g",
"identifier": "cf__hera_syndulla_hosnian_prime_natus",
"name": "Hera Syndulla Hosnian Prime natus",
"possibleValues": [{"id": "AFNYfr-iBxD9lg8odJFVQJ4AGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQXtZNyttSS7-d16jA4Qm6_w",
"title": "Option 1",
"value": 1
},
{"id": "ADNEdfHcduiwrk9NO-TPWuwAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQa_RNnq6QTKyIxPBugMgBmQ",
"title": "Option 2",
"value": 2
},
{"id": "AChtDw6fZJ3X3OICoYJ48MkAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQrna-CyCZQyWSxP_hloEnxg",
"title": "Weird, Option 3",
"value": 3
}
],
"type": "CHECKBOX_LIST"
}
],
"name": "Custom Section"
}
]
}

Retrieve a list of departments

get/companies/{companyUrlName}/departments

Retrieve a list of departments

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Responses

200

Success

Response Schema: application/json

Array of objects (DepartmentSchema)

Array

code	string Work Group code
id	string Unique ID of this object
name	string Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"code": "ASV21",
"id": "AJY901cFwZ46S93o0md3c0EACkRlcGFydG1lb",
"name": "Product"
},
{"code": "KSIC251",
"id": "AEw5ZlklT0bwlwtU86WUOeMACkRlcGFydG1lb",
"name": "Engineering"
}
]
}

Retrieve a list of job titles

get/companies/{companyUrlName}/job_titles

Retrieve a list of job titles

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Responses

200

Success

Response Schema: application/json

Array of objects (JobTitleSchema)

Array

code	string Work Group code
id	string Unique ID of this object
name	string Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"code": "MFwHhC2FYd2W9TgB",
"id": "AJO-QWkulBRK9cONSeoUHWkACEpvYlRpdGxlABD5oujSgGxCUYbiiQ5dIJJD",
"name": "IT Manager"
},
{"code": "Zv8c6SSJ9XxcSQIE",
"id": "ABq9PQj73Sv7s9OD6oKu5OAACEpvYlRpdGxlABAjQrOGritFIIdXXtG48s7N",
"name": "Marketing Analyst"
}
]
}

Retrieve a list of locations

get/companies/{companyUrlName}/locations

Retrieve a list of locations

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Responses

200

Success

Response Schema: application/json

Array of objects (LocationSchema)

Array

id	string Unique ID of this object
name	string Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
"name": "Company Location example"
}
]
}

Documents

Endpoints related to Documents

Retrieve a list of document templates

get/companies/{companyUrlName}/document_templates

Retrieve a list of document templates

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Responses

200

Success

Response Schema: application/json

Array of objects (DocumentTemplateSchema)

Array

description	string Description for this template
id	string Unique ID of this object
kind	string Type of document that this template uses Enum: "ATTACHED" "EMPLOYEE_PROVIDED" "I9_SUPPORTING" "I_9" "JOB_OFFER" "PERFORMANCE_REVIEW" "PERSONALIZED_AGREEMENT" "STATE_TAX" "W_4" "W_9"
name	string Name of this template

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"description": "Employee Offer Letter",
"id": "ALQ2H8vRqNAZHkgUFixtzWQAHVBlcnNvbmFsaXpl",
"kind": "JOB_OFFER",
"name": "YC Offer Letter"
}
]
}

Start a document for an employee

post/companies/{companyUrlName}/employees/{employeeId}/documents

Start a document for an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Request Body schema: application/json
required

documentTemplateId

required

string

Document Template ID

Responses

200

Success

Response Schema: application/json

object (EmployeeDocumentSchema)

completed	boolean True if this document has been completed
	object (EmployeeBasicFieldsSchema)
	object (EmployeeBasicFieldsSchema)
expirationDate	string <date> Date that this document expires
	object Most recently completed version of this document
id	string Unique ID of this object
name	string Name of this document
	Array of objects (EmployeeDocumentStepSchema) Document steps
	object Template that was used to create this document

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

application/json

{"documentTemplateId": "string"
}

Response samples

application/json

{"data": {"completed": false,
"createdBy": {"firstName": "GoCo",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Automation",
"middleInitial": "G",
"personalEmail": "[email protected]",
"preferredFirstName": "GoCo",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555-555-5555"
},
"employee": {"firstName": "John",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Doe",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "John",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "1234567890"
},
"expirationDate": "2019-12-31",
"file": {"url": "https://goco-uploads.s3.amazonaws.com/employee_documents/2537aeda-b772-4db3-b18c-08274dcf471c/AGXLKKkpk_fh8AGZzM3hKvMAClc0RG9jdW1lbnQAEM66T6SOu0IxtsOOmi58j_s.pdf"
},
"id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
"name": "Form W-4",
"steps": [{"assignedTo": {"firstName": "John",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Doe",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "John",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "1234567890"
},
"completed": false,
"completedAt": "2019-01-01T00:00:00.000Z",
"completedBy": {"firstName": "John",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Doe",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "John",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "1234567890"
},
"templateStep": {"action": "SIGN",
"assignee": "TEAM_MEMBER",
"order": 1
}
},
{"assignedTo": {"firstName": "John",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Doe",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "John",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "1234567890"
},
"completed": false,
"completedAt": "2019-01-01T00:00:00.000Z",
"completedBy": {"firstName": "John",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Doe",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "John",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "1234567890"
},
"templateStep": {"action": "ACKNOWLEDGE",
"assignee": "FULL_ACCESS_DOCUMENT_PERMISSIONS",
"order": 2
}
}
],
"template": {"id": "AGXLKKkpk_fh8AGZzM3hKvMAClc0VGVtcGxhdGUAIgCgRlDm1bdHUZDk78PIn5-RAHpIbDHuVUB1nafug24phGM",
"name": "Form W-4"
}
}
}

Upload a document to an employee's profile

post/companies/{companyUrlName}/employees/{employeeId}/documents/one_off_upload

Upload a document to an employee's profile

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Request Body schema: application/json
required

name required	string Document Name
fileUrl required	string <uri> Document URL
employeeCanView	boolean Employee Can View Document?
managerCanView	boolean Manager Can View Document?

Responses

200

Success

Response Schema: application/json

object (EmployeeDocumentSchema)

completed	boolean True if this document has been completed
	object (EmployeeBasicFieldsSchema)
	object (EmployeeBasicFieldsSchema)
expirationDate	string <date> Date that this document expires
	object Most recently completed version of this document
id	string Unique ID of this object
name	string Name of this document
	Array of objects (EmployeeDocumentStepSchema) Document steps
	object Template that was used to create this document

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

application/json

{"employeeCanView": true,
"fileUrl": "http://example.com",
"managerCanView": true,
"name": "string"
}

Response samples

application/json

{"data": {"completed": true,
"createdBy": {"firstName": "GoCo",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Automation",
"middleInitial": "G",
"personalEmail": "[email protected]",
"preferredFirstName": "GoCo",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555-555-5555"
},
"employee": {"firstName": "John",
"id": "c1ebeab0-d030-4035-8455-ac5178df1379",
"lastName": "Test33",
"middleInitial": "K",
"personalEmail": "[email protected]",
"preferredFirstName": "Test11",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555-555-5555"
},
"expirationDate": "",
"file": {"url": "https://goco-uploads.s3.amazonaws.com/employee_documents/2537aeda-b772-4db3-b18c-08274dcf471c/AGXLKKkpk_fh8AGZzM3hKvMAClc0RG9jdW1lbnQAEM66T6SOu0IxtsOOmi58j_s.pdf"
},
"id": "AHuxgU-k0qR11WUDLDSPs1YAEEF0dGFjaGVk",
"name": "Document Name",
"steps": [{"assignedTo": {"firstName": "GoCo",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Automation",
"middleInitial": "G",
"personalEmail": "[email protected]",
"preferredFirstName": "GoCo",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555-555-5555"
},
"completed": true,
"completedAt": "2023-07-10T15:35:56-07:00",
"completedBy": {"firstName": "GoCo",
"id": "2537aeda-b772-4db3-b18c-08274dcf471c",
"lastName": "Automation",
"middleInitial": "G",
"personalEmail": "[email protected]",
"preferredFirstName": "GoCo",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555-555-5555"
},
"templateStep": {"action": "UPLOAD",
"assignee": "DOCUMENT_SENDER",
"order": 1
}
}
],
"template": { }
}
}

Employees

Endpoints related to Employees

Bulk update custom fields for an employee

patch/companies/{companyUrlName}/employees/{employeeId}/custom_fields/bulk_update

Bulk update custom fields for an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Request Body schema: application/json
required

required

Array of objects

Array

identifier required	string Custom Field Identifier
	object Custom Field Currency Value. Valid when Custom Field Type in `[CURRENCY]`
dateValue	string <date> Custom Field Date Value. Valid when Custom Field Type in `[DATE]`
intValue	integer Custom Field Integer Value. Valid when Custom Field Type in `[DROPDOWN, RADIO_LIST]`
intValues	Array of integers Custom Field Integer Values. Valid for custom field types in `[CHECKBOX_LIST]`
numberValue	number Custom Field Number Value. Valid when Custom Field Type in `[NUMBER]`
stringValue	string Custom Field String Value. Valid when Custom Field Type in `[SHORT_TEXT, LONG_TEXT]`

Responses

200

Success

Response Schema: application/json

object

Employee Custom Fields Updated

Array of objects

Array

displayValue	string Custom Field Display Value
identifier	string Custom Field Identifier

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

application/json

{"fields": [{"currencyValue": {"currency": "AED",
"value": 0
},
"dateValue": "2019-08-24",
"identifier": "string",
"intValue": 0,
"intValues": [0
],
"numberValue": 0,
"stringValue": "string"
}
]
}

Response samples

application/json

{"data": {"fields": [{"displayValue": "Custom Field 1 Value",
"identifier": "cf__custom_field_1"
},
{"displayValue": "Custom Field 2 Value",
"identifier": "cf__custom_field_2"
}
]
}
}

Create an employee

post/companies/{companyUrlName}/employees

Create an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

Request Body schema: application/json
required

firstName required	string First Name
lastName required	string Last Name
insertionSource	string Insertion Source Enum: "GREENHOUSE" "JAZZ_HR" "LEVER" "PUBLIC_API" "WORKABLE"
personalEmail	string <email> Personal Email
workflowTemplateId	string Hiring Workflow Template ID
	object Employee's address information
companyClassId	string Company class ID
compensationNote	string Compensation note for this employee
departmentId	string Department ID
dob	string <date> Date of birth
employmentType	string Employment type Enum: "CONTRACTOR" "FULL_TIME" "PART_TIME" "TEMPORARY"
jobTitleId	string Job Title ID
legalSex	string Legal Sex Enum: "FEMALE" "MALE"
locationId	string Work location ID
managerId	string Manager ID
payrollScheduleId	string Payroll Schedule ID
ssn	string Social Security Number
startDate	string <date> Start date
	object Wage rate
wageType	string Wage type Enum: "FIXED_AMOUNT" "HOURLY" "MONTHLY" "QUARTERLY" "SALARY" "WEEKLY"
workEmail	string Work Email
workPhone	string Work Phone

Responses

200

Success

Response Schema: application/json

object (EmployeeSchema)

	object Address
	object Department
	object Division
dob	string <date> Date of Birth
efmlaBalance	number <double> Emergency Family and Medical Leave Hours Balance
	Array of objects Emergency Contacts
employmentStatus	string Employment Status Enum: "ACTIVE" "ON_LEAVE" "PENDING" "TERMINATED"
employmentType	string Employment Type Enum: "CONTRACTOR" "FULL_TIME" "PART_TIME" "TEMPORARY"
epslBalance	number <double> Emergency Paid Sick Leave Hours Balance
extraWithholding	number <double> Extra Withholding
firstName	string First Name
genderIdentity	string Gender Identity
id	string Unique ID of this object
insertionSource	string Insertion Source Enum: "ADP_WORKFORCE" "GREENHOUSE" "HIRING_WIZARD" "IMPORT" "JAZZ_HR" "LEVER" "PAYCHEX" "PUBLIC_API" "QUICK_ADD" "UNKNOWN" "WORKABLE"
isManager	boolean Is Manager?
	object Job Title
lastName	string Last Name
legalSex	string Legal Sex Enum: "FEMALE" "MALE"
	object Location
	object (EmployeeBasicFieldsSchema)
middleInitial	string Middle Initial Name
	object Non Work State Withholding
	object Payroll Schedule
personalBalance	number <double> Personal Leave Hours Balance
personalEmail	string <email> Personal Email
	object Photo
preferredFirstName	string Preferred First Name
preferredPronoun	string Preferred Pronoun Enum: "EY_EM_EIRS" "HE_HIM_HIS" "NAME_NAME_NAMES" "PER_PER_PERS" "SHE_HER_HERS" "SIE_HIR_HIRS" "THEY_THEM_THEIRS" "ZEE_HERE_HERES" "ZE_HIR_HIRS" "ZE_ZIM_ZIMS" "ZE_ZIR_ZIRS"
rehire	boolean Rehire?
residentState	string Resident State
sickBalance	number <double> Sick Leave Hours Balance
ssn	string Social Security Number
startDate	string <date> Start date of the employee
taxFilingStatus	string Tax Filing Status Enum: "exempt" "head_of_household" "married" "married_withhold_as_single" "single"
terminationDay	string <date> Termination date
terminationNote	string Termination Note
terminationStatus	string Termination Status Enum: "OFF" "ON" "PENDING" "TERMINATING"
terminationType	string Termination Type Enum: "DECEASED" "GROSS_MISCONDUCT" "INVOLUNTARY" "UNKNOWN" "VOLUNTARY_NOT_REGRETTED" "VOLUNTARY_REGRETTED"
	object Time Off Policy
	object Time Tracking Policy
uniqueOnboardingLink	string Onboarding Link
vacationBalance	number <double> Vacation Hours Balance
w420202MultipleJobs	boolean w4 2020 - Multiple Jobs
w420203DependentWithholding	number <double> w4 2020 - Dependent Withholding
w420204aOtherIncome	number <double> w4 2020 - Other Income
w420204bDeductions	number <double> w4 2020 - Deductions
w42020IncomeBelow200k	boolean w4 2020 - Income Below 200k
w42020OtherDependents	integer <int64> w4 2020 - Other Dependents
w42020QualifiedChildren	integer <int64> w4 2020 - Qualified Children
w4Version	string How and which W-4 fields are available on this employee Enum: "PRE2020" "REVISION2020"
	object Wage Rate
wageType	string Wage Type Enum: "FIXED_AMOUNT" "HOURLY" "MONTHLY" "QUARTERLY" "SALARY" "WEEKLY"
withholdingAllowances	integer <int64> Withholding Allowances
workEmail	string <email> Work Email
workPhone	string Work Phone

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

application/json

{"address": {"address1": "string",
"address2": "string",
"city": "string",
"country": "string",
"phone": "string",
"postalCode": "string",
"state": "string"
},
"companyClassId": "string",
"compensationNote": "string",
"departmentId": "string",
"dob": "2019-08-24",
"employmentType": "CONTRACTOR",
"jobTitleId": "string",
"legalSex": "FEMALE",
"locationId": "string",
"managerId": "string",
"payrollScheduleId": "string",
"ssn": "string",
"startDate": "2019-08-24",
"wageRate": {"currency": "AED",
"value": 0
},
"wageType": "FIXED_AMOUNT",
"workEmail": "string",
"workPhone": "string"
}

Response samples

application/json

{"data": {"address": {"address1": "97243 Von Wall",
"address2": "square K",
"city": "Kesslerchester",
"country": "US",
"phone": "270-293-1016",
"postalCode": "77865",
"state": "CA"
},
"department": {"code": "ASV21",
"id": "AAoe1J6kJJMBRy7IUaC-3zEACkRlcGFydG1lbnQAEAcdTtlmxUQTkUsyee3qTWA",
"name": "heuristic Music 93"
},
"division": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpdmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"dob": "1982-05-30",
"efmlaBalance": 0,
"employmentStatus": "ACTIVE",
"employmentType": "TEMPORARY",
"epslBalance": 0,
"extraWithholding": 0,
"firstName": "Darnell",
"genderIdentity": "FEMALE",
"id": "f9b0a835-866d-4277-99f1-d1caebffe5ca",
"insertionSource": "UNKNOWN",
"isManager": false,
"jobTitle": {"id": "ADvpk8UFfBgwzyl3CJZLipgACEpvYlRpdGxlABAvGKBWr6BIp5D-1WneYw7V",
"name": "Default Title"
},
"lastName": "Morar",
"legalSex": "FEMALE",
"location": {"id": "AOIW0DGFSR3-hj0C93NFuM0ACExvY2F0aW9uABD2Ksx1R0hIB5qdPLa9VDFG",
"name": "Headquarters"
},
"manager": {"firstName": "Cristi",
"id": "30602a86-5c6f-4afc-b10c-ae99b4bfd862",
"lastName": "D'Amore",
"middleInitial": "F",
"personalEmail": "[email protected]",
"preferredFirstName": "Cristi",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555 3430234"
},
"middleInitial": "K",
"nonWorkStateWithholding": {"allowances": "2",
"exempt": false,
"extraWithholding": 2000,
"filingStatus": "married"
},
"payrollSchedule": {"id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
"name": "Default"
},
"personalBalance": 0,
"personalEmail": "[email protected]",
"preferredFirstName": "Darnell",
"preferredPronoun": "THEY_THEM_THEIRS",
"rehire": false,
"residentState": "CA",
"sickBalance": 0,
"ssn": "538-68-8947",
"startDate": "2023-06-24",
"taxFilingStatus": "married_withhold_as_single",
"terminationDay": "2023-07-05",
"terminationNote": "note",
"terminationStatus": "OFF",
"terminationType": "INVOLUNTARY",
"timeOffPolicy": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpaSf2dmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"timeTrackingPolicy": {"id": "ALjpB4RvxEHRadJrqNiB8oAAElRpbWVUcmFja2luZ1BvbGljeQAQKMfMFhDgRti5AWCeCiH7qA",
"name": "Becki Simonis"
},
"uniqueOnboardingLink": "https://goco-client-test.herokuapp.com/login",
"vacationBalance": 0,
"w420202MultipleJobs": false,
"w420203DependentWithholding": 0,
"w420204aOtherIncome": 0,
"w420204bDeductions": 0,
"w42020IncomeBelow200k": true,
"w42020OtherDependents": 2,
"w42020QualifiedChildren": 5,
"w4Version": "REVISION2020",
"wageRate": {"currency": "USD",
"value": 55650
},
"wageType": "SALARY",
"withholdingAllowances": 1,
"workEmail": "[email protected]",
"workPhone": "555 3430234"
}
}

Retrieve a list of compensation methods for an employee

get/companies/{companyUrlName}/employees/{employeeId}/compensation_methods

Retrieve a list of compensation methods for an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Responses

200

Success

Response Schema: application/json

Array of objects (EmployeeCompensationMethodsSchema)

Array

accountNickname	string Employee created label for account
amount	number <double> Either a flat dollar amount or percentage to be deposited to this account
amountType	string Indicate if the amount is fixed or a percentage of gross pay Enum: "DOLLARS" "PERCENT"
	object Details for bank account
currency	string Currency used Enum: "AED" "ARS" "AUD" "BGN" "BHD" "CAD" "CHF" "CLP" "CNH" "CNY" "CZK" "DKK" "EUR" "FJD" "GBP" "HKD" "HUF" "IDR" "ILS" "INR" "ISK" "JPY" "KES" "KWD" "MAD" "MXN" "MYR" "NOK" "NZD" "PHP" "PKR" "PLN" "QAR" "RON" "RSD" "RUB" "SAR" "SEK" "SGD" "TRY" "TWD" "UAH" "USD" "VND" "ZAR"
formattedDepositAmount	string Formatted amount, including the currency or percent symbol.
id	string Unique identifier for the compensation method
paymentMethod	string Direct deposit or paper check Enum: "DIRECT_DEPOSIT" "PAPER_CHECK"
priority	integer <int64> Order in which funds from gross pay will be allocated to account

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"accountNickname": "Account Nickname",
"amount": 100,
"amountType": "DOLLARS",
"bankAccount": {"accountNumber": "1234567890",
"accountType": "CHECKING",
"bank": {"name": "Bank Name"
},
"routingNumber": "123456789"
},
"currency": "USD",
"formattedDepositAmount": "$100",
"paymentMethod": "DIRECT_DEPOSIT",
"priority": 1
}
]
}

Retrieve a list of custom fields for an employee

get/companies/{companyUrlName}/employees/{employeeId}/custom_fields

Retrieve a list of custom fields for an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Responses

200

Success

Response Schema: application/json

Array of objects (EmployeeCustomFieldsSchema)

Array

	Array of objects Custom Fields
name	string Section Name

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"fields": [{"definition": {"description": "Sanitation",
"id": "AF4CT0nTHFVqawpAkuStgfQAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQzQJJuO92T-KiKqJ3NzoIfg",
"identifier": "cf__jyn_erso_kamino_molestiae",
"name": "Jyn Erso Kamino molestiae",
"possibleValues": [ ],
"type": "CURRENCY"
},
"displayValue": "$ 12.34"
},
{"definition": {"description": "I can’t abide these Jawas. Disgusting creatures.",
"id": "AGVDqEUSkLDhAYD56K1IpOUAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQcsm1IdOASXSETdHlU_oyuw",
"identifier": "cf__jango_fett_kamino_sunt",
"name": "Jango Fett Kamino sunt",
"possibleValues": [{"id": "AL7yWiK0xhdFdNtWOGA5GIIAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQ0BgwbpLHR1uOFTpzq7oGoA",
"title": "Option 1",
"value": 1
},
{"id": "AAMDMjE08_X2Bl7rbZNTyhAAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQTMnEv_SiR3mk4uDYwDQeSg",
"title": "Option 2",
"value": 2
},
{"id": "ABgA3IYM8rEM2yDmE1M8pFgAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQJvdSbXBrTqOeextBrgl2Ew",
"title": "Weird, Option 3",
"value": 3
}
],
"type": "DROPDOWN"
},
"displayValue": "Option 2"
}
],
"name": ""
},
{"fields": [{"definition": {"description": "I will start my operations here, and pull the rebels apart piece by piece.",
"id": "ANf-u6LgTWZI5TiI1h1odmkAFUN1c3RvbUZpZWxkRGVmaW5pdGlvbgAQVeXvVpHWSIqjPMAD6PEJ0g",
"identifier": "cf__hera_syndulla_hosnian_prime_natus",
"name": "Hera Syndulla Hosnian Prime natus",
"possibleValues": [{"id": "AFNYfr-iBxD9lg8odJFVQJ4AGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQXtZNyttSS7-d16jA4Qm6_w",
"title": "Option 1",
"value": 1
},
{"id": "ADNEdfHcduiwrk9NO-TPWuwAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQa_RNnq6QTKyIxPBugMgBmQ",
"title": "Option 2",
"value": 2
},
{"id": "AChtDw6fZJ3X3OICoYJ48MkAGEN1c3RvbUZpZWxkUG9zc2libGVWYWx1ZQAQrna-CyCZQyWSxP_hloEnxg",
"title": "Weird, Option 3",
"value": 3
}
],
"type": "CHECKBOX_LIST"
},
"displayValue": "Weird, Option 3"
}
],
"name": "Custom Section"
}
]
}

Retrieve a list of employees

get/companies/{companyUrlName}/employees

Retrieve a list of employees

SecurityApiKeyAuth

Request

path Parameters

companyUrlName

required

string

Company URL Name

query Parameters

page	integer <int64> Page Example: page=1
maxPerPage	integer <int64> Max per page Example: maxPerPage=10
employmentStatus	Array of strings Filter by employment statuses Items Enum: "ACTIVE" "ON_LEAVE" "PENDING" "TERMINATED" Example: employmentStatus=ACTIVE,PENDING,TERMINATED,ON_LEAVE

Responses

200

Success

Response Schema: application/json

	Array of objects (EmployeeSchema)
maxPerPage	integer Max per page
page	integer Current page
total	integer Total count
totalPages	integer Total pages

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"address": {"address1": "97243 Von Wall",
"address2": "square K",
"city": "Kesslerchester",
"country": "US",
"phone": "270-293-1016",
"postalCode": "77865",
"state": "CA"
},
"department": {"code": "ASV21",
"id": "AAoe1J6kJJMBRy7IUaC-3zEACkRlcGFydG1lbnQAEAcdTtlmxUQTkUsyee3qTWA",
"name": "heuristic Music 93"
},
"division": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpdmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"dob": "1982-05-30",
"efmlaBalance": 0,
"emergencyContacts": [{"name": "Primary Contact",
"phone": "270-293-1018",
"priority": 1
},
{"name": "Secondary Contact",
"phone": "270-293-1019",
"priority": 2
}
],
"employmentStatus": "ACTIVE",
"employmentType": "TEMPORARY",
"epslBalance": 0,
"extraWithholding": 0,
"firstName": "Darnell",
"genderIdentity": "FEMALE",
"id": "f9b0a835-866d-4277-99f1-d1caebffe5ca",
"insertionSource": "UNKNOWN",
"isManager": false,
"jobTitle": {"id": "ADvpk8UFfBgwzyl3CJZLipgACEpvYlRpdGxlABAvGKBWr6BIp5D-1WneYw7V",
"name": "Default Title"
},
"lastName": "Morar",
"legalSex": "FEMALE",
"location": {"id": "AOIW0DGFSR3-hj0C93NFuM0ACExvY2F0aW9uABD2Ksx1R0hIB5qdPLa9VDFG",
"name": "Headquarters"
},
"manager": {"firstName": "Cristi",
"id": "30602a86-5c6f-4afc-b10c-ae99b4bfd862",
"lastName": "D'Amore",
"middleInitial": "F",
"personalEmail": "[email protected]",
"preferredFirstName": "Cristi",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555 3430234"
},
"middleInitial": "K",
"nonWorkStateWithholding": {"allowances": "2",
"exempt": false,
"extraWithholding": 2000,
"filingStatus": "married"
},
"payrollSchedule": {"id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
"name": "Default"
},
"personalBalance": 0,
"personalEmail": "[email protected]",
"preferredFirstName": "Darnell",
"preferredPronoun": "THEY_THEM_THEIRS",
"rehire": false,
"residentState": "CA",
"sickBalance": 0,
"ssn": "538-68-8947",
"startDate": "2023-06-24",
"taxFilingStatus": "married_withhold_as_single",
"terminationDay": "2023-07-05",
"terminationNote": "note",
"terminationStatus": "OFF",
"terminationType": "INVOLUNTARY",
"timeOffPolicy": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpaSf2dmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"timeTrackingPolicy": {"id": "ALjpB4RvxEHRadJrqNiB8oAAElRpbWVUcmFja2luZ1BvbGljeQAQKMfMFhDgRti5AWCeCiH7qA",
"name": "Becki Simonis"
},
"uniqueOnboardingLink": "https://goco-client-test.herokuapp.com/login",
"vacationBalance": 0,
"w420202MultipleJobs": false,
"w420203DependentWithholding": 0,
"w420204aOtherIncome": 0,
"w420204bDeductions": 0,
"w42020IncomeBelow200k": true,
"w42020OtherDependents": 2,
"w42020QualifiedChildren": 5,
"w4Version": "REVISION2020",
"wageRate": {"currency": "USD",
"value": 55650
},
"wageType": "SALARY",
"withholdingAllowances": 1,
"workEmail": "[email protected]",
"workPhone": "555 3430234"
}
],
"maxPerPage": 25,
"page": 2,
"total": 2,
"totalPages": 1
}

Retrieve a list of state withholdings for an employee

get/companies/{companyUrlName}/employees/{employeeId}/state_withholdings

Retrieve a list of state withholdings for an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Responses

200

Success

Response Schema: application/json

Array of objects (EmployeeStateWithholdingsSchema)

Array

allowNonResidentExemption	boolean Allow Non Resident Exemption
allowances	string Allowances
exempt	boolean Exempt
exemptReason	string Exempt Reason Enum: "NON_RESIDENT" "OTHER"
	object Exception Form
exemptionOptions	string Exemption Options Enum: "NONE" "SIMPLE" "UPLOAD"
	Array of objects Fields
filingStatus	string Filing Status
	object Form
id	string Unique ID of this object
isWorkState	boolean Is Work State
signedAt	string <date-time> Signed At
state	string State

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": [{"allowNonResidentExemption": false,
"allowances": "1",
"exempt": false,
"exemptReason": "OTHER",
"exemptionForm": {"title": "IT-2104-E",
"value": "https://assets.goco.io/state-forms/ny_withholding_exemption_form.pdf"
},
"exemptionOptions": "NONE",
"fields": [{"allowNegative": null,
"dataType": "STRING",
"default": null,
"fieldName": "filingStatus",
"hint": null,
"label": "Personal Exemption",
"legacy": null,
"maxValue": null,
"minValue": null,
"perPayPeriod": true,
"possibleValues": [{"title": "None",
"value": "0"
},
{"title": "Single",
"value": "S"
},
{"title": "Single, Head of Family",
"value": "H"
},
{"title": "Married",
"value": "M"
},
{"title": "Married Filing Separately",
"value": "MS"
}
],
"required": true,
"subLabel": null,
"useCalculator": false,
"value": "H"
}
],
"filingStatus": "H",
"form": {"title": "A4",
"value": "https://assets.goco.io/state-forms/al_withholding_form.pdf"
},
"id": "ANPAWSvANFgR9jm1IdpMpQEADUFsV2l0aGhvbGRpbmcAEMy9gKcFHUK4tS6Mn6ALsB4",
"isWorkState": false,
"signedAt": "2024-03-12T07:23:14-07:00",
"state": "AL"
},
{"allowNonResidentExemption": false,
"allowances": "9",
"exempt": false,
"exemptReason": "OTHER",
"exemptionForm": {"title": "IT-2104-E",
"value": "https://assets.goco.io/state-forms/ny_withholding_exemption_form.pdf"
},
"exemptionOptions": "NONE",
"fields": [{"allowNegative": null,
"dataType": "STRING",
"default": null,
"fieldName": "filingStatus",
"hint": "This determines the tax rate you will file as. Make sure you are selecting the correct option as it will affect the amount withheld from your paycheck for taxes.",
"label": "Exemptions Claimed",
"legacy": null,
"maxValue": null,
"minValue": null,
"perPayPeriod": true,
"possibleValues": [{"title": "You claim yourself (1 exemption)",
"value": "you"
},
{"title": "You claim yourself and your spouse (2 exemptions)",
"value": "you_and_spouse"
},
{"title": "Head of Household, and you claim yourself (2 exemptions)",
"value": "head_of_household"
}
],
"required": true,
"subLabel": null,
"useCalculator": false,
"value": "head_of_household"
}
],
"filingStatus": "head_of_household",
"form": {"title": "AR4EC",
"value": "https://assets.goco.io/state-forms/ar_withholding_form.pdf"
},
"id": "ANz6sJ06gR58mikgTS5WNrEADUFyV2l0aGhvbGRpbmcAEKnjD7YqUkvNpczpj-uUqwE",
"isWorkState": false,
"signedAt": "2024-03-12T07:23:14-07:00",
"state": "AR"
}
]
}

Retrieve an employee

get/companies/{companyUrlName}/employees/{employeeId}

Retrieve an employee

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Responses

200

Success

Response Schema: application/json

object (EmployeeSchema)

	object Address
	object Department
	object Division
dob	string <date> Date of Birth
efmlaBalance	number <double> Emergency Family and Medical Leave Hours Balance
	Array of objects Emergency Contacts
employmentStatus	string Employment Status Enum: "ACTIVE" "ON_LEAVE" "PENDING" "TERMINATED"
employmentType	string Employment Type Enum: "CONTRACTOR" "FULL_TIME" "PART_TIME" "TEMPORARY"
epslBalance	number <double> Emergency Paid Sick Leave Hours Balance
extraWithholding	number <double> Extra Withholding
firstName	string First Name
genderIdentity	string Gender Identity
id	string Unique ID of this object
insertionSource	string Insertion Source Enum: "ADP_WORKFORCE" "GREENHOUSE" "HIRING_WIZARD" "IMPORT" "JAZZ_HR" "LEVER" "PAYCHEX" "PUBLIC_API" "QUICK_ADD" "UNKNOWN" "WORKABLE"
isManager	boolean Is Manager?
	object Job Title
lastName	string Last Name
legalSex	string Legal Sex Enum: "FEMALE" "MALE"
	object Location
	object (EmployeeBasicFieldsSchema)
middleInitial	string Middle Initial Name
	object Non Work State Withholding
	object Payroll Schedule
personalBalance	number <double> Personal Leave Hours Balance
personalEmail	string <email> Personal Email
	object Photo
preferredFirstName	string Preferred First Name
preferredPronoun	string Preferred Pronoun Enum: "EY_EM_EIRS" "HE_HIM_HIS" "NAME_NAME_NAMES" "PER_PER_PERS" "SHE_HER_HERS" "SIE_HIR_HIRS" "THEY_THEM_THEIRS" "ZEE_HERE_HERES" "ZE_HIR_HIRS" "ZE_ZIM_ZIMS" "ZE_ZIR_ZIRS"
rehire	boolean Rehire?
residentState	string Resident State
sickBalance	number <double> Sick Leave Hours Balance
ssn	string Social Security Number
startDate	string <date> Start date of the employee
taxFilingStatus	string Tax Filing Status Enum: "exempt" "head_of_household" "married" "married_withhold_as_single" "single"
terminationDay	string <date> Termination date
terminationNote	string Termination Note
terminationStatus	string Termination Status Enum: "OFF" "ON" "PENDING" "TERMINATING"
terminationType	string Termination Type Enum: "DECEASED" "GROSS_MISCONDUCT" "INVOLUNTARY" "UNKNOWN" "VOLUNTARY_NOT_REGRETTED" "VOLUNTARY_REGRETTED"
	object Time Off Policy
	object Time Tracking Policy
uniqueOnboardingLink	string Onboarding Link
vacationBalance	number <double> Vacation Hours Balance
w420202MultipleJobs	boolean w4 2020 - Multiple Jobs
w420203DependentWithholding	number <double> w4 2020 - Dependent Withholding
w420204aOtherIncome	number <double> w4 2020 - Other Income
w420204bDeductions	number <double> w4 2020 - Deductions
w42020IncomeBelow200k	boolean w4 2020 - Income Below 200k
w42020OtherDependents	integer <int64> w4 2020 - Other Dependents
w42020QualifiedChildren	integer <int64> w4 2020 - Qualified Children
w4Version	string How and which W-4 fields are available on this employee Enum: "PRE2020" "REVISION2020"
	object Wage Rate
wageType	string Wage Type Enum: "FIXED_AMOUNT" "HOURLY" "MONTHLY" "QUARTERLY" "SALARY" "WEEKLY"
withholdingAllowances	integer <int64> Withholding Allowances
workEmail	string <email> Work Email
workPhone	string Work Phone

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

Response samples

application/json

{"data": {"address": {"address1": "97243 Von Wall",
"address2": "square K",
"city": "Kesslerchester",
"country": "US",
"phone": "270-293-1016",
"postalCode": "77865",
"state": "CA"
},
"department": {"code": "ASV21",
"id": "AAoe1J6kJJMBRy7IUaC-3zEACkRlcGFydG1lbnQAEAcdTtlmxUQTkUsyee3qTWA",
"name": "heuristic Music 93"
},
"division": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpdmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"dob": "1982-05-30",
"efmlaBalance": 0,
"employmentStatus": "ACTIVE",
"employmentType": "TEMPORARY",
"epslBalance": 0,
"extraWithholding": 0,
"firstName": "Darnell",
"genderIdentity": "FEMALE",
"id": "f9b0a835-866d-4277-99f1-d1caebffe5ca",
"insertionSource": "UNKNOWN",
"isManager": false,
"jobTitle": {"id": "ADvpk8UFfBgwzyl3CJZLipgACEpvYlRpdGxlABAvGKBWr6BIp5D-1WneYw7V",
"name": "Default Title"
},
"lastName": "Morar",
"legalSex": "FEMALE",
"location": {"id": "AOIW0DGFSR3-hj0C93NFuM0ACExvY2F0aW9uABD2Ksx1R0hIB5qdPLa9VDFG",
"name": "Headquarters"
},
"manager": {"firstName": "Cristi",
"id": "30602a86-5c6f-4afc-b10c-ae99b4bfd862",
"lastName": "D'Amore",
"middleInitial": "F",
"personalEmail": "[email protected]",
"preferredFirstName": "Cristi",
"preferredPronoun": "THEY_THEM_THEIRS",
"workEmail": "[email protected]",
"workPhone": "555 3430234"
},
"middleInitial": "K",
"nonWorkStateWithholding": {"allowances": "2",
"exempt": false,
"extraWithholding": 2000,
"filingStatus": "married"
},
"payrollSchedule": {"id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
"name": "Default"
},
"personalBalance": 0,
"personalEmail": "[email protected]",
"preferredFirstName": "Darnell",
"preferredPronoun": "THEY_THEM_THEIRS",
"rehire": false,
"residentState": "CA",
"sickBalance": 0,
"ssn": "538-68-8947",
"startDate": "2023-06-24",
"taxFilingStatus": "married_withhold_as_single",
"terminationDay": "2023-07-05",
"terminationNote": "note",
"terminationStatus": "OFF",
"terminationType": "INVOLUNTARY",
"timeOffPolicy": {"id": "ABLDYLb23CN1xPmcwCDyw5kACERpaSf2dmlzaW9uABCgLoSPWpVFKKlcQ1e6Puue",
"name": "Default"
},
"timeTrackingPolicy": {"id": "ALjpB4RvxEHRadJrqNiB8oAAElRpbWVUcmFja2luZ1BvbGljeQAQKMfMFhDgRti5AWCeCiH7qA",
"name": "Becki Simonis"
},
"uniqueOnboardingLink": "https://goco-client-test.herokuapp.com/login",
"vacationBalance": 0,
"w420202MultipleJobs": false,
"w420203DependentWithholding": 0,
"w420204aOtherIncome": 0,
"w420204bDeductions": 0,
"w42020IncomeBelow200k": true,
"w42020OtherDependents": 2,
"w42020QualifiedChildren": 5,
"w4Version": "REVISION2020",
"wageRate": {"currency": "USD",
"value": 55650
},
"wageType": "SALARY",
"withholdingAllowances": 1,
"workEmail": "[email protected]",
"workPhone": "555 3430234"
}
}

Update an employee

patch/companies/{companyUrlName}/employees/{employeeId}

The effective date will be set as follows: For incomplete hires, we prioritize the employee's start date; if unavailable, we consider the creation date, defaulting to today's date if neither is provided. For completed hires, we use the start date if it's in the future; otherwise, we default to today's date

SecurityApiKeyAuth

Request

path Parameters

companyUrlName required	string Company URL Name
employeeId required	string Employee ID

Request Body schema: application/json
required

firstName	string First Name
lastName	string Last Name
	object Employee's address information
companyClassId	string Company class ID
compensationNote	string Compensation note for this employee
departmentId	string Department ID
dob	string <date> Date of birth
employmentType	string Employment type Enum: "CONTRACTOR" "FULL_TIME" "PART_TIME" "TEMPORARY"
jobTitleId	string Job Title ID
legalSex	string Legal Sex Enum: "FEMALE" "MALE"
locationId	string Work location ID
managerId	string Manager ID
payrollScheduleId	string Payroll Schedule ID
ssn	string Social Security Number
startDate	string <date> Start date
	object Wage rate
wageType	string Wage type Enum: "FIXED_AMOUNT" "HOURLY" "MONTHLY" "QUARTERLY" "SALARY" "WEEKLY"
workEmail	string Work Email
workPhone	string Work Phone

Responses

200

Success

Response Schema: application/json

object (EmployeeSchema)

	object Address
	object Department
	object Division
dob	string <date> Date of Birth
efmlaBalance	number <double> Emergency Family and Medical Leave Hours Balance
	Array of objects Emergency Contacts
employmentStatus	string Employment Status Enum: "ACTIVE" "ON_LEAVE" "PENDING" "TERMINATED"
employmentType	string Employment Type Enum: "CONTRACTOR" "FULL_TIME" "PART_TIME" "TEMPORARY"
epslBalance	number <double> Emergency Paid Sick Leave Hours Balance
extraWithholding	number <double> Extra Withholding
firstName	string First Name
genderIdentity	string Gender Identity
id	string Unique ID of this object
insertionSource	string Insertion Source Enum: "ADP_WORKFORCE" "GREENHOUSE" "HIRING_WIZARD" "IMPORT" "JAZZ_HR" "LEVER" "PAYCHEX" "PUBLIC_API" "QUICK_ADD" "UNKNOWN" "WORKABLE"
isManager	boolean Is Manager?
	object Job Title
lastName	string Last Name
legalSex	string Legal Sex Enum: "FEMALE" "MALE"
	object Location
	object (EmployeeBasicFieldsSchema)
middleInitial	string Middle Initial Name
	object Non Work State Withholding
	object Payroll Schedule
personalBalance	number <double> Personal Leave Hours Balance
personalEmail	string <email> Personal Email
	object Photo
preferredFirstName	string Preferred First Name
preferredPronoun	string Preferred Pronoun Enum: "EY_EM_EIRS" "HE_HIM_HIS" "NAME_NAME_NAMES" "PER_PER_PERS" "SHE_HER_HERS" "SIE_HIR_HIRS" "THEY_THEM_THEIRS" "ZEE_HERE_HERES" "ZE_HIR_HIRS" "ZE_ZIM_ZIMS" "ZE_ZIR_ZIRS"
rehire	boolean Rehire?
residentState	string Resident State
sickBalance	number <double> Sick Leave Hours Balance
ssn	string Social Security Number
startDate	string <date> Start date of the employee
taxFilingStatus	string Tax Filing Status Enum: "exempt" "head_of_household" "married" "married_withhold_as_single" "single"
terminationDay	string <date> Termination date
terminationNote	string Termination Note
terminationStatus	string Termination Status Enum: "OFF" "ON" "PENDING" "TERMINATING"
terminationType	string Termination Type Enum: "DECEASED" "GROSS_MISCONDUCT" "INVOLUNTARY" "UNKNOWN" "VOLUNTARY_NOT_REGRETTED" "VOLUNTARY_REGRETTED"
	object Time Off Policy
	object Time Tracking Policy
uniqueOnboardingLink	string Onboarding Link
vacationBalance	number <double> Vacation Hours Balance
w420202MultipleJobs	boolean w4 2020 - Multiple Jobs
w420203DependentWithholding	number <double> w4 2020 - Dependent Withholding
w420204aOtherIncome	number <double> w4 2020 - Other Income
w420204bDeductions	number <double> w4 2020 - Deductions
w42020IncomeBelow200k	boolean w4 2020 - Income Below 200k
w42020OtherDependents	integer <int64> w4 2020 - Other Dependents
w42020QualifiedChildren	integer <int64> w4 2020 - Qualified Children
w4Version	string How and which W-4 fields are available on this employee Enum: "PRE2020" "REVISION2020"
	object Wage Rate
wageType	string Wage Type Enum: "FIXED_AMOUNT" "HOURLY" "MONTHLY" "QUARTERLY" "SALARY" "WEEKLY"
withholdingAllowances	integer <int64> Withholding Allowances
workEmail	string <email> Work Email
workPhone	string Work Phone

401

Not Authorized

404

Not Found

422

Unprocessable Content

429

Too Many Requests

Request samples

GoCo Public API (1.0.0)

Introduction

Getting Started

Authentication

Companies

Retrieve a list of companies

Response Schema: application/json

Retrieve a list of custom fields for a company

path Parameters

Response Schema: application/json

Retrieve a list of departments

path Parameters

Response Schema: application/json

Retrieve a list of job titles

path Parameters

Response Schema: application/json

Retrieve a list of locations

path Parameters

Response Schema: application/json

Documents

Retrieve a list of document templates

path Parameters

Response Schema: application/json

Start a document for an employee

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Upload a document to an employee's profile

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Employees

Bulk update custom fields for an employee

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Create an employee

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Retrieve a list of compensation methods for an employee

path Parameters

Response Schema: application/json

Retrieve a list of custom fields for an employee

path Parameters

Response Schema: application/json

Retrieve a list of employees

path Parameters

query Parameters

Response Schema: application/json

Retrieve a list of state withholdings for an employee

path Parameters

Response Schema: application/json

Retrieve an employee

path Parameters

Response Schema: application/json

Update an employee

path Parameters

Request Body schema: application/jsonrequired

Response Schema: application/json

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required