Atomic logo
API

UserLink 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

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.

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

These headers are included in requests that are made via the end user from client-side code, e.g. searching for their employer. The public token defaults to a 24 hour expiry, but can be set to a minimum of 30 minutes by passing in the desired duration using the optional tokenLifetime property in the call to /access-token. This minimum is to allow for users to complete variations of the flows, such as MFA, which can take time.

HeaderDescription
x-public-token Public token generated during access token creation.

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.

An AccessToken grants access to Atomic's API resources for an end user when its value is used as the x-public-token header.

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.

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

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.

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"
  }
}

A user has the option to link their payroll through their payroll provider or by navigating our employer-to-payroll system mapping. We have the notion of a Company that encompasses both aspects.

Use this endpoint to build a typeahead experience, as employed in our Transact SDK, or to get the company's _id for deeplinking to the login section of Transact.
Search for a Company using a text query. Searches can also be filtered by passing in additional properties detailed below.

Authentication can be handled via either the API Key and Secret method or the Access Token method.

querystring
Filters companies by name. Uses fuzzy matching to narrow results.
productstring
Filters companies by a specific product. Possible values include deposit, verify, and tax.
products[string]
Filters companies by a list of products; only companies that support all of the provided products will be returned. Possible values include deposit, verify, and tax.
tags[string]
Filters companies by a specific tag. Possible values include gig-economy, payroll-provider, and unemployment.
excludedTags[string]
Excludes companies by a specific tag. Possible values include gig-economy, payroll-provider, and unemployment.
POST/company/search
https://sandbox-api.atomicfi.com/company/search

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.

_idstring
Unique identifier for the company.
namestring
Company name.
statusstring
Possible values include operational or under-maintenance.
connector.availableProducts[string]
A list of compatible products.
branding.logo.urlstring
Logo for the company, in PNG format.
branding.colorstring
Branding color for the company.
tags[string]
Tags with which a company is associated. Possible values include gig-economy, payroll-provider, unemployment, and manual-deposits.
Example response
{
  "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"
      ]
    }
  ]
}

Each discrete payroll operation, such as a verification of income, direct deposit switch, or update to a payment account of file, will instantiate what is referred to as a Task in our system. A Task consists of an authentication step where Atomic logs into a payroll or service provider and an operation step where we read data or write to the system; either a direct deposit allocation or updating a payment account on file, depending on the Task.

This endpoint returns the details of a Task. Submit the corresponding taskId and receive the details of that Task.

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.

taskIdstring
The id of the Task. The taskId property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET/task/:taskId/details
https://sandbox-api.atomicfi.com/task/:taskId/details

A successful request will return the details of the task.

