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

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:

IP allowlisting can be enabled for your account. When it is, requests authenticated with your API Key and Secret from any other address are rejected with a 401 and error code 40111 (Invalid IP address.). Contact your Atomic representative to set up or change the list.
HeaderDescription
x-api-keyAPI Key for your Atomic account
x-api-secretAPI Secret for your Atomic account

Access Token

A publicToken will be included in the headers of requests which are made via the end user from client-side code, e.g. searching for their employer or initializing a Task. The publicToken defaults to a 24 hour expiry, but can be set to a minimum of 30 minutes or a maximum of 30 days by passing in the desired duration using the optional tokenLifetime property in the call to /access-token. The 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.

Mutual TLS

Optionally, Atomic can require a client certificate on connections from your servers. Requests using mutual TLS go to a dedicated hostname per environment and still carry the API Key and Secret headers above. Endpoints routed through Atomic's PCI Card Data Environment do not support mutual TLS. See the Mutual TLS for API Requests guide for requirements and setup.

Request Body Encryption

Optionally, the JSON body of a request authenticated with your API Key and Secret can be encrypted as a JWE using a public key Atomic publishes for your account. Send the encrypted payload as { "encryptedBody": "..." } and include the header below. See the Request Body Encryption guide for details.

HeaderDescription
x-enc-key-id The _id of the public key used to encrypt the body, from Get JWE Public Keys.

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 Request The request was unacceptable. This includes request bodies or parameters that fail validation (message Invalid request payload, with details in data.errors) and requests that reference a user or other resource that does not exist (for example User not found.).
401Unauthorized Missing or invalid credentials. See Authentication errors below.
403Forbidden Your credentials are valid, but the endpoint is not enabled for your account, or the public token used does not belong to the user named in the request.
404Not Found The URL does not match any endpoint. Check the path and HTTP method. A user or resource that cannot be found returns 400, not 404.
422Unprocessable EntityThe requested product is not supported by this endpoint.
429Too Many RequestsToo many requests, please try again later.
50XInternal Server ErrorAn error occurred with our API.

Error response body

Every error response uses the same JSON shape. message is a human-readable summary. code is a numeric Atomic error code whose first three digits match the HTTP status; it is present on most errors but omitted on schema validation failures. type names the kind of error, and data carries additional detail when there is any. Validation failures include data.errors, a list of readable messages, and data.verboseErrors, the raw output of the schema validator.

Example validation error 
{
  "type": "BadRequestError",
  "message": "Invalid request payload",
  "data": {
    "errors": [
      "must have required property 'identifier'"
    ],
    "verboseErrors": [
      {
        "instancePath": "",
        "schemaPath": "#/required",
        "keyword": "required",
        "params": {
          "missingProperty": "identifier"
        },
        "message": "must have required property 'identifier'"
      }
    ]
  }
}
Example error with a code 
{
  "type": "ClientError",
  "message": "User not found.",
  "code": 40011
}

Authentication errors

A 401 response includes a code that identifies the cause. The most common are listed below.

CodeMessageCause
40101Unauthorized.The API key or secret is not valid.
40103Expired.The public token has expired. Create a new access token.
40104Invalid token.The public token is not recognized or has been revoked.
40106Authentication has not been configured for this endpoint. No credentials were sent, or the credentials sent are not the kind this endpoint accepts. Most often this means a x-public-token header was sent to an endpoint that requires x-api-key and x-api-secret, or the other way around. Check the authentication listed for the endpoint.
40111Invalid IP address. IP allowlisting is enabled for your account and the request came from an address that is not on the list.

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. The minimum allowed is 1,800 (30 min). The max allowed is 2,592,000 (30 days). Shorter token lifetimes are recommended for security purposes.

Default value: 86,400 (24 hours)

Products may have additional required properties. Refer to the implementation pages for additional details.
POST/access-token
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER"
}
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": "PUBLIC_TOKEN"
  }
}

Revoke Access Token

