API

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:

HeaderDescription
x-api-keyAPI Key for your Atomic account
x-api-secretAPI 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.

HeaderDescription
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.

CodeTitleDescription
200OKThe request was successful.
400Bad RequestThe request was unacceptable.
401UnauthorizedMissing or invalid credentials.
404Not FoundThe resource does not exist.
422Validation errorA validation error occurred.
50XInternal Server ErrorAn 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-versionDate
A Date-string in the form of YYYY-MM-DD. Specific versions to be provided by Atomic.
HeaderDescription
x-atomic-versionDate 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

identifierstring
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.

Optional Properties

tokenLifetimeinteger
The number of seconds until the token expires.

Default value: 86,400 (24 hours)

Products may have additional required properties. Refer to the implementation pages for additional details.
POST/access-token
https://sandbox-api.atomicfi.com/access-token

Product 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.

DepositVerify

Response

Successfully creating an Access Token will return a payload with a data object containing a publicToken. The publicToken may be used to initialize the Transact SDK and is valid for tokenLifetime seconds.

Example response 
{
  "data": {
    "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48"
  }
}

Employees

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

nextCursorstring
The cursor to use to retrieve the next page of data.
previousCursorstring
The cursor to use to retrieve the previous page of data
limitinteger
The max number of employees to return.
employerIdstring
The employer _id used to filter the employees.
GET/employees
https://sandbox-api.atomicfi.com/employees

Response

A successful request will return a paginated list of employees in ascending order of creation.