_idstring
The id of the task.
authenticatedboolean
Indicates whether or not the task has successfully authenticated against the payroll system.
companyobject
Metadata for the employer.
Child Properties
_idstring
Unique identifier for the company.
namestring
The name of the company
brandingobject
Metadata for the company's branding.
Child Properties
logoobject
Metadata for the company's logo.
Child Properties
urlstring
URL for the company's logo.
connectorobject
Metadata for the connector.
Child Properties
_idstring
Unique identifier for the connector.
namestring
The name of the connector
brandingobject
Metadata for the connector's branding.
Child Properties
logoobject
Metadata for the connector's logo.
Child Properties
urlstring
URL for the connector's logo.
createdAtdate
The timestamp when the task was created, stored in UTC and ISO 8601 format.
updatedAtdate
The timestamp when the task was last updated, stored in UTC and ISO 8601 format.
depositDataobjectOptional
If the task is a deposit task, this data will indicate the type of deposit switch performed.
Child Properties
accountTypestring
The type of the account. Possible values include savings, checking, or paycard.
distributionAmountnumber
The amount being distributed to the account. When distributionType is percent, the number represents a percentage of the total pay. When distributionType is fixed, this number represents a fixed dollar amount. This value is not set when distributionType is total.
distributionTypestring
The type of distribution for the account. Possible values include total, percent, or fixed.
lastFourstring
The last digits of the account number.
routingNumberstring
The routing number.
titlestring
The title of the account.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
linkedAccountstringOptional
The id of the linked account used to create the task.
metadataobjectOptional
The metadata provided by your system when the task was initialized.
payrollDataAvailableboolean
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
productstring
The product of the task. Possible values include deposit, verify, and tax.
statusstring
The status of the task which may be queued, processing, failed, or completed.
taskWorkflowobject
The task workflow of the task.
Child Properties
_idstring
The id of the task workflow.
userobject
The user that ran the task.
Child Properties
_idstring
The id of the user in atomic's system.
identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
Example response
{
  "data": {
    "task": {
      "_id": "65b15fd99b3f03aa9edff9de",
      "authenticated": true,
      "company": {
        "_id": "607e249736b9f053b536bde0",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
          }
        },
        "name": "Test Company"
      },
      "connector": {
        "_id": "607e249736b9f053b536bde1",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
          }
        },
        "name": "Test Connector"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:05.000Z",
      "depositData": {
        "accountType": "checking",
        "distributionAmount": 10,
        "distributionType": "fixed",
        "lastFourAccountNumber": "0000",
        "routingNumber": "22000000",
        "title": "Checking Account"
      },
      "failReason": "unknown-failure",
      "linkedAccount": "645963a0b754649972f3d4ac",
      "metadata": {
        "data": "test"
      },
      "payrollDataAvailable": false,
      "product": "deposit",
      "status": "failed",
      "taskWorkflow": {
        "_id": "643f2ed34253e21bdbd2de31"
      },
      "user": {
        "_id": "607e249736b9f053b536bdea",
        "identifier": "GUID"
      }
    }
  }
}

Calling this API returns the status of a Task. Submit the corresponding taskId and receive the status of that Task and payrollDataAvailable which indicates that any fetchable data is ready to be pulled via the corresponding API calls.

This endpoint is designed to be lightweight and intended for polling use cases.

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.

taskIdstring
The id of the Task. The taskId property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET/task/:taskId/status
https://sandbox-api.atomicfi.com/task/:taskId/status

A successful request will return the createdAt date, status, and if a Task failed (Tasks with a status of "failed") a failReason.

createdAtdate
The timestamp when the Task was created, stored in UTC and ISO 8601 format.
statusstring
The status of the task which may be queued, processing, failed, or completed.
payrollDataAvailableboolean
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
Example response
{
  "data": {
    "task": {
      "createdAt": "2023-01-03T16:40:48.009Z",
      "status": "failed",
      "failReason": "no-data-found",
      "payrollDataAvailable": false
    }
  }
}

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

taskIdstring
The _id of the Task, which can be retrieved either from interaction events during the Transact session with the user or from the associated webhooks.
fileIdstring
The _id of the file. This is returned in API calls for relevant data categories, such as /taxes for W-2's, or sent via relevant webhooks when a file is retrieved from the payroll system.
GET/task/:taskId/file/:fileId/generate-url
https://sandbox-api.atomicfi.com/task/:taskId/file/:fileId/generate-url

A successful request will return a URL that can be used to download the file.

urlstring
A URL that can be used to download the file. The URL is valid for 1 hour.
Example response
{
  "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}
This endpoint is currently in beta. If you would like access please reach out to your Customer Success Manager.

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

companyobject
Child Properties
namestring
The name of the employer provided to you by the end user.
idstring
If you have our company IDs mapped you can use an ID instead of relying on our search.
productstring
The name of the product for which you would like a conversion confidence prediction. Currently Verify is the only product supported.
POST/task/prescreen
https://sandbox-api.atomicfi.com/task/prescreen

The response returns an object with a single confidence property as 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.

confidencestring
The likelihood of the user being successful using our flow. Will return a value of "HIGH" or "LOW".
Example response
{
  "data": {
    "confidence": "HIGH"
  }
}

List deposit accounts once they've been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/deposit-accounts/:identifier
https://sandbox-api.atomicfi.com/deposit-accounts/:identifier

A successful response will return all direct deposit accounts on file for the user.

data[DepositAccounts]
An array of objects that include an array of deposit account objects, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "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
          }
        ]
      ],
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get employment data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/employment/:identifier
https://sandbox-api.atomicfi.com/employment/:identifier

