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 by the end user, e.g. searching for their employer.

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

Errors

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

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

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, earn, 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, earn, 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, typically an SVG if available.
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 or a direct deposit switch, will instantiate what is referred to as a Task in our system. A Task consists of an authentication step where Atomic logs into the payroll provider and the operation step where we either read data or write a direct deposit allocation.

Get Task Status

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

Authentication is handled via the API Key and Secret method. 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 invited, queued, processing, paused, captcha, mfa, error, failed, retry, completed, or manual.
failReasonstringOptional: The failure reason associated with a failed task. Will consist of one of the failure values.

Example response

{
  "createdAt": "2023-01-03T16:40:48.009Z",
  "status": "failed",
  "failReason": "no-data-found"
}

Generate File URL

Generate a URL in order to download a user file (ex: paystubs PDFs). Each URL is valid for 1 hour.

Authentication is handled via the API Key and Secret method. 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.

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.

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.

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.

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.

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.

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.

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

productstringDeprecated: One of deposit, verify, earn, 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.
operationstring: Specifies the operation with which to initialize Transact. One of deposit, verify, earn, or tax.

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.

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
}