nextCursorstring
The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring
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.
Example response 
{
  "data": {
    "nextCursor": "6387dd18118deb05b68f0bde",
    "previousCursor": "6387dd0f1a5c71c793b4b507",
    "employees": [
      {
        "_id": "5eea73d5f55d6c0007d1fcdf",
        "firstName": "John",
        "lastName": "Doe",
        "employer": "5f0361ec9ecb2400089f1451"
      },
      {
        "_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.

Required Properties

_idstring
The _id of the employee.

Optional Properties

includestring
A comma separated list of employment data objects to include. Each list item will be one of the following: 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, all fields are returned.
GET/employees/:_id
https://sandbox-api.atomicfi.com/employees/:_id

Response

A successful request will return an employee.

dataobject
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 and updatedAt are also included.
Example response 
{
  "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": [
      {
        "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
          }
        ]
      },
      {
        "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"
  }
}

Employers

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

userIdentifierstring
Filter the employers sent back in the response by optionally passing the identifier used to launch Transact when the HR admin connected their payroll provider.
nextCursorstring
The cursor to use to retrieve the next page of data.
previousCursorstring
The cursor to use to retrieve the previous page of data
limitinteger
The max number of employees to return.
GET/employers
https://sandbox-api.atomicfi.com/employers

Response

A successful request will return a paginated list of employers in ascending order of creation.

nextCursorstring
The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring
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 and name.
Example response 
{
  "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.

Required Properties

_idstring
The _id of the employer.
GET/employers/:_id
https://sandbox-api.atomicfi.com/employers/:_id

Response

A successful request will return an employer.

_idstring
The _id of the employer.
namestring
The employer's name.
einstring
The employer's Employer Identification Number.
sourceIdstring
The id of the employer in the external system.
locations[object]
A list of locations for the employer
Child Properties
Optional Properties
line1string
First line of the address of the employer.
line2string
Second line of the address of the employer.
citystring
City where the employer is located.
statestring
State where the employer is located.
postalCodestring
Postal code for the employer.
countrystring
Country where the employer is located.
createdAtdate
The date the employer data was initially retrieved.
updatedAtdate
The date the employer data was most recently retrieved.
Example response 
{
  "data": {
    "_id": "5eea76350d0ada0007fb43c7",
    "name": "Example Employer A",
    "ein": "12345678",
    "sourceId": "035add56-0038-4dc9-98b2-23cb39877d47",
    "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.

Optional Properties

nextCursorstring
The cursor to use to retrieve the next page of data.
previousCursorstring
The cursor to use to retrieve the previous page of data
limitinteger
The max number of employees to return.
employerIdstring
The identifier used to filter the employer documents by the corresponding employer.
GET/employer-documents
https://sandbox-api.atomicfi.com/employer-documents

Response

A successful request will return a paginated list of employer documents in ascending order of creation.

nextCursorstring
The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring
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, and metadata.
Example response 
{
  "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.

Required Properties

_idstring
The _id of the employer document.
GET/employer-documents/:_id
https://sandbox-api.atomicfi.com/employer-documents/:_id

Response

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.

_idstring
The _id of the employer document.
typestring
The type of the employer document. For example "941" would be a Form 941.
sourceIdstring
The id of the employer document in the external system.
datedate
A timestamp of when the document was filed, stored in UTC and ISO 8601 format.
metadataobject
Additional metadata about the document.
urlstring
The URL to download the form. Each request to this endpoint will generate a new URL, which will expire after 1 hour.
createdAtdate
The date the document was initially retrieved.
updatedAtdate
The date the document was most recently retrieved.
Example response 
{
  "data": {
    "_id": "63fe5ca6d93310ec79aee4f1",
    "employer": "63f7f2e7baf8f344eacd59fd",
    "type": "941",
    "sourceId": "21b0cdd6-b7c9-11ed-afa1-0242ac120002",
    "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.

Optional Properties

nextCursorstring
The cursor to use to retrieve the next page of data.
previousCursorstring
The cursor to use to retrieve the previous page of data
limitinteger
The max number of employees to return.
employerIdstring
The identifier used to filter the employer deduction types by the corresponding employer. This value can be retrieved from the /employers endpoint.
GET/employer-deduction-types
https://sandbox-api.atomicfi.com/employer-deduction-types

Response

A successful request will return a paginated list of employer deduction types in ascending order of creation.

nextCursorstring
The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring
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, and endDate.
Example response 
{
  "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.

Required Properties

_idstring
The _id of the employer deduction type.
GET/employer-deduction-types/:_id
https://sandbox-api.atomicfi.com/employer-deduction-types/:_id

Response

A successful request will return an employer deduction type.

_idstring
The _id of the employer deduction type.
amountnumber
The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.
calculationstring
Either fixed or percent.
categorystring
One of 401k, 401k-catchup, 403b, 408b, 408k, premium-only-plan, garnishment, or other
categoryTypestring
Either pre-tax or post-tax.
createdAtdate
The date the employer deduction type was initially retrieved.
employerstring
The _id of the employer.
endDatedate
The date at which the applied deduction will expire in the payroll system.
labelstring
The label of the employer deduction type.
sourceIdstring
The id of the employer deduction type in the payroll system.
startDatedate
The date at which the applied deduction type began in the payroll system
updatedAtdate
The date the employer deduction data was most recently retrieved from the payroll system.
Example response 
{
  "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",
    "sourceId": "001",
    "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

deductions[Deduction Type]
The list of deductions to apply to the referenced employees. This example references deduction types on file in the payroll system.
Child Properties
Required Properties
_idstring
The _id of the employer deduction type to be applied.
employees[Employee]
Child Properties
Required Properties
_idstring
The _id of the employee.
Optional Properties
amountnumber
The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.
calculationstring
Either fixed or percent.
POST/employer/:_id/deductions
https://sandbox-api.atomicfi.com/employer/:_id/deductions

Response

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._idstring
The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring
the _id of the Task.
Example response 
{
  "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

deductions[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
categorystring
One of 401k, 401k-catchup, 403b, 408b, 408k, premium-only-plan, garnishment, or other
categoryTypestring
Either pre-tax or post-tax.
labelstring
The label of the employer deduction type.
employees[Employee]
The employees to apply the deductions to.
Child Properties
Required Properties
_idstring
The _id of the employee.
Optional Properties
amountnumber
The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.
calculationstring
Either fixed or percent.
Optional Properties
amountnumber
The amount of the deduction type in dollars if calculation is fixed or percentage if calculation is percent.
calculationstring
Either fixed or percent.
endDatedate
The date at which the applied deduction will expire in the payroll system.
startDatedate
The date at which the applied deduction type began in the payroll system
POST/employer/:_id/deductions
https://sandbox-api.atomicfi.com/employer/:_id/deductions

Response

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._idstring
The _id of the Task Workflow.
taskWorkflow.tasks[0]._idstring
the _id of the Task.
Example response 
{
  "data": {
    "taskWorkflow": {
      "_id": "6387e1eba1dabf6708a16e39",
      "tasks": [
        {
          "_id": "5eea76350d0ada0007fb43c7"
        }
      ]
    }
  }
}

Payroll Runs

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

nextCursorstring
The cursor to use to retrieve the next page of data.
previousCursorstring
The cursor to use to retrieve the previous page of data
limitinteger
The max number of employees to return.
employerIdstring
The employer _id used to filter the payroll runs.
GET/payroll-runs
https://sandbox-api.atomicfi.com/payroll-runs

Response

A successful request will return a paginated list of payroll runs in ascending order of creation.

nextCursorstring
The cursor to use to get the next page of data. If null, the end of the data has been reached.
previousCursorstring
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, and runState.
Example response 
{
  "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.

Required Properties

_idstring
The id of the payroll run.
GET/payroll-runs/:_id
https://sandbox-api.atomicfi.com/payroll-runs/:_id

Response

A successful request will return a payroll run.

_idstring
The id of the employer document.
employerstring
The id of the employer.
checkDatedate
The date the payroll run was deposited, stored in UTC and ISO 8601 format.
payPeriodEndDatedate
The end date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
payPeriodStartDatedate
The start date for the pay period of the payroll run, stored in UTC and ISO 8601 format.
runInitiatedDatedate
The date the payroll run was initiated, stored in UTl and ISO 8601 format.
runStatestring
The state of the payroll run. One of approved, closed, draft, failed, processed, or scheduled
runTypestring
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, or travel-reimbursement
sourceIdstring
The id of the payroll run in the external system.
urlstring
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.
createdAtdate
The date the payroll run was initially retrieved.
updatedAtdate
The date the payroll run was most recently retrieved.
Example response 
{
  "data": {
    "_id": "643980405d1c26218ba1eb75",
    "employer": "642c9aa6f8fc90e0dbb4c92f",
    "checkDate": "2023-04-14T16:45:16.243Z",
    "payPeriodEndDate": "2022-11-16T00:00:00.000Z",
    "payPeriodStartDate": "2022-11-02T00:00:00.000Z",
    "runInitiatedDate": "2022-11-30T01:00:00.000Z",
    "runState": "approved",
    "runType": "other",
    "sourceId": "21b0cdd6-b7c9-11ed-afa1-0242ac120002",
    "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
    "createdAt": "2023-04-14T16:33:04.736Z",
    "updatedAt": "2023-04-14T16:45:37.331Z"
  }
}