A successful request will return the employment data for the user.

data[Employment]
An array of objects that include an employment object, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "employment": {
        "employeeType": "fulltime",
        "employmentStatus": "active",
        "jobTitle": "Product Manager",
        "startDate": "2017-04-19T12:00:00.000Z",
        "minimumMonthsOfEmployment": 58,
        "weeklyHours": 40,
        "employer": {
          "name": "Company Inc.",
          "address": {
            "line1": "12345 Enterprise Rd",
            "line2": "Suite 105",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "84111",
            "country": "USA"
          }
        }
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get identity data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/identity/:identifier
https://sandbox-api.atomicfi.com/identity/:identifier

A successful request will return the identity data for the user.

data[Identity]
An array of objects that include an identity object, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "identity": {
        "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"
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get income data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/income/:identifier
https://sandbox-api.atomicfi.com/income/:identifier

A successful request will return the income data associated with the account.

data[Income]
An array of objects that include an income object, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "income": {
        "income": 45000,
        "incomeType": "yearly",
        "annualIncome": 45000,
        "hourlyIncome": 21.56,
        "netHourlyRate": 18.44,
        "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
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get statements data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
limitstring
The number of statement records to return provided as a query string parameter.
GET/statements/:identifier
https://sandbox-api.atomicfi.com/statements/:identifier

A successful request will return the statements for the user.

data[Statement]
An array of objects that include a statements object, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "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": 37,
          "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]"
          },
          "parsedData": {
            "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": 37,
            "deductions": [
              {
                "category": "taxes",
                "rawLabel": "Federal Income Tax",
                "amount": 200,
                "ytdAmount": 2000
              },
              {
                "category": "taxes",
                "rawLabel": "Utah State Tax",
                "amount": 50,
                "ytdAmount": 500
              },
              {
                "category": "other",
                "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": [
              {
                "rawLabel": "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": 34,
          "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]"
          }
        }
      ],
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get timesheets data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/timesheets/:identifier
https://sandbox-api.atomicfi.com/timesheets/:identifier

A successful request will return the timesheets for the user.

data[Timesheet]
An array of objects that include a timesheets object, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "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"
        }
      ],
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

Get tax data once its been synced to Atomic from the payroll provider.

This data is only available if access has been granted via Verify or Continous Access.
For purely Deposit switch use cases, this information is not collected.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
linkedAccountstring
The _id of a LinkedAccount object provided as a query string parameter.
taskstring
The _id of the task, provided as a query string parameter, that was used to retrieve the data. If this parameter is not provided, the data that was most recently retrieved from the payroll system will be returned.
GET/taxes/:identifier
https://sandbox-api.atomicfi.com/taxes/:identifier

A successful request will return the taxes for the user.

data[Tax]
An array of objects that include a array of taxes objects, company, connector, task ID, and linkedAccount ID if enabled.
Example response
{
  "data": [
    {
      "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",
              "line2": "Suite 230",
              "city": "Preston",
              "state": "VA",
              "postalCode": "20191"
            },
            "controlNumber": "012547 WY/OA7",
            "employeeName": {
              "first": "Kris",
              "last": "Public"
            },
            "employeeAddress": {
              "line1": "1 Main St",
              "line2": "Apartment 123",
              "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
              }
            ],
            "statutory": false,
            "retirementPlan": true,
            "thirdPartySickPay": false,
            "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
              }
            ]
          }
        },
        {
          "type": "1099",
          "year": "2020-01-01T00:00:00.000Z",
          "form": {
            "_id": "60abeff60836730008616faf",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        }
      ],
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      },
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "linkedAccount": "5f7212103a40e91f95ba376d",
      "task": "602414d84f9a1980cf5eafcc"
    }
  ]
}

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. Linked Accounts are the mechanism we use to facilitate our Continuous Access product. They are also used to initiate Task Workflows in the background.