This endpoint is used to revoke an existing AccessToken. This action invalidates the token, preventing it from being used to access Atomic's API resources.

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

publicTokenstring
The publicToken associated with the AccessToken you wish to revoke. Passed with the URL as a path parameter (e.g., /access-token/:publicToken/revoke). Replace :publicToken with the value returned by the access-token API response.
PUT/access-token/:publicToken/revoke
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/access-token/:publicToken/revoke

Response

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

Example response 
{
  "result": {
    "success": true
  }
}

CoAuth

Atomic has established direct partnerships with select payroll systems to enable seamless user lookups, a capability branded as CoAuth.

By identifying a user and leveraging the payroll system’s stored multi-factor authentication (MFA) flow, Atomic can securely verify the user’s identity. Once verified, the payroll system provides the necessary access for Atomic to update the user’s direct deposit information efficiently; reducing friction, enhancing conversion rates, and overall improving the user experience.

Pre-screen

The Pre-Screen API allows for pre-screening a user through CoAuth by using their identity data to perform a lookup within supported payroll systems. This API is typically called after the user expresses intent to set up direct deposit but before launching them into Transact.

Once the user is identified within a payroll system, Atomic can seamlessly set up direct deposit on their behalf, improving conversion rates and creating a more streamlined user experience.

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
The user's unique identifier, to be used again during AccessToken creation.

Optional Properties

identityobject
An object containing identity data for the user to be used by Atomic for the lookup operation in the CoAuth enabled payroll system. When provided, all four child properties are required. When omitted, Atomic uses the identity data already stored for the user, such as the identity sent during AccessToken creation; if no identity data is available, no lookup is performed and an empty incomeSources array is returned.
Child Properties
Required Properties
ssnstring
Social Security Number for the user.
dateOfBirthstring
The date of birth for the user, in ISO 8601 date format.
phonestring
The phone number for the user.
emailstring
The email address for the user. Must match what is on file with the payroll system.
POST/pre-screen
{
  "identifier": "END_USER_IDENTIFIER",
  "identity": {
    "ssn": "666-00-9876",
    "dateOfBirth": "1980-01-01",
    "phone": "555-867-5309",
    "email": "test@example.com"
  }
}
https://sandbox-api.atomicfi.com/pre-screen

Response

A successful pre-screen will return a data object containing an incomeSources array. Each object in the array will contain details about the payroll system where the user was verified and a data object with specifics regarding the lookup operation. The array is empty when the user was not found in any supported payroll system.

incomeSources[IncomeSource]
An array of IncomeSource objects containing details of the lookups performed by Atomic in the CoAuth enabled payroll systems.
Child Properties
Required Properties
dataobject
An object with details about the lookup operation in the payroll system.
Child Properties
Required Properties
userStatusenum
The status of the lookup. Options are:
    VERIFIED_PAYROLLNOT_FOUNDUNSUPPORTED_PAYROLL
