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:

Header	Description
`x-api-key`	API Key for your Atomic account
`x-api-secret`	API Secret for your Atomic account

Access Token

These headers are included in requests that are made 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.

Header	Description
`x-public-token`	Public token generated during access token creation.

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Code	Title	Description
200	OK	The request was successful.
400	Bad Request	The request was unacceptable.
401	Unauthorized	Missing or invalid credentials.
404	Not Found	The resource does not exist.
422	Validation error	A validation error occurred.
50X	Internal Server Error	An error occurred with our API.

Access Token

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

Create Access Token

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

identifierstring: A unique identifier from your system that will be used to reference this user. This could be a primary key used in your system or another unique identifier. Creating multiple access tokens with the same identifier will tie those tokens to the same user in Atomic's system.

Optional Properties

tokenLifetimeinteger

The number of seconds until the token expires.

Default value: 86,400 (24 hours)

Products may have additional required properties. Refer to the implementation pages for additional details.

POST/access-token

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

Product Specific Properties

The identifier property is required for generating all AccessTokens, but each Atomic product may require some additional context in order to correctly set up the flow in our backend. Please refer to the implementation pages for each Product to get specific details regarding AccessToken creation.

Deposit

Verify

Response

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

Example response

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

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.

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.

Optional Properties

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

Response

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

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

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.

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

Optional Properties

_idstring

The id of the task workflow.

userobject

The user that ran the task.

Child Properties

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

Required Properties

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

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

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

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

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.

GET/deposit-accounts/:identifier

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

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

GET/employment/:identifier

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

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

GET/identity/:identifier

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

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

GET/income/:identifier

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

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

limitstring

The number of statement records to return provided as a query string parameter.

GET/statements/:identifier

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]"
          }
        },
        {
          "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 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.

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

GET/timesheets/:identifier

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

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

GET/taxes/:identifier

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

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

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.

Optional Properties

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

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

Optional Properties

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

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.

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

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

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.

GET/user/:identifier/tasks

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.

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

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

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
}

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.

Create Endpoint

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.

Required Properties

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

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

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

Update Endpoint

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.

Required Properties

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

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.

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

Response

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

Example response

{
  "success": true
}

API Secrets

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

Create API Secret

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.

Required Properties

namestring: The name of the secret.

POST/secrets

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

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

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

Response

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
}