Continuous Access must be enabled for your institution to use Linked Accounts.

For a Continuous Access workflow, use this endpoint to list accounts linked to a particular user.

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.

identifierstring
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's identifier.
GET/linked-account/list/:identifier
https://sandbox-api.atomicfi.com/linked-account/list/:identifier

The response contains an array of Linked Account objects for the end user.

_idstring
Unique identifier for the linked account.
validboolean
Whether or not the account credentials were valid after the last attempted use.
transactRequiredboolean
Whether or not using the account requires the user to be present within Transact.
lastSuccessstring
The datetime of the last successful usage of the account in ISO 8601 format.
lastFailurestring
The datetime of the last failed usage of the account in ISO 8601 format.
companyobject
The Company to which the account is linked.
connectorobject
The Connector to which the account is linked.
Example response
{
  "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 this endpoint to initiate a Task Workflow in the background with a Linked Account. Send a request to this endpoint containing an array of the tasks you wish to execute and the _id of the LinkedAccount. This is generally used to refresh the data sync'ed to Atomic from a payroll 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.

We recommend against using this endpoint for Deposit Tasks without the user present. Most payroll systems now require MFA codes to modify a deposit.
tasks[TaskConfiguration]
Defines configuration for the tasks you wish to execute as part of the task workflow.
Child Properties
operationstring
Specifies the operation with which to initialize Transact. One of deposit, verify, or tax.
productstringDeprecated
One of deposit, verify, or tax. This is deprecated in favor of operation. product will be available for the foreseeable future and we will give ample warning when it is planned to be sunset.
onCompletestring
The 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"

onFailstring
The 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"

distributionobject
Optionally pass in enforced deposit settings.
Child Properties
typestring
Can be total to indicate the remaining balance of their paycheck, fixed to indicate a specific dollar amount, or percent to indicate a percentage of their paycheck.
amountnumber

When distribution.type is fixed, it indicates a dollar amount to be used for the distribution. When distribution.type is percent, it indicates a percentage of a paycheck. This is not required if distribution.type is total.

This value cannot be updated by the user unless canUpdate is set to true.

linkedAccountstring
The _id of a LinkedAccount object.
POST/task-workflow/from-linked-account
https://sandbox-api.atomicfi.com/task-workflow/from-linked-account

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 Task List in 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.

taskobject
Metadata for the first task in the task workflow.
Child Properties
_idstring
Unique identifier for the task.
taskWorkflowobject
Metadata for the created task workflow.
Child Properties
_idstring
Unique identifier for the task workflow.
companyobject
Metadata for the end user's company or payroll provider.
Child Properties
_idstring
Unique identifier for the company.
namestring
The name of the company
brandingobject
Metadata for the company's branding.
Child Properties
logoobject
Metadata for the company's logo.
Child Properties
urlstring
URL for the company's logo.
colorstring
Hexadecimal color for the company's brand.
Example response
{
  "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"
      }
    }
  }
}

A User is an entity in the Atomic system that is created during the access token creation process. Details about a user's accounts are stored on the user object for reference as needed in an operation; ie. for adding a deposit account to a payroll system or updating the card-on-file for a merchant service.

This endpoint is used to add data to a user in response to an onDataRequest event emitted from our Transact SDK. Any data passed will be upserted into the user's object. The typical use case is to delay the transmission of sensitive data (bank accounts, cards, identity information, etc.) until our system has need for such data.

The shape of the request body is similar to our access token creation endpoint, except the data to be added/updated will be nested in a data key, and the identifier will not be nested, but remain on the first-level of the object.

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/user
https://sandbox-api.atomicfi.com/user