originenum
The origin of the income source verification. Currently limited to pre-screen.
lookupDatestring
The timestamp of when the income source was derived or verified. Returned in ISO 8601 format.
company{Company}
An object with details for the payroll system where the user was verified.
Child Properties
Required Properties
_idstring
An identifier for the payroll system used for the pre-screen.
namestring
The name of the payroll system used for the pre-screen.
brandingobject
Metadata for the company's branding.
Child Properties
Required Properties
logoobject
Metadata for the company's logo.
Child Properties
Required Properties
urlstring
URL for the company's logo.
Optional Properties
backgroundColorstring
A hex code for the background color of the logo, returned where needed. If not present, the branding.color should be used.
Optional Properties
colorstring
A hex code for the alternate color in a payroll system. This is typically used for button colors and other secondary color themes.
Optional Properties
connectorobjectOptional
An object with details for the connector Atomic uses to access the payroll system. Contains the same _id, name, and branding properties as company. Omitted when no connector information is available.
Child Properties
Required Properties
_idstring
An identifier for the connector.
Optional Properties
namestring
The name of the connector.
brandingobject
Metadata for the connector's branding, with the same shape as company.branding.
Example response 
{
  "success": true,
  "data": {
    "incomeSources": [
      {
        "data": {
          "userStatus": "VERIFIED_PAYROLL",
          "origin": "pre-screen",
          "lookupDate": "2024-08-27T16:44:21.482Z"
        },
        "company": {
          "_id": "5d38f1e8512bbf71fb776015",
          "name": "ADP",
          "branding": {
            "logo": {
              "url": "https://atomicfi-public-production.s3.amazonaws.com/a8d7e778-b718-45e0-b639-2305e33e7f95_ADP.png",
              "backgroundColor": "#F2F2F2"
            },
            "color": "#9460FE"
          }
        },
        "connector": {
          "_id": "5d38f1e8512bbf71fb776016",
          "name": "ADP",
          "branding": {
            "logo": {
              "url": "https://atomicfi-public-production.s3.amazonaws.com/a8d7e778-b718-45e0-b639-2305e33e7f95_ADP.png",
              "backgroundColor": "#F2F2F2"
            },
            "color": "#9460FE"
          }
        }
      }
    ]
  }
}

Company

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.

Company Search

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.

Use this lookup when you need to identify a payroll provider. If you need additional metadata for a specific result, use the returned _id with Company Details.

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

Required Properties

querystring
Filters companies by name. Uses fuzzy matching to narrow results. Maximum length is 50 characters.

Optional Properties

scopes[string]
Filters companies by product suite. Further filtering is possible with the product and products properties. Options are:
    pay-linkuser-linkcustom
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.
franchiseParentstring
The _id of a franchise parent company. Restricts results to that brand’s franchisees, for building a franchise location picker. query is still required.
POST/company/search
{
  "query": "Doordash",
  "product": "deposit"
}
https://sandbox-api.atomicfi.com/company/search

Response

Successfully querying the Company search endpoint will return a payload with a data array of Company objects.

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action 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.
connector.capabilities.supportedPaymentMethods[string]
When present, shows the supported payment method types for the connector (card, bank). Often omitted for deposit-only connectors.
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.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
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",
          "backgroundColor": "#F2F2F2"
        },
        "color": "#9460FE"
      },
      "tags": [
        "gig-economy"
      ]
    }
  ]
}

Company List

Use this endpoint to retrieve the list of companies available to your account. It is well suited for building a static company catalog, pulling a snapshot of the catalog for design or planning workflows, or pre-validating which companies your customers can connect.

Results are sorted by popularity, with the most frequently selected companies appearing first. Popularity is based on how often users select each company in Transact over a rolling two-week window.

For typeahead-style lookup by name, use Company Search. For a single company by _id, use Company Details.

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

These are query string parameters on the request URL (this endpoint is GET, so parameters are not sent as a JSON body). Pass a single value with product or scope to narrow the list.

Example: /company/list?scope=user-link&product=deposit

productenumOptional
Filters to companies that support the specified product.

deposit — /company/list?product=deposit
    deposit
scopeenumOptional
Filters companies by product suite. When omitted, your account’s configured scopes are applied.

user-link — /company/list?scope=user-link
    user-link
limitnumberOptional
Maximum number of companies to return per request. Must be between 1 and 100. Defaults to 100.
skipnumberOptional
Number of records to skip before returning results, for cursor-style pagination. Must be 0 or greater. Defaults to 0.
GET/company/list
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/company/list

Response

A successful response returns a payload with a data array of Company objects.

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action until it has been restored.

When a connector defines Pay Link payment methods, each item also includes connector.capabilities.supportedPaymentMethods (for example card or bank). Many deposit-only connectors omit this field.

