Download OpenAPI specification:Download
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.
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.
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.
{- "data": [
- {
- "id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
- "name": "Demo Company 1",
- "urlName": "demo-company-1"
}
]
}
Retrieve a list of custom fields for a company
{- "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
{- "data": [
- {
- "code": "ASV21",
- "id": "AJY901cFwZ46S93o0md3c0EACkRlcGFydG1lb",
- "name": "Product"
}, - {
- "code": "KSIC251",
- "id": "AEw5ZlklT0bwlwtU86WUOeMACkRlcGFydG1lb",
- "name": "Engineering"
}
]
}
Retrieve a list of job titles
{- "data": [
- {
- "code": "MFwHhC2FYd2W9TgB",
- "id": "AJO-QWkulBRK9cONSeoUHWkACEpvYlRpdGxlABD5oujSgGxCUYbiiQ5dIJJD",
- "name": "IT Manager"
}, - {
- "code": "Zv8c6SSJ9XxcSQIE",
- "id": "ABq9PQj73Sv7s9OD6oKu5OAACEpvYlRpdGxlABAjQrOGritFIIdXXtG48s7N",
- "name": "Marketing Analyst"
}
]
}
Retrieve a list of locations
{- "data": [
- {
- "id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
- "name": "Company Location example"
}
]
}
Retrieve a list of document templates
Success
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "data": [
- {
- "description": "Employee Offer Letter",
- "id": "ALQ2H8vRqNAZHkgUFixtzWQAHVBlcnNvbmFsaXpl",
- "kind": "JOB_OFFER",
- "name": "YC Offer Letter"
}
]
}
Start a document for an employee
Success
object (EmployeeDocumentSchema) | |||||||||||||||||||
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "documentTemplateId": "string"
}
{- "data": {
- "completed": false,
- "createdBy": {
- "firstName": "GoCo",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Automation",
- "middleInitial": "G",
- "preferredFirstName": "GoCo",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555-555-5555"
}, - "employee": {
- "firstName": "John",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Doe",
- "middleInitial": "K",
- "preferredFirstName": "John",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "1234567890"
}, - "expirationDate": "2019-12-31",
- "id": "AODiB4QAMchj0PlhVmAS3eYAClc0RG9jdW1lbn",
- "name": "Form W-4",
- "steps": [
- {
- "assignedTo": {
- "firstName": "John",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Doe",
- "middleInitial": "K",
- "preferredFirstName": "John",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "1234567890"
}, - "completed": false,
- "completedAt": "2019-01-01T00:00:00.000Z",
- "completedBy": {
- "firstName": "John",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Doe",
- "middleInitial": "K",
- "preferredFirstName": "John",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "1234567890"
}, - "templateStep": {
- "action": "SIGN",
- "assignee": "TEAM_MEMBER",
- "order": 1
}
}, - {
- "assignedTo": {
- "firstName": "John",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Doe",
- "middleInitial": "K",
- "preferredFirstName": "John",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "1234567890"
}, - "completed": false,
- "completedAt": "2019-01-01T00:00:00.000Z",
- "completedBy": {
- "firstName": "John",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Doe",
- "middleInitial": "K",
- "preferredFirstName": "John",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "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
Success
object (EmployeeDocumentSchema) | |||||||||||||||||||
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "employeeCanView": true,
- "managerCanView": true,
- "name": "string"
}
{- "data": {
- "completed": true,
- "createdBy": {
- "firstName": "GoCo",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Automation",
- "middleInitial": "G",
- "preferredFirstName": "GoCo",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555-555-5555"
}, - "employee": {
- "firstName": "John",
- "id": "c1ebeab0-d030-4035-8455-ac5178df1379",
- "lastName": "Test33",
- "middleInitial": "K",
- "preferredFirstName": "Test11",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555-555-5555"
}, - "expirationDate": "",
- "id": "AHuxgU-k0qR11WUDLDSPs1YAEEF0dGFjaGVk",
- "name": "Document Name",
- "steps": [
- {
- "assignedTo": {
- "firstName": "GoCo",
- "id": "2537aeda-b772-4db3-b18c-08274dcf471c",
- "lastName": "Automation",
- "middleInitial": "G",
- "preferredFirstName": "GoCo",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "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",
- "preferredFirstName": "GoCo",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555-555-5555"
}, - "templateStep": {
- "action": "UPLOAD",
- "assignee": "DOCUMENT_SENDER",
- "order": 1
}
}
], - "template": { }
}
}
Bulk update custom fields for an employee
required | Array of objects | ||||||||||||||
Array
|
{- "fields": [
- {
- "currencyValue": {
- "currency": "AED",
- "value": 0
}, - "dateValue": "2019-08-24",
- "identifier": "string",
- "intValue": 0,
- "intValues": [
- 0
], - "numberValue": 0,
- "stringValue": "string"
}
]
}
{- "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
firstName required | string First Name |
lastName required | string Last Name |
insertionSource | string Insertion Source |
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 |
jobTitleId | string Job Title ID |
legalSex | string Legal Sex |
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 |
workEmail | string Work Email |
workPhone | string Work Phone |
Success
object (EmployeeSchema) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "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"
}
{- "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",
- "preferredFirstName": "Cristi",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555 3430234"
}, - "middleInitial": "K",
- "nonWorkStateWithholding": {
- "allowances": "2",
- "exempt": false,
- "extraWithholding": 2000,
- "filingStatus": "married"
}, - "payrollSchedule": {
- "id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
- "name": "Default"
}, - "personalBalance": 0,
- "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"
}, - "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,
- "workPhone": "555 3430234"
}
}
Retrieve a list of compensation methods for an employee
Success
Array of objects (EmployeeCompensationMethodsSchema) | |||||||||||||||||||
Array
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "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
{- "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
{- "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",
- "preferredFirstName": "Cristi",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555 3430234"
}, - "middleInitial": "K",
- "nonWorkStateWithholding": {
- "allowances": "2",
- "exempt": false,
- "extraWithholding": 2000,
- "filingStatus": "married"
}, - "payrollSchedule": {
- "id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
- "name": "Default"
}, - "personalBalance": 0,
- "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"
}, - "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,
- "workPhone": "555 3430234"
}
], - "maxPerPage": 25,
- "page": 2,
- "total": 2,
- "totalPages": 1
}
Retrieve a list of state withholdings for an employee
Success
Array of objects (EmployeeStateWithholdingsSchema) | |||||||||||||||||||||||||||
Array
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "data": [
- {
- "allowNonResidentExemption": false,
- "allowances": "1",
- "exempt": false,
- "exemptReason": "OTHER",
- "exemptionForm": {
- "title": "IT-2104-E",
}, - "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",
- "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",
}, - "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",
- "id": "ANz6sJ06gR58mikgTS5WNrEADUFyV2l0aGhvbGRpbmcAEKnjD7YqUkvNpczpj-uUqwE",
- "isWorkState": false,
- "signedAt": "2024-03-12T07:23:14-07:00",
- "state": "AR"
}
]
}
Retrieve an employee
Success
object (EmployeeSchema) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests
{- "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",
- "preferredFirstName": "Cristi",
- "preferredPronoun": "THEY_THEM_THEIRS",
- "workPhone": "555 3430234"
}, - "middleInitial": "K",
- "nonWorkStateWithholding": {
- "allowances": "2",
- "exempt": false,
- "extraWithholding": 2000,
- "filingStatus": "married"
}, - "payrollSchedule": {
- "id": "ACLa_zOrrCN2DvGcOcWx_9IAD1BheXJvbGxTY2hlZHVsZQAQpHa0cvY_QSiFUdijhrtrgA",
- "name": "Default"
}, - "personalBalance": 0,
- "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"
}, - "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,
- "workPhone": "555 3430234"
}
}
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
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 |
jobTitleId | string Job Title ID |
legalSex | string Legal Sex |
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 |
workEmail | string Work Email |
workPhone | string Work Phone |
Success
object (EmployeeSchema) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Not Authorized
Not Found
Unprocessable Content
Too Many Requests