This endpoint is used to retrieve tasks for the specified user.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
statusstring
The status of the task, provided as a query string parameter, which may be queued, processing, failed, or completed.
payrollDataAvailablestring
A boolean value, provided as a query string parameter, indicating whether or not the user's payroll data is ready for retrieval via API.
GET/user/:identifier/tasks
https://sandbox-api.atomicfi.com/user/:identifier/tasks

A successful response will return an object with data.tasks equal to an array of task objects with the following properties.

_idstring
The id of the task.
authenticatedboolean
A boolean value indication whether or not the task has successfully authenticated against the payroll system.
createdAtdate
The timestamp when the task was created, stored in UTC and ISO 8601 format.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
payrollDataAvailableboolean
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
productenum
The product relevant to the executed task. Options are:
    depositverify
statusstring
The status of the task which may be queued, processing, failed, or completed.
Example response
{
  "data": {
    "tasks": [
      {
        "_id": "65b3f3c8b871a9626c36d103",
        "authenticated": true,
        "createdAt": "2024-01-26T18:02:55.795Z",
        "payrollDataAvailable": true,
        "product": "verify",
        "status": "completed"
      },
      {
        "_id": "65b3f3c8b871a9626c36d103",
        "authenticated": true,
        "createdAt": "2024-01-26T18:02:55.795Z",
        "failReason": "bad-credentials",
        "payrollDataAvailable": false,
        "product": "deposit",
        "status": "failed"
      }
    ]
  }
}

This endpoint is used to remove monitoring for users that have payroll data monitoring enabled via continuous access.

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.

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
PUT/user/:identifier/end-monitoring
https://sandbox-api.atomicfi.com/user/:identifier/end-monitoring

A successful response will return a json object with success equal to true.

Example response
{
  "success": true
}

Webhooks are the recommended way to receive data and updates from the Atomic system. They allow us to send real-time updates as user-driven events occur within the Atomic system to an API endpoint in your system via HTTPS POST calls. All webhooks are secured via an API Secret used to sign the webhook with an HMAC signature which is included in the header of the HTTPS call. Refer to our How to Secure Webhooks guide for more details.

Webhook endpoints can be configured in the Atomic Console or via API.

This API is used to register a webhook endpoint for receiving updates 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.

urlstring
The URL of the endpoint where Atomic will send webhook events for the associated webhook event types.
secretIdstring
The ID of the API secret that will be used to create the HMAC signature of the webhook event.
eventTypes[string]
A list of webhook event types that the endpoint will listen for.
POST/webhooks/endpoints
https://sandbox-api.atomicfi.com/webhooks/endpoints

A successful response will return a JSON object with data.endpoint equal to the newly created endpoint object along with the _id field for the new webhook endpoint.

Example response
{
  "data": {
    "endpoint": {
      "url": "https://your-endpoint.com/webhooks",
      "secretId": "65c6adc38a19739b40d68a60",
      "eventTypes": [
        "task-authentication-status-updated",
        "task-status-updated"
      ],
      "_id": "65cd12a0fee167d71e442b1b"
    }
  }
}

This endpoint is used to retrieve the configured webhook endpoints.

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/webhooks/endpoints
https://sandbox-api.atomicfi.com/webhooks/endpoints

A successful response will return a JSON object with data.endpoints equal to an array of endpoint objects with the following properties.

_idstring
The ID of the endpoint in the Atomic system.
urlstring
The URL of the endpoint where Atomic will send webhook events for the associated webhook event types.
secretIdstring
The ID of the API secret that will be used to create the HMAC signature of the webhook event.
eventTypes[string]
A list of webhook event types that the endpoint will listen for.
Example response
{
  "data": {
    "endpoints": [
      {
        "_id": "65cd0ead25ae54fd510bc441",
        "url": "https://your-endpoint.com/webhooks",
        "secretId": "65c6adc38a19739b40d68a60",
        "eventTypes": [
          "task-status-updated"
        ]
      },
      {
        "_id": "65cd12a0fee167d71e442b1b",
        "url": "https://your-second-endpoint.com/webhooks",
        "secretId": "65c6adc38a19739b40d68a60",
        "eventTypes": [
          "task-authentication-status-updated"
        ]
      }
    ]
  }
}