data[object]
Array of company objects matching the request filters.
_idstring
Unique identifier for the company.
namestring
Company name.
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.
connector.availableProducts[string]
A list of compatible products.
connector.capabilities.supportedPaymentMethods[string]
When present, shows the supported payment method types for the connector (card, bank). Often omitted for deposit-only connectors.
statusstring
Possible values include operational, under-maintenance, and disabled.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
Example response 
{
  "success": true,
  "data": [
    {
      "_id": "5d38f1e8512bbf71fb776015",
      "name": "DoorDash",
      "status": "operational",
      "createdAt": "2019-07-24T18:03:20.184Z",
      "tags": [
        "gig-economy"
      ],
      "branding": {
        "logo": {
          "url": "https://atomicfi-public-production.s3.amazonaws.com/a8d7e778-b718-45e0-b639-2305e33e7f95_doordash.svg",
          "backgroundColor": "#FF3008"
        },
        "color": "#FF3008"
      },
      "connector": {
        "_id": "5d38f182512bbf0c06776013",
        "availableProducts": [
          "deposit"
        ],
        "capabilities": {
          "distributionTypes": [
            "total"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "availableProducts": [
        "deposit"
      ],
      "availableActions": []
    },
    {
      "_id": "5fc810d63279fe0009c493ec",
      "name": "Paychex Flex",
      "status": "operational",
      "createdAt": "2020-12-02T22:10:30.966Z",
      "tags": [
        "payroll-provider"
      ],
      "branding": {
        "logo": {
          "url": "https://cdn-public.atomicfi.com/9d736728-7ac7-46f6-b559-ddc711a9253b_paychex.png",
          "backgroundColor": "#004B8D"
        },
        "color": "#004B8D"
      },
      "connector": {
        "_id": "5f516d0ad5e724000712f154",
        "availableProducts": [
          "deposit"
        ],
        "capabilities": {
          "distributionTypes": [
            "total",
            "fixed",
            "percent"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "availableProducts": [
        "deposit"
      ],
      "availableActions": []
    }
  ]
}

Company Details

Use this endpoint to retrieve all information Atomic has for a specific company.

The response includes company metadata such as branding, status, search information, and connector capabilities.

This can be useful when you need to render payroll provider branding in your own UI, confirm whether a company supports direct deposit-related flows before deeplinking, or inspect connector capabilities such as supported distribution actions, distribution types, and authentication methods.

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

companyIdstring
The _id of the company. Use the value returned by Company Search or another Atomic company lookup.
GET/company/:companyId/details
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/company/:companyId/details

Response

A successful request returns the public company details payload for the specified company, including status, search metadata, connector capabilities, supported products, and payroll-provider branding details.

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action until it has been restored.
_idstring
Unique identifier for the company.
namestring
Company name.
subtextstring
Optional descriptive text shown alongside the company name.
createdAtstring
Timestamp for when the company record was created.
brandingobject
Branding metadata for the company.
Child Properties
Optional Properties
logoobject
Logo metadata for the company.
Child Properties
Optional Properties
urlstring
URL for the company logo.
deprecatedFileTypeUrlstring
Legacy URL for the company logo in a deprecated file format.
backgroundColorstring
Background color used behind the company logo.
colorstring
Primary branding color used for the company.
tags[string]
Company tags associated with the payroll provider.
statusstring
Possible values include operational, under-maintenance, and disabled.
searchstring
Search text used to match the company in company lookup flows.
keywords[string]
Supplemental search keywords associated with the company.
isConfigurableConnectorboolean
Indicates whether the selected connector can be configured.
alternativeConnectors[]
Alternative connector options available for the company, if any.
coAuthConnectors[]
Co-auth connector options available for the company, if any.
franchiseParentobject
Metadata for the franchise parent company when this company is a franchise child.
Child Properties
Optional Properties
_idstring
Unique identifier for the franchise parent company.
namestring
Display name for the franchise parent company.
brandingobject
Branding metadata for the franchise parent company.
availableProducts[string]
Products that can be launched with this company.
connectorobject
Connector metadata for this company.
Child Properties
Optional Properties
_idstring
Unique identifier for the connector.
namestring
Display name for the connector.
createdAtstring
Timestamp for when the connector record was created.
brandingobject
Branding metadata for the connector.
availableProducts[string]
Products that can be launched with this connector.
capabilitiesobject
Connector capabilities exposed by the public API.
Child Properties
Optional Properties
headlessAuthenticationboolean
Whether the connector supports headless authentication.
ssoAuthenticationboolean
Whether the connector supports SSO authentication.
distributionActions[string]
Distribution actions supported by the connector, such as creating a new deposit allocation.
distributionTypes[string]
Distribution types supported by the connector, such as total, fixed, or percent.
authenticationMethods[string]
Authentication methods supported by the connector.
showConfirmDistributionPageboolean
Whether the connector shows a distribution confirmation page before submitting changes.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
Example response 
{
  "success": true,
  "data": {
    "_id": "5fc810d63279fe0009c493ec",
    "createdAt": "2020-12-02T22:10:30.966Z",
    "branding": {
      "logo": {
        "url": "https://cdn-public.atomicfi.com/9d736728-7ac7-46f6-b559-ddc711a9253b_paychex.png",
        "backgroundColor": "#004B8D"
      },
      "color": "#004B8D"
    },
    "name": "Paychex Flex",
    "subtext": "",
    "tags": [
      "payroll-provider",
      "us-incorporated"
    ],
    "alternativeConnectors": [],
    "isConfigurableConnector": false,
    "coAuthConnectors": [],
    "search": "paychex flex",
    "keywords": [],
    "connector": {
      "_id": "5f516d0ad5e724000712f154",
      "branding": {
        "logo": {
          "url": "https://cdn-public.atomicfi.com/9d736728-7ac7-46f6-b559-ddc711a9253b_paychex.png",
          "backgroundColor": "#004B8D"
        },
        "color": "#004B8D"
      },
      "name": "Paychex Flex",
      "createdAt": "2020-09-03T22:24:10.729Z",
      "availableProducts": [
        "deposit"
      ],
      "capabilities": {
        "headlessAuthentication": true,
        "ssoAuthentication": false,
        "distributionActions": [
          "create"
        ],
        "distributionTypes": [
          "total",
          "fixed",
          "percent"
        ],
        "authenticationMethods": [
          "standard-auth",
          "true-auth",
          "true-auth-desktop"
        ],
        "showConfirmDistributionPage": true
      }
    },
    "status": "operational",
    "availableProducts": [
      "deposit"
    ]
  }
}

Task

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.

Get Task Details

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.

Required Properties

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

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/task/:taskId/details

Response

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
Required Properties
_idstring
Unique identifier for the company.
namestring
The name of the company
Optional Properties
brandingobject
Metadata for the company's branding.
Child Properties
Optional Properties
logoobject
Metadata for the company's logo.
Child Properties
Optional Properties
urlstring
URL for the company's logo.
connectorobject
Metadata for the connector.
Child Properties
Required Properties
_idstring
Unique identifier for the connector.
namestring
The name of the connector
Optional Properties
brandingobject
Metadata for the connector's branding.
Child Properties
Optional Properties
logoobject
Metadata for the connector's logo.
Child Properties
Optional 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
Optional 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.
lastFourAccountNumberstring
The last four digits of the account number. If your account is configured to receive full account information, this field is replaced by accountNumber, containing the full 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.. Other transitional values may appear while a task is being processed; treat any value other than completed or failed as in progress.
taskWorkflowobject
The Task Workflow of the Task. When multiple tasks are associated with a single workflow, they will all have the same taskWorkflow object. Every Task is associated with a Task Workflow, even if it not associated with another Task.
Child Properties
Required Properties
_idstring
The id of the Task Workflow.
userobject
The user who processed the Task.
Child Properties
Required 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"
      }
    }
  }
}

Get Task Status

Calling this API returns the status of a Task. Submit the corresponding taskId and receive the status of that Task. For verify Tasks, the response also includes 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.

Required Properties

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

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/task/:taskId/status

Response

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.. Other transitional values may appear while a task is being processed; treat any value other than completed or failed as in progress.
payrollDataAvailablebooleanOptional
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api. Only returned for verify Tasks.
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": "completed",
      "payrollDataAvailable": true
    }
  }
}

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

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/task/:taskId/file/:fileId/generate-url

