
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 the API collaboration tool Postman. You can use the button below to import our collection of endpoints. Be sure to set your apiUrl
, apiKey
, and apiSecret
environment variables.
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.
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.
Company Search
Searches for a Company using a text query
. Searches can also be narrowed by passing in additional properties detailed below. The primary use case of this endpoint is for an autocomplete search component.
Authentication can be handled via either the API Key and Secret method or the Access Token method.
Optional Properties
product
string
deposit
, verify
, paylink
, earn
, and tax
.products
[string]
deposit
, verify
, paylink
, earn
, and tax
.tags
[string]
gig-economy
, payroll-provider
, and unemployment
.excludedTags
[string]
gig-economy
, payroll-provider
, and unemployment
.POST
/company/searchResponse
Successfully querying the Company search endpoint will return a payload with a data
array of Company objects. When a company is under-maintenance
, users are unable to initiate an authentication until it has been restored.
_id
string- Unique identifier for the company.
name
string- Company name.
status
string- Possible values include
operational
orunder-maintenance
. connector.availableProducts
[string]- A list of compatible products.
branding.logo.url
string- Logo for the company, typically an SVG if available.
branding.color
string- Branding color for the company.
tags
[string]- Tags with which a company is associated. Possible values include
gig-economy
,payroll-provider
,unemployment
, andmanual-deposits
.
{
"data": [
{
"_id": "5d38f1e8512bbf71fb776015",
"name": "DoorDash",
"status": "operational",
"connector": {
"_id": "5d38f182512bbf0c06776013",
"availableProducts": [
"deposit"
],
"capabilities": {
"distributionTypes": [
"total"
]
}
},
"branding": {
"logo": {
"url": "https://atomicfi-public-production.s3.amazonaws.com/a8d7e778-b718-45e0-b639-2305e33e7f95_ADP.svg"
},
"color": "#E20000"
},
"tags": [
"gig-economy"
]
}
]
}
Get Employees
Authentication is handled via the API Key and Secret method.
GET
/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.
{
"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.
Optional Properties
include
string
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/:_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: income, statements, depositAccounts, employment, taxes, identity, and timesheets.
{
"data": {
"_id": "5eea73d5f55d6c0007d1fcdf",
"firstName": "Jane",
"lastName": "Appleseed",
"dateOfBirth": "1984-04-12T12:00:00.000Z",
"email": "janeappleseed@example.com",
"phone": "5558881111",
"ssn": "111223333",
"address": "123 Example St.",
"city": "Salt Lake City",
"state": "UT",
"postalCode": "84111",
"employeeType": "fulltime",
"employmentStatus": "active",
"jobTitle": "Product Manager",
"startDate": "2017-04-19T12:00:00.000Z",
"minimumMonthsOfEmployment": 58,
"weeklyHours": 40,
"employer": "638917c56473d301c45c2211",
"classCode": "8810",
"income": 45000,
"incomeType": "yearly",
"payCycle": "weekly",
"nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
"currentPayPeriodStart": "2020-06-13T12:00:00.000Z",
"currentPayPeriodEnd": "2020-06-27T12:00:00.000Z",
"unpaidHoursInPayPeriod": 24,
"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,
"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
}
],
"paystub": {
"_id": "60abeff50836730008616fad",
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
},
{
"date": "2020-06-30T12:00:00.000Z",
"payPeriodStartDate": "2020-05-27T12:00:00.000Z",
"payPeriodEndDate": "2020-06-12T12:00:00.000Z",
"grossAmount": 1000,
"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
}
],
"paystub": {
"_id": "60abeff50836730008616fae",
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
}
],
"taxes": [
{
"type": "w2",
"year": "2020-01-01T00:00:00.000Z",
"totalWages": 50000,
"form": {
"_id": "60abeff60836730008616faf",
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
},
"parsedData": {
"taxYear": 2022,
"employeeTin": "XXX-XX-1234",
"employerTin": "12-3456789",
"employerNameAddress": {
"name1": "Tax Form Issuer, Inc",
"line1": "12021 Sunset Valley Dr",
"city": "Preston",
"state": "VA",
"postalCode": "20191"
},
"controlNumber": "012547 WY/OA7",
"employeeName": {
"first": "Kris",
"last": "Public"
},
"employeeAddress": {
"line1": "1 Main St",
"city": "Melrose",
"state": "NY",
"postalCode": "12121"
},
"wages": 44416.74,
"federalTaxWithheld": 6907.16,
"socialSecurityWages": 47162.92,
"socialSecurityTaxWithheld": 2924.1,
"medicareWages": 47162.92,
"medicareTaxWithheld": 683.86,
"socialSecurityTips": 134.25,
"allocatedTips": 149.75,
"dependentCareBenefit": 543.25,
"nonQualifiedPlan": 354.23,
"codes": [
{
"code": "C",
"amount": 301.5
},
{
"code": "D",
"amount": 2746.18
},
{
"code": "DD",
"amount": 4781.88
}
],
"other": [
{
"description": "Housing",
"amount": 6500
},
{
"description": "Union Dues",
"amount": 1500
}
],
"stateTaxWithholding": [
{
"stateTaxWithheld": 1726.78,
"state": "OH",
"stateTaxId": "OH 036-133505158F-01",
"stateIncome": 44416.74
}
],
"localTaxWithholding": [
{
"localTaxWithheld": 427.62,
"localityName": "Kirtland",
"state": "OH",
"localIncome": 44416.74
}
]
}
}
],
"timesheets": [
{
"duration": 420,
"date": "2021-10-13T12:00:00.000Z",
"type": "unpaid",
"clockedIn": "2021-10-13T13:00:00.000Z",
"clockedOut": "2021-10-13T20:00:00.000Z"
},
{
"duration": 480,
"date": "2021-10-12T12:00:00.000Z",
"type": "paid",
"clockedIn": "2021-10-12T13:00:00.000Z",
"clockedOut": "2021-10-12T21:00:00.000Z"
},
{
"duration": 340,
"date": "2021-10-11T12:00:00.000Z",
"type": "paid",
"clockedIn": "2021-10-11T13:00:00.000Z",
"clockedOut": "2021-10-11T18:40:00.000Z"
}
],
"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
}
]
}
}
Get Employers
Authentication is handled via the API Key and Secret method.
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
[]- 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.
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.
sourceId
string- The id of the employer in the external 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.
{
"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"
}
]
}
}
Linked Account
A LinkedAccount
is a persistent connection that has been authenticated by an end-user. Once established, it can be used to perform read and write operations.
NOTE: Linked Accounts must be enabled on your account in order for them to be used.
List Linked Accounts
If enabled on your account, can be used to list accounts linked to a particular user.
Authentication is handled via the API Key and Secret method.
Required Properties
identifier
string- The user's identifier, as sent to Atomic during AccessToken creation. Passed with the URL as a path parameter (e.g.
/linked-account/list/:identifier
), replacing:identifier
with your user'sidentifier
.
GET
/linked-account/list/:identifierResponse
The response contains an array of Linked Account objects for the end user.
_id
string- Unique identifier for the linked account.
valid
boolean- Whether or not the account credentials were valid after the last attempted use.
transactRequired
boolean- Whether or not using the account requires the user to be present within Transact.
lastSuccess
string- The datetime of the last successful usage of the account in ISO 8601 format.
lastFailure
string- The datetime of the last failed usage of the account in ISO 8601 format.
company
object- The Company to which the account is linked.
connector
object- The Connector to which the account is linked.
{
"data": [
{
"_id": "5f7212103a40e91f95ba376d",
"valid": true,
"connector": {
"_id": "5d77f95207085632a58945c3",
"name": "ADP",
"branding": {}
},
"company": {
"_id": "5d77f9e1070856f3828945c6",
"name": "DoTerra",
"branding": {
"logo": {
"_id": "5eb62781b4b83f0008f638cc",
"url": "https://cdn.atomicfi.com/logo.svg"
}
}
},
"lastSuccess": "2020-09-28T16:40:48.009Z",
"transactRequired": false
}
]
}
Use a Linked Account
To generate a Task Workflow using a Linked Account, a Task Workflow request is created that contains an array of the tasks
you wish to execute and the _id of the LinkedAccount
. A Task Workflow is then created if the request is successful.
Authentication is handled via the API Key and Secret method.
Required Properties
tasks
[TaskConfiguration]- Defines configuration for the tasks you wish to execute as part of the task workflow.
Child Properties
Required Properties
product
stringDeprecated- One of
deposit
,verify
,paylink
,earn
, ortax
. This is deprecated in favor ofoperation
.product
will be available for the foreseeable future and we will give ample warning when it is planned to be sunset. operation
string- Specifies the operation with which to initialize Transact. One of
deposit
,verify
,paylink
,earn
, ortax
.
Optional Properties
onComplete
stringThe action to take on completion of the task. Can be either "continue" or "finish." To execute the next task, use "continue." To finish the task workflow and not execute any of the subsequent tasks, use "finish."Default value: "continue"
onFail
stringThe action to take on failure of the task. Can be either "continue" or "finish." To execute the next task, use "continue." To finish the task workflow and not execute any of the subsequent tasks, use "finish."Default value: "continue"
distribution
objectOptionally pass in enforced deposit settings.Child Properties
Required Properties
type
string- Can be
total
to indicate the remaining balance of their paycheck,fixed
to indicate a specific dollar amount, orpercent
to indicate a percentage of their paycheck.
Optional Properties
amount
numberWhen
distribution.type
isfixed
, it indicates a dollar amount to be used for the distribution. Whendistribution.type
ispercent
, it indicates a percentage of a paycheck. This is not required ifdistribution.type
istotal
.This value cannot be updated by the user unless
canUpdate
is set totrue
. linkedAccount
string- The
_id
of a LinkedAccount object.
POST
/task-workflow/from-linked-accountResponse
Successfully creating a Task Workflow will return a payload with a data
object containing metadata about the created taskWorkflow
, its first task
, and the associated company
. The Atomic Console can be used to track task progress.
Subsequent Tasks after the task
referenced in the response will be processed as needed depending on the results of the first Task as well as the configuration provided; their progress may be tracked via webhooks. If you plan on implementing webhooks, we recommend saving the _id
values of the task
and the taskWorkflow
for reference.
task
object- Metadata for the first task in the task workflow.
taskWorkflow
object- Metadata for the created task workflow.
company
object- Metadata for the user's company.
Child Properties
{
"data": {
"task": {
"_id": "5d3b23b155f500465c895f60"
},
"taskWorkflow": {
"_id": "5d3b23b155f500465c895f5f"
},
"company": {
"_id": "5d77f9e1070856f3828945c6",
"name": "Mocky",
"branding": {
"logo": {
"url": "https://cdn-public.atomicfi.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
},
"color": "#090721"
}
}
}
}
Use a Linked AccountDeprecated
To generate a Task using a Linked Account, a Task request is created that contains the product and the _id of the LinkedAccount
. A Task is then created if the request is successful.
Authentication is handled via the API Key and Secret method.
Required Properties
product
string- One of
deposit
,verify
,paylink
,earn
, ortax
. linkedAccount
string- The
_id
of a LinkedAccount object.
POST
/task/createResponse
Successfully creating a Task will return a payload with a data
object containing metadata about the created task
, taskWorkflow
, and the associated company
. The Atomic Console can be used to track task progress. If you plan on implementing webhooks, we recommend saving the task _id
for reference.
task
object- Metadata for the first task in the task workflow.
taskWorkflow
object- Metadata for the created task workflow.
company
object- Metadata for the user's company.
Child Properties
{
"data": {
"task": {
"_id": "5d3b23b155f500465c895f60"
},
"taskWorkflow": {
"_id": "5d3b23b155f500465c895f5f"
},
"company": {
"_id": "5d77f9e1070856f3828945c6",
"name": "Mocky",
"branding": {
"logo": {
"url": "https://cdn-public.atomicfi.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
},
"color": "#090721"
}
}
}
}
Get Task Status
An endpoint to return the status of a Task. Submit the corresponding taskId
and receive the status
of that Task.
Authentication is handled via the API Key and Secret method.
Required Properties
taskId
string- The id of the Task. The
taskId
property is sent in several webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET
/task/:taskId/statusResponse
A successful request will return the createdAt
date, status
, and if a Task failed (Tasks with a status of "failed") a failReason
.
createdAt
date- The timestamp when the task was created, stored in UTC and ISO 8601 format.
status
string- The status of the task which may be
invited
,queued
,processing
,paused
,captcha
,mfa
,error
,failed
,retry
,completed
, ormanual
. failReason
stringOptional- The failure reason associated with a failed task. Will consist of one of the failure values.
{
"createdAt": "2023-01-03T16:40:48.009Z",
"status": "failed",
"failReason": "no-data-found"
}
Generate File URL
Generate a URL in order to download a user file (ex: paystubs PDFs). Each URL is valid for 1 hour.
Authentication is handled via the API Key and Secret method.
GET
/task/:taskId/file/:fileId/generate-urlResponse
A successful request will return a URL that can be used to download the file.
url
string- A URL that can be used to download the file. The URL is valid for 1 hour.
{
"url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
PrescreenBeta
Prescreen is an endpoint you can call prior to task creation in order to get a predicted conversion confidence, offering additional insight into your user and the likelihood they will succeed using our service.
Authentication is handled via the API Key and Secret method.
POST
/task/prescreenResponse
The response returns an object with a single confidence property with a string value. We will make this determination based on a variety of proprietary considerations such as traffic volumes and calculations with other similar connector types.
confidence
string- The likelihood of the user being successful using our flow. Will return a value of "HIGH" or "LOW".
{
"data": {
"confidence": "HIGH"
}
}