
EmployerLink API Reference
Atomic's API is built around RESTful principles, using JSON encoded request and response bodies.
To get going quickly, we recommend using Postman - an API collaboration tool. Atomic provides a public workspace which you can fork into your own workspace. Use the button below to get started.
The workspace comes fully documented with:
- several useful flows using our APIs
- requests for all of the Atomic endpoints
- an environment containing placeholders for all the variables needed to connect to your Sandbox instance of Console
Authentication
Atomic uses a combination of API keys and access tokens to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.
API Key and Secret
You can retrieve and manage your API key and secrets on the credentials page on the Atomic Console. Include these headers in requests that are secured with your API Key and Secret:
Header | Description |
---|---|
x-api-key | API Key for your Atomic account |
x-api-secret | API Secret for your Atomic account |
Access Token
These headers are included in requests that are made by the end user, e.g. searching for their employer.
Header | Description |
---|---|
x-public-token | Public token generated during access token creation. |
Errors
Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.
Code | Title | Description |
---|---|---|
200 | OK | The request was successful. |
400 | Bad Request | The request was unacceptable. |
401 | Unauthorized | Missing or invalid credentials. |
404 | Not Found | The resource does not exist. |
422 | Validation error | A validation error occurred. |
50X | Internal Server Error | An error occurred with our API. |
API Versioning
The Atomic API accepts an x-atomic-version
header. This is a mechanism we have put in place to ensure stability as the surface of the API changes over time. A new version will be released when there are backward incompatible changes to the API. We will publish a changelog and migration guides as new versions are rolled out to highlight any relevant changes and make migrations seamless for consumers of our API.
To use the version header, append the x-atomic-version
header to all calls to the Atomic API. The value of the header will follow standardized CalVer practices. The current version is 2022-12-02
.
x-atomic-version
Date- A Date-string in the form of
YYYY-MM-DD
. Specific versions to be provided by Atomic.
Header | Description |
---|---|
x-atomic-version | Date string of the required API version |
Access Token
An AccessToken
grants access to Atomic's API resources for an end user when its value is used as the x-public-token
header.
Create Access Token
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
identifier
string- A unique identifier from your system that will be used to reference this user. This could be a primary key used in your system or another unique identifier. Creating multiple access tokens with the same identifier will tie those tokens to the same user in Atomic's system.
POST
/access-tokenProduct Specific Properties
The identifier
property is required for generating all AccessTokens
, but each Atomic product may require some additional context in order to correctly set up the flow in our backend. Please refer to the implementation pages for each Product to get specific details regarding AccessToken
creation.
Get Employees
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Optional Properties
nextCursor
string
previousCursor
string
limit
integer
include
string
employeeDeductions
, depositAccounts
, employment
, identity
, income
, statements
, timesheets
, ortaxes
. If this parameter is present, only the corresponding data objects will be returned. If this parameter is missing, only _id
, firstName
, lastName
, and employer
will be returned.GET
/employers/:_id/employeesResponse
A successful request will return a paginated list of employees in ascending order of creation.
nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
employees
[]- An array of objects representing an employee. Each object will contain
_id
,firstName
,lastName
, andemployer
fields, as well any additional fields requested by theinclude
parameter.
{
"data": {
"nextCursor": "6387dd18118deb05b68f0bde",
"previousCursor": "6387dd0f1a5c71c793b4b507",
"employees": [
{
"_id": "5eea73d5f55d6c0007d1fcdf",
"firstName": "John",
"lastName": "Doe",
"employer": "5f03900c13857400082e9497"
},
{
"_id": "5eea76350d0ada0007fb43c7",
"firstName": "Jane",
"lastName": "Doe",
"employer": "5f03900c13857400082e9497"
}
]
}
}
Get an Employee
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Optional Properties
include
string
deductions
, depositAccounts
, employeeDeductions
, employment
, identity
, income
, statements
, timesheets
, ortaxes
. If this parameter is present, only the corresponding data objects will be returned. If this parameter is missing, all fields are returned.GET
/employees/:_idResponse
A successful request will return an employee.
data
object- An object containing employment data for a given employee. This data will be a union of the following objects: depositAccounts, employment, identity, income, statements, and taxes. Timestamps for
createdAt
andupdatedAt
are also included.
{
"data": {
"_id": "5eea73d5f55d6c0007d1fcdf",
"depositAccounts": [
{
"routingNumber": "123123123",
"accountNumber": "1122330000",
"type": "checking",
"bankName": "Molecular Bank",
"distributionType": "percent",
"distributionAmount": 80
},
{
"routingNumber": "456456456",
"accountNumber": "XXXX1111",
"type": "savings",
"bankName": "Molecular Bank",
"distributionType": "percent",
"distributionAmount": 20
}
],
"employeeType": "fulltime",
"employmentStatus": "active",
"jobTitle": "Product Manager",
"startDate": "2017-04-19T12:00:00.000Z",
"weeklyHours": 40,
"classCode": 8810,
"terminationDate": "2019-09-01T12:00:00.000Z",
"firstName": "Jane",
"lastName": "Appleseed",
"dateOfBirth": "1984-04-12T12:00:00.000Z",
"email": "janeappleseed@example.com",
"phone": "5558881111",
"ssn": "111223333",
"homeAddress": {
"line1": "123 Example St.",
"line2": "Apt. 345",
"city": "Salt Lake City",
"state": "UT",
"zipcode": "84111",
"country": "USA"
},
"income": 45000,
"incomeType": "yearly",
"payCycle": "weekly",
"statements": [
{
"_id": "642c9aa7f8fc90e0dbb4ca71",
"createdAt": "2023-04-04T21:46:15.762Z",
"updatedAt": "2023-08-14T20:29:45.419Z",
"employee": "64b820a19cba026a0245feeb",
"date": "2020-06-15T12:00:00.000Z",
"payPeriodStartDate": "2020-05-27T12:00:00.000Z",
"payPeriodEndDate": "2020-06-12T12:00:00.000Z",
"grossAmount": 1000,
"ytdGrossAmount": 10000,
"netAmount": 800,
"ytdNetAmount": 8000,
"paymentMethod": "deposit",
"hours": 39,
"deductions": [
{
"category": "taxes",
"label": "Federal Income Tax",
"rawLabel": "Federal Income Tax",
"amount": 200,
"ytdAmount": 2000
},
{
"category": "taxes",
"label": "State Income Tax",
"rawLabel": "Utah State Tax",
"amount": 50,
"ytdAmount": 500
},
{
"category": "other",
"label": "Abc corp dd",
"rawLabel": "Abc corp dd",
"amount": 5,
"ytdAmount": 50
}
],
"earnings": [
{
"category": "benefit",
"rawLabel": "Social Security (Disability)",
"amount": 1000
},
{
"category": "bonus",
"rawLabel": "Quarterly Bonus",
"amount": 2000,
"ytdAmount": 6000
},
{
"category": "overtime",
"rawLabel": "Overtime Pay",
"amount": 100,
"ytdAmount": 1000,
"hours": 10,
"rate": 15
},
{
"category": "reimbursement",
"rawLabel": "Gas Card",
"amount": 25.47,
"ytdAmount": 85.74
}
],
"netAmountAdjustments": [
{
"label": "Mileage Reimbursement",
"amount": 25
}
]
},
{
"_id": "64b820a19cba026a0245feed",
"createdAt": "2023-08-07T22:01:28.305Z",
"updatedAt": "2023-08-14T20:29:45.419Z",
"employee": "64b820a19cba026a0245feeb",
"date": "2020-06-30T12:00:00.000Z",
"payPeriodStartDate": "2020-05-27T12:00:00.000Z",
"payPeriodEndDate": "2020-06-12T12:00:00.000Z",
"grossAmount": 1000,
"paymentMethod": "check",
"hours": 37,
"deductions": [
{
"category": "taxes",
"label": "Federal Income Tax",
"rawLabel": "Federal Income Tax",
"amount": 200
},
{
"category": "taxes",
"label": "State Income Tax",
"rawLabel": "Utah State Tax",
"amount": 50
},
{
"category": "other",
"label": "Abc corp dd",
"rawLabel": "Abc corp dd",
"amount": 5
}
]
}
],
"taxes": [
{
"type": "w2",
"year": "2020-01-01T00:00:00.000Z",
"totalWages": 50000
},
{
"type": "w2",
"year": "2021-01-01T00:00:00.000Z",
"totalWages": 55000
}
],
"createdAt": "2023-02-28T19:57:26.445Z",
"updatedAt": "2023-02-28T21:18:55.490Z"
}
}
Employee Deduction Requests
An Employee Deduction Request is when a deduction is submitted to Atomic in order to write the deduction to the payroll system. This endpoint gives you a way to get the status of those requests and has several ways for you to filter them down to get to the data you need.
An Employee Deduction Request can be in any of these states: `processing`, `applied`, or `failed`.
Get Employee Deduction Request
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Optional Properties
employeeId
string
state
string
processing
, applied
, or failed
.trackingId
string
taskId
string
nextCursor
string
previousCursor
string
limit
integer
GET
/employers/:_id/employee-deduction-requestsResponse
A successful request will return a paginated list of employee deduction requests in ascending order of creation.
employeeDeductionRequests
[EmployeeDeductionRequest]- An array of objects representing an Employee Deduction Request. Each object will contain
_id
,trackingId
,customer
,employee
,employer
,employerDeductionType
,state
,task
, andemployeeDeduction
fields. nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
{
"data": {
"nextCursor": "6387dd18118deb05b68f0bde",
"previousCursor": "6387dd0f1a5c71c793b4b507",
"employeeDeductionRequests": [
{
"_id": "64af13c7e919bd3efbed494e",
"trackingId": "a1f23a50-e36e-409b-8c05-a55ed4cd8d63",
"customer": "5e978dcf3abbf90008a00b7a",
"employee": "642df289af36e2ef5e1679dc",
"employer": "64949a939e688f909acd70e6",
"employerDeductionType": "6439618cfc32f24ab9933047",
"state": "applied",
"task": "65022b04c88cf9b8aaa0147e",
"employeeDeduction": {
"_id": "6508ca7ebc39bd78ca1fb87d",
"label": "retirement",
"calculation": "fixed",
"category": "401k",
"categoryType": "post-tax",
"amount": 4,
"startDate": "2023-09-13T17:57:56.230Z"
}
},
{
"_id": "64af19aa4bff9f438210a6e1",
"trackingId": "3a4c0f51-0330-49f7-94d6-fc1499b5d1a7",
"customer": "5e978dcf3abbf90008a00b7a",
"employee": "642df289af36e2ef5e1679d9",
"employer": "64949a939e688f909acd70e6",
"employerDeductionType": "6439618cfc32f24ab9933047",
"state": "failed",
"task": "65022b0ce9d34a15e4a31c9e",
"employeeDeduction": {
"_id": "6508ca8b882f46254b6934b7",
"label": "retirement",
"calculation": "percent",
"category": "other",
"categoryType": "pre-tax",
"amount": 20,
"startDate": "2023-09-13T17:57:56.230Z"
}
}
]
}
}
Get Employers
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Optional Properties
userIdentifier
string
identifier
used to launch Transact when the HR admin connected their payroll provider.nextCursor
string
previousCursor
string
limit
integer
GET
/employersResponse
A successful request will return a paginated list of employers in ascending order of creation.
nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
employers
[Employer]- An array of objects representing an employer. Each object will contain
_id
andname
.
{
"data": {
"nextCursor": "6387e1eba1dabf6708a16e39",
"previousCursor": "6387e1f194c2fdd82d90d404",
"employers": [
{
"_id": "5eea73d5f55d6c0007d1fcdf",
"name": "Example Employer A"
},
{
"_id": "5eea76350d0ada0007fb43c7",
"name": "Example Employer B"
}
]
}
}
Get an Employer
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/employers/:_idResponse
A successful request will return an employer.
_id
string- The
_id
of the employer. name
string- The employer's name.
ein
string- The employer's Employer Identification Number.
connector
object- The payroll provider used by the referenced employer. Atomic refers to these as connector's in our system.
locations
[object]- A list of locations for the employer
Child Properties
Optional Properties
line1
stringFirst line of the address of the employer.line2
stringSecond line of the address of the employer.city
stringCity where the employer is located.state
stringState where the employer is located.postalCode
stringPostal code for the employer.country
stringCountry where the employer is located. createdAt
date- The date the employer data was initially retrieved.
updatedAt
date- The date the employer data was most recently retrieved.
{
"data": {
"_id": "5eea76350d0ada0007fb43c7",
"name": "Example Employer A",
"ein": "12345678",
"connector": {
"_id": "dd5376350d0ada0007f2f5sh",
"name": "Payroll System A"
},
"locations": [
{
"line1": "12345 Enterprise Rd",
"line2": "Suite 105",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "84111",
"country": "USA"
}
],
"createdAt": "2023-02-28T19:57:26.445Z",
"updatedAt": "2023-02-28T21:18:55.490Z"
}
}
Employer Documents
Frequently, additional documentation is required for various use cases. This endpoint will be used to retrieve said documents from the Atomic system as we are able to pull them from the HR systems.
Get Employer Documents
This endpoint returns a paginated list of Employer Documents reference data. Each object contains an _id
which can be used to get the document from the Atomic system.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/employers/:_id/employer-documentsResponse
A successful request will return a paginated list of employer documents in ascending order of creation.
nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
employerDocuments
[EmployerDocument]- An array of objects representing an employer document. Each object will contain
_id
,employer
,type
,date
, andmetadata
.
{
"data": {
"nextCursor": "6387e1eba1dabf6708a16e39",
"previousCursor": "6387e1f194c2fdd82d90d404",
"employerDocuments": [
{
"_id": "63fe5ca6d93310ec79aee4f1",
"employer": "63f7f2e7baf8f344eacd59fd",
"type": "941",
"date": "2021-01-01T00:00:00.000Z",
"metadata": {
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-03-01T00:00:00.000Z"
}
},
{
"_id": "63fe5ca6d93310ec79aee4f2",
"employer": "63f7f2e7baf8f344eacd59fd",
"type": "941",
"date": "2021-03-01T00:00:00.000Z",
"metadata": {
"startDate": "2021-03-01T00:00:00.000Z",
"endDate": "2021-06-01T00:00:00.000Z"
}
}
]
}
}
Get an Employer Document
Use this endpoint to retrieve Employer Documents from the Atomic system using the _id
received from calls to /employer-documents
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/employer-documents/:_idResponse
A successful request will return data about an employer document including url
, which is a generated link to download the document from the Atomic system.
_id
string- The
_id
of the employer document. type
string- The type of the employer document. For example
"941"
would be a Form 941. date
date- A timestamp of when the document was filed, stored in UTC and ISO 8601 format.
metadata
object- Additional metadata about the document.
url
string- The URL to download the form. Each request to this endpoint will generate a new URL, which will expire after 1 hour.
createdAt
date- The date the document was initially retrieved.
updatedAt
date- The date the document was most recently retrieved.
{
"data": {
"_id": "63fe5ca6d93310ec79aee4f1",
"employer": "63f7f2e7baf8f344eacd59fd",
"type": "941",
"date": "2021-01-01T00:00:00.000Z",
"metadata": {
"startDate": "2021-01-01T00:00:00.000Z",
"endDate": "2021-03-01T00:00:00.000Z"
},
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
"createdAt": "2023-02-28T19:57:26.445Z",
"updatedAt": "2023-02-28T21:18:55.490Z"
}
}
Employer Deduction Types
Many payroll systems have the ability to create templates for deductions so they can be used multiple times. These endpoints will retrieve templates that are available in the payroll system. Using the _id
, you will be able to get more information about a specific deduction type or apply the deduction type to write a deduction for an employee or list of employees.
Get Employer Deduction Types
Get all Deduction Types for an Employer.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/employers/:_id/employer-deduction-typesResponse
A successful request will return a paginated list of employer deduction types in ascending order of creation.
nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
employerDeductionTypes
[EmployerDeductionType]- An array of objects representing an employer deduction type. Each object will contain
_id
,employer
,amount
,calculation
,label
,category
,categoryType
,startDate
, andendDate
.
{
"data": {
"nextCursor": "6387e1eba1dabf6708a16e39",
"previousCursor": "6387e1f194c2fdd82d90d404",
"employerDeductionTypes": [
{
"_id": "642703b666b8c0abb8c65cff",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"amount": 10,
"calculation": "percent",
"category": "401k",
"categoryType": "pre-tax",
"endDate": "2023-02-02T00:00:00.000Z",
"label": "401k",
"startDate": "2022-02-02T00:00:00.000Z"
},
{
"_id": "642703b666b8c0abb8c65d01",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"amount": 100,
"calculation": "fixed",
"category": "Other",
"label": "Life Insurance"
},
{
"_id": "642703b666b8c0abb8c65d03",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"label": "Garnishment",
"category": "Garnishment"
}
]
}
}
Get an Employer Deduction Type
Get a specific Deduction Type for an Employer.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/employer-deduction-types/:_idResponse
A successful request will return an employer deduction type.
_id
string- The
_id
of the employer deduction type. amount
number- The amount of the deduction type in dollars if
calculation
isfixed
or percentage ifcalculation
ispercent
. calculation
string- Either
fixed
orpercent
. category
string- One of
401k
,401k-catchup
,403b
,408b
,408k
,premium-only-plan
,garnishment
, orother
categoryType
string- Either
pre-tax
orpost-tax
. createdAt
date- The date the employer deduction type was initially retrieved.
employer
string- The
_id
of the employer. endDate
date- The date at which the applied deduction will expire in the payroll system.
label
string- The label of the employer deduction type.
startDate
date- The date at which the applied deduction type began in the payroll system
updatedAt
date- The date the employer deduction data was most recently retrieved from the payroll system.
{
"data": {
"_id": "642703b666b8c0abb8c65cff",
"amount": 10,
"calculation": "percent",
"category": "401k",
"categoryType": "pre-tax",
"createdAt": "2023-03-31T16:00:54.321Z",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"endDate": "2023-02-02T00:00:00.000Z",
"label": "401k",
"startDate": "2022-02-02T00:00:00.000Z",
"updatedAt": "2023-04-04T21:46:16.694Z"
}
}
Deductions
Deductions can be added to any number of employees either by referencing an existing employer deduction type on file in the payroll system or by specifying a new deduction type to be created and applied to the referenced employees.
These methods can be used in combination to apply existing and newly created deductions to employees, if so desired. The endpoint is the same, but the request body will differ depending on the use case.
Apply Existing Deductions
Using an _id
from the Employer Deduction Types endpoint, you can reference an existing deduction type to apply it to a list of employees for a given employer.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
employeeDeductions
[Deduction Type]- The list of deductions to apply to the referenced employees. This example references deduction types on file in the payroll system.
POST
/employers/:_id/employee-deductionsResponse
A successful request will return the _id
's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.
taskWorkflow._id
string- The
_id
of the Task Workflow. taskWorkflow.tasks[0]._id
string- the
_id
of the Task.
{
"data": {
"taskWorkflow": {
"_id": "6387e1eba1dabf6708a16e39",
"tasks": [
{
"_id": "5eea76350d0ada0007fb43c7"
}
]
}
}
}
Create a New Deduction
Create new deductions on demand and apply them to a list employees.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
employeeDeductions
[Deduction Type]- The list of deductions to apply to the referenced employees. This example creates a new deduction type on demand and then applies it to the list of employees.
Child Properties
Required Properties
category
string- One of
401k
,401k-catchup
,403b
,408b
,408k
,premium-only-plan
,garnishment
, orother
categoryType
string- Either
pre-tax
orpost-tax
. label
string- The label of the employer deduction type.
employees
[Employee]- The employees to apply the deductions to.
Child Properties
Optional Properties
amount
numberThe amount of the deduction type in dollars ifcalculation
isfixed
or percentage ifcalculation
ispercent
.calculation
stringEitherfixed
orpercent
.endDate
dateThe date at which the applied deduction will expire in the payroll system.startDate
dateThe date at which the applied deduction type began in the payroll system
POST
/employers/:_id/employee-deductionsResponse
A successful request will return the _id
's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.
taskWorkflow._id
string- The
_id
of the Task Workflow. taskWorkflow.tasks[0]._id
string- the
_id
of the Task.
{
"data": {
"taskWorkflow": {
"_id": "6387e1eba1dabf6708a16e39",
"tasks": [
{
"_id": "5eea76350d0ada0007fb43c7"
}
]
}
}
}
Update Existing Deductions
Update deductions that have been perviously applied.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Required Properties
employeeDeductions
[Deduction Type]- The list of employee deductions to update.
Child Properties
Optional Properties
amount
numberThe amount of the deduction type in dollars ifcalculation
isfixed
or percentage ifcalculation
ispercent
.calculation
stringEitherfixed
orpercent
.startDate
dateThe date at which the applied deduction type began in the payroll systemendDate
dateThe date at which the applied deduction will expire in the payroll system.trackingId
stringA unique string that we store alongside your request, used to query the status of the deduction.
PUT
/employers/:_id/employee-deductionsResponse
A successful request will return the _id
's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.
taskWorkflow._id
string- The
_id
of the Task Workflow. taskWorkflow.tasks[0]._id
string- the
_id
of the Task.
{
"data": {
"taskWorkflow": {
"_id": "6387e1eba1dabf6708a16e39",
"tasks": [
{
"_id": "5eea76350d0ada0007fb43c7"
}
]
}
}
}
Delete Deductions
Delete deductions which have been applied to employees by sending a list of deduction _id
's to this PUT endpoint.
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
PUT
/employers/:_id/delete-employee-deductionsResponse
A successful request will return the _id
's of the associated Task and Task Workflow, which is a grouping of any Tasks needed to complete the request to the payroll system.
taskWorkflow._id
string- The
_id
of the Task Workflow. taskWorkflow.tasks[0]._id
string- the
_id
of the Task.
{
"data": {
"taskWorkflow": {
"_id": "6387e1eba1dabf6708a16e39",
"tasks": [
{
"_id": "5eea76350d0ada0007fb43c7"
}
]
}
}
}
Get Payroll Runs
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
Optional Properties
nextCursor
string
previousCursor
string
limit
integer
checkDateAfter
ISO8601 Timestamp
checkDateBefore
ISO8601 Timestamp
GET
/employers/:_id/payroll-runsResponse
A successful request will return a paginated list of payroll runs in ascending order of creation.
nextCursor
string- The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursor
string- The cursor to use to get the previous page of data. If null, there is no previous page of data.
payrollRuns
[PayrollRun]- An array of objects representing a payroll run. Each object will contain
_id
,employer
,checkDate
,payPeriodEndDate
,payPeriodStartDate
,runInitiatedDate
,runType
, andrunState
.
{
"data": {
"nextCursor": "6387dd18118deb05b68f0bde",
"previousCursor": "6387dd0f1a5c71c793b4b507",
"payrollRuns": [
{
"_id": "6407babd7d627e100e7a54d1",
"employer": "6407bab97d627e100e7a5246",
"checkDate": "2023-01-31T00:00:00.000Z",
"payPeriodEndDate": "2023-01-16T00:00:00.000Z",
"payPeriodStartDate": "2023-01-02T00:00:00.000Z",
"runInitiatedDate": "2023-01-31T01:00:00.000Z",
"runType": "regular",
"runState": "approved"
},
{
"_id": "6407babd7d627e100e7a54d2",
"employer": "6407bab97d627e100e7a5246",
"checkDate": "2022-11-30T00:00:00.000Z",
"payPeriodEndDate": "2022-11-16T00:00:00.000Z",
"payPeriodStartDate": "2022-11-02T00:00:00.000Z",
"runInitiatedDate": "2022-11-30T01:00:00.000Z",
"runType": "regular",
"runState": "processed"
}
]
}
}
Get a Payroll Run
Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.
GET
/payroll-runs/:_idResponse
A successful request will return a payroll run, which contains a list of associated employee statements.
_id
string- The id of the employer document.
employer
string- The id of the employer.
checkDate
date- The date the payroll run was deposited, stored in UTC and ISO 8601 format.
payPeriodEndDate
date- The end date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
payPeriodStartDate
date- The start date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
runInitiatedDate
date- The date the payroll run was initiated, stored in UTl and ISO 8601 format.
runState
string- The state of the payroll run. One of
approved
,closed
,draft
,failed
,processed
, orscheduled
runType
string- The type of payroll run. One of
accumulated-sick-leave
,back-pay
,bonus
,commission
,correction
,off-cycle
,one-time-payment
,other
,overtime
,regular
,sick-leave
,termination
, ortravel-reimbursement
url
string- The URL to download the raw payroll run document. Each request to this endpoint will generate a new URL, which will expire after 1 hour.
createdAt
date- The date the payroll run was initially retrieved.
updatedAt
date- The date the payroll run was most recently retrieved.
statements
[]- List of statements that were a part of the payroll run
{
"data": {
"_id": "643980405d1c26218ba1eb75",
"employer": "642c9aa6f8fc90e0dbb4c92f",
"checkDate": "2023-04-14T16:45:16.243Z",
"runInitiatedDate": "2022-11-30T01:00:00.000Z",
"payPeriodStartDate": "2022-11-02T00:00:00.000Z",
"payPeriodEndDate": "2022-11-16T00:00:00.000Z",
"runState": "processed",
"runType": "other",
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
"createdAt": "2023-04-14T16:33:04.736Z",
"updatedAt": "2023-04-14T16:45:37.331Z",
"statements": [
{
"_id": "6ccb35d2f66d4c0512f8magw",
"employee": "5eea73d5f55d6c0007d1fcdf",
"date": "2023-04-14T16:45:16.243Z",
"payPeriodStartDate": "2022-11-02T00:00:00.000Z",
"payPeriodEndDate": "2022-11-16T00:00:00.000Z",
"grossAmount": 1000,
"netAmount": 745,
"deductions": [
{
"category": "taxes",
"label": "Federal Income Tax",
"rawLabel": "Federal Income Tax",
"amount": 200,
"ytdAmount": 2000
},
{
"category": "taxes",
"label": "State Income Tax",
"rawLabel": "Utah State Tax",
"amount": 50,
"ytdAmount": 500
},
{
"category": "other",
"label": "Abc corp dd",
"rawLabel": "Abc corp dd",
"amount": 5,
"ytdAmount": 50
}
],
"paystub": {
"_id": "60abeff50836730008616fad",
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
}
]
}
}