Response

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

PrescreenBeta

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.

Required Properties

companyobject
Child Properties
Required Properties
namestring
The name of the employer provided to you by the end user.
Optional Properties
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
{
  "company": {
    "name": "Amazon"
  },
  "product": "verify"
}
https://sandbox-api.atomicfi.com/task/prescreen

Response

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

Deposit Accounts

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
GET/deposit-accounts/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/deposit-accounts/:identifier

Response

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

Employment

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
GET/employment/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/employment/:identifier

Response

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

Identity

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
GET/identity/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/identity/:identifier

Response

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

Income

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
GET/income/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/income/:identifier

Response

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

Statements

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
limitstring
The number of statement records to return provided as a query string parameter.
GET/statements/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/statements/:identifier

Response

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

Timesheets

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
includeOutputMetadatastring
If this field, provided as a query string parameter, is set to true, the outputMetadata will be included in the response.
GET/timesheets/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/timesheets/:identifier

Response

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

Taxes

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

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

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.
typestring
The type of tax form to return, provided as a query string parameter. Possible values include w2 and 1040. If this parameter is not provided, all tax forms are returned.
GET/taxes/:identifier
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/taxes/:identifier

Response

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

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

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

Required Properties

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/linked-account/list/:identifier

Response

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 a Linked Account

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.