This endpoint is used to update a webhook endpoint which has already been registered in 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.

urlstring
The URL of the endpoint where Atomic will send webhook events for the associated webhook event types.
secretIdstring
The ID of the API secret that will be used to create the HMAC signature of the webhook event.
eventTypes[string]
A list of webhook event types that the endpoint will listen for.
PUT/webhooks/endpoints/:_id
https://sandbox-api.atomicfi.com/webhooks/endpoints/:_id

A successful response will return a JSON object with data.endpoint equal to the updated endpoint along with the _id field.

Example response
{
  "data": {
    "endpoint": {
      "url": "https://your-endpoint-updated.com",
      "secretId": "65c6adc38a19739b40d68a60",
      "eventTypes": [
        "task-status-updated"
      ],
      "_id": "65cd12a0fee167d71e442b1b"
    }
  }
}

This endpoint is used to delete a webhook endpoint 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.

DELETE/webhooks/endpoints/:_id
https://sandbox-api.atomicfi.com/webhooks/endpoints/:_id

A successful response will return a JSON object with successequal to true.

Example response
{
  "success": true
}

API secrets can be configured in the Atomic Console or via API.

This endpoint is used to create an API secret in 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.

namestring
The name of the secret.
POST/secrets
https://sandbox-api.atomicfi.com/secrets

A successful response will return a JSON object with data.secret equal to the newly created secret.

_idstring
The id of the secret.
createdAtstring
The date the secret was created in ISO 8601 format.
namestring
The name of the secret.
tokenstring
The value of the secret. This is used to make requests to the Atomic api. This value is only viewable in the returned data of this endpoint and in the Atomic console.
Example response
{
  "data": {
    "secret": {
      "_id": "65cd3c146e611eb3ebdf4c07",
      "createdAt": "2024-02-14T22:17:56.312Z",
      "name": "my secret",
      "token": "03e87171-cadc-43a7-8c31-a9459d94eb10"
    }
  }
}

This endpoint is used to retrieve all registered API secrets along with the webhook endpoints that they are assigned to.

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/secrets
https://sandbox-api.atomicfi.com/secrets

A successful response will return a JSON object with data.secrets equal to an array of API secret objects with the following properties.

_idstring
The id of the secret.
createdAtstring
The date the secret was created in ISO 8601 format.
namestring
The name of the secret.
endpoints[endpoints]
The list of webhook endpoints that the secret is assigned to.
Example response
{
  "data": {
    "secrets": [
      {
        "_id": "65c6adc38a19739b40d68a60",
        "name": "default",
        "createdAt": "2024-02-09T22:56:06.842Z",
        "endpoints": [
          {
            "_id": "65cd0ead25ae54fd510bc441",
            "url": "https://your-endpoint.com",
            "eventTypes": [
              "task-status-updated"
            ]
          },
          {
            "_id": "65cd0ead25ae54fd510bc441",
            "url": "https://your-other-endpoint.com",
            "eventTypes": [
              "task-authentication-status-updated"
            ]
          }
        ]
      },
      {
        "_id": "65cd3b4595374196666d4d37",
        "name": "new secret",
        "createdAt": "2024-02-09T22:55:46.240Z",
        "endpoints": []
      }
    ]
  }
}

This endpoint is used to delete an API secret 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.

DELETE/secrets/:_id
https://sandbox-api.atomicfi.com/secrets/:_id

A successful response will return a JSON object with successequal to true.

If a secret is currently assigned to a webhook endpoint, this endpoint will throw an error with status code of 400. Secrets will need to be unassigned from all webhook endpoints before they can be deleted. Unassign API secrets by updating any webhooks associated with the secret to different secrets.
Example response
{
  "success": true
}