Required Properties

tasks[TaskConfiguration]
Defines configuration for the tasks you wish to execute as part of the task workflow.
Child Properties
Required Properties
productstring
The product to run for this task. One of deposit, verify, or tax.
Optional Properties
distributionobject
Optionally pass in enforced deposit settings.
Child Properties
Optional 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.

actionstring
The change to make to the deposit allocation. Can be create to add a new allocation, update to modify an existing allocation, or delete to remove one.

Default value: "create"

linkedAccountstring
The _id of a LinkedAccount object.
POST/task-workflow/from-linked-account
{
  "tasks": [
    {
      "product": "verify"
    }
  ],
  "linkedAccount": "5f7212103a40e91f95ba376d"
}
https://sandbox-api.atomicfi.com/task-workflow/from-linked-account

Response

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
Required Properties
_idstring
Unique identifier for the task.
taskWorkflowobject
Metadata for the created task workflow.
Child Properties
Required Properties
_idstring
Unique identifier for the task workflow.
companyobject
Metadata for the end user's company or payroll provider.
Child Properties
Required Properties
_idstring
Unique identifier for the company.
namestring
The name of the company
Optional Properties
brandingobject
Metadata for the company's branding.
Child Properties
Optional Properties
logoobject
Metadata for the company's logo.
Child Properties
Optional 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"
      }
    }
  }
}

User

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.

End Monitoring

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.

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.
PUT/user/:identifier/end-monitoring
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/user/:identifier/end-monitoring

Response

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

Example response 
{
  "success": true
}

Get Tasks

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.

Required Properties

identifierstring
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

statusstring
Filters tasks by status, provided as a query string parameter. Commonly queued, processing, failed, or completed.; the value must exactly match the task's current status.
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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/user/:identifier/tasks

Response

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.. Other transitional values may appear while a task is being processed; treat any value other than completed or failed as in progress.
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"
      }
    ]
  }
}

Update User

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
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER",
  "data": {
    "account": {
      "accountNumber": "220000000",
      "routingNumber": "110000000",
      "type": "checking",
      "title": "Premier Plus Checking"
    }
  }
}
https://sandbox-api.atomicfi.com/user

Webhooks

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.

Use these endpoints to manage where Atomic sends webhook event payloads. For the payloads sent to your endpoint, see the Webhooks Reference.

Create Endpoint

This API is used to register a webhook endpoint for receiving updates from the Atomic system. The secretId must refer to an API secret that belongs to your account.

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

urlstring
The URL where Atomic will send webhook events for the associated webhook event types. Must be a valid URL.
secretIdstring
The ID of an API secret on your account. Atomic uses this secret to create the HMAC signature for webhook event requests.
eventTypes[string]
A non-empty list of supported webhook event types that the endpoint will listen for.
The request body must include only the fields listed below. Atomic validates that the URL is valid, that the API secret exists for your account, and that every event type is a supported webhook event type. You can register up to 15 webhook endpoints, and a request that repeats the url and secretId of an existing endpoint is rejected.
POST/webhooks/endpoints
{
  "url": "https://your-endpoint.com/webhooks",
  "secretId": "65c6adc38a19739b40d68a60",
  "eventTypes": [
    "task-authentication-status-updated",
    "task-status-updated"
  ]
}
https://sandbox-api.atomicfi.com/webhooks/endpoints

Response

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

Get Endpoints

This endpoint returns all webhook endpoints configured for your account. It does not accept query string parameters or a request body.

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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

Response

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 where Atomic will send webhook events for the associated webhook event types. Must be a valid URL.
secretIdstring
The ID of an API secret on your account. Atomic uses this secret to create the HMAC signature for webhook event requests.
eventTypes[string]
A non-empty list of supported 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"
        ]
      }
    ]
  }
}

Update Endpoint

This endpoint is used to update a webhook endpoint which has already been registered in the Atomic system. Pass the endpoint ID as :_id in the request path and include the full replacement endpoint configuration in the request body.

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

urlstring
The URL where Atomic will send webhook events for the associated webhook event types. Must be a valid URL.
secretIdstring
The ID of an API secret on your account. Atomic uses this secret to create the HMAC signature for webhook event requests.
eventTypes[string]
A non-empty list of supported webhook event types that the endpoint will listen for.
Updates replace the endpoint configuration. Include url, secretId, and eventTypes together in the request body.
PUT/webhooks/endpoints/:_id
{
  "url": "https://your-endpoint-updated.com",
  "secretId": "65c6adc38a19739b40d68a60",
  "eventTypes": [
    "task-status-updated"
  ]
}
https://sandbox-api.atomicfi.com/webhooks/endpoints/:_id

Response

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

Delete Endpoint

This endpoint is used to delete a webhook endpoint from the Atomic system. Pass the endpoint ID as :_id in the request path. It does not accept a request body.

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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

Response

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

Example response 
{
  "success": true
}

API Secrets

API secrets can be configured on the credentials page of the Atomic Console or via API.

Create API Secret

This endpoint is used to create an API secret in the Atomic system. An account can have up to 10 API secrets; requests beyond that limit return a 400 error.

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

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

Response

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

Get API Secrets

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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

Response

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": []
      }
    ]
  }
}

Delete API Secret

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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

Response

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

This endpoint returns a 400 error with the message You must have at least one secret. if the secret is currently assigned to a webhook endpoint, if it is the only secret on your account, or if no secret with that ID exists. Before deleting a secret that is in use, update any webhook endpoints assigned to it to use a different secret.
Example response 
{
  "success": true
}

Get JWE Public Keys

This endpoint returns the public keys available for request body encryption. Keys are scoped to the environment of the credentials used. The response is empty unless request body encryption has been enabled for your account.

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/jwe-public-keys
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/secrets/jwe-public-keys

Response

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

_idstring
The id of the public key. Send this value in the x-enc-key-id header on encrypted requests.
publicKeystring
The PEM-encoded RSA public key to encrypt request bodies with.
createdAtstring
The date the key was created in ISO 8601 format.
Example response 
{
  "data": [
    {
      "_id": "66bd1c0f3a2e4f5a8c9d0e12",
      "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----",
      "createdAt": "2026-08-14T18:02:11.541Z"
    }
  ]
}