API

UserLink API Reference

Atomic's API is built around RESTful principles, using JSON encoded request and response bodies.

To get going quickly, we recommend using the API collaboration tool Postman. You can use the button below to import our collection of endpoints. Be sure to set your apiUrl, apiKey, and apiSecret  environment variables.

Authentication

Atomic uses a combination of API keys and access tokens to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

API Key and Secret

You can retrieve and manage your API key and secrets on the credentials page on the Atomic Console. Include these headers in requests that are secured with your API Key and Secret:

HeaderDescription
x-api-keyAPI Key for your Atomic account
x-api-secretAPI 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.

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

CodeTitleDescription
200OKThe request was successful.
400Bad RequestThe request was unacceptable.
401UnauthorizedMissing or invalid credentials.
404Not FoundThe resource does not exist.
422Validation errorA validation error occurred.
50XInternal Server ErrorAn error occurred with our API.

Access Token

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

Create Access Token

Authentication is handled via the API Key and Secret method.

Required Properties

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.

DepositVerifyPaylink

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

Linked Account

A LinkedAccount is a persistent connection that has been authenticated by an end-user. Once established, it can be used to perform read and write operations.

NOTE: Linked Accounts must be enabled on your account in order for them to be used.

List Linked Accounts

If enabled on your account, can be used to list accounts linked to a particular user.

Authentication is handled via the API Key and Secret method.

Required Properties

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

This is a new endpoint that replaces the Use a Linked Account endpoint for Tasks.

To generate a Task Workflow using a Linked Account, a Task Workflow request is created that contains an array of the tasks you wish to execute and the _id of the LinkedAccount. A Task Workflow is then created if the request is successful.

Authentication is handled via the API Key and Secret method.

Required Properties

tasks[TaskConfiguration]
Defines configuration for the tasks you wish to execute as part of the task workflow.
Child Properties
Required Properties
productstringDeprecated
One of deposit, verify, paylink, 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, paylink, 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 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 user's company.
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"
      }
    }
  }
}

Use a Linked AccountDeprecated

This endpoint has been deprecated in favor of the new Use a Linked Account endpoint for Task Workflows.

To generate a Task using a Linked Account, a Task request is created that contains the product and the _id of the LinkedAccount. A Task is then created if the request is successful.

Authentication is handled via the API Key and Secret method.

Required Properties

productstring
One of deposit, verify, paylink, earn, or tax.
linkedAccountstring
The _id of a LinkedAccount object.

Optional Properties

distributionobject
The distribution of the deposit as defined in the SDK Parameters.
metadataobject
Optionally pass metadata that will be returned to you in webhook events.
POST/task/create
https://sandbox-api.atomicfi.com/task/create

Response

Successfully creating a Task will return a payload with a data object containing metadata about the created task, taskWorkflow, and the associated company. The Atomic Console can be used to track task progress. If you plan on implementing webhooks, we recommend saving the task _id for reference.

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 user's company.
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"
      }
    }
  }
}

Company

Company Search

Searches for a Company using a text query. Searches can also be narrowed by passing in additional properties detailed below. The primary use case of this endpoint is for an autocomplete search component.

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

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

Get Task Status

An endpoint to return the status of a Task. Submit the corresponding taskId and receive the status of that Task.

Authentication is handled via the API Key and Secret method.

Required Properties

taskIdstring
The id of the Task. The taskIdproperty is sent in several webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.
GET/task/:taskId/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.

Required Properties

taskIdstring
The id of the task.
fileIdstring
The id of the file.
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 is a new endpoint that 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.

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 with a string value. We will make this determination based on a variety of proprietary considerations such as traffic volumes and calculations with other similar connector types.

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 all direct deposit accounts on file for the specified user.

Authentication is handled via the API Key and Secret method.

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

Return all employment data for the specified user.

Authentication is handled via the API Key and Secret method.

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

Returns all identity data for the specified user.

Authentication is handled via the API Key and Secret method.

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

Returns income data for the specified user.

Authentication is handled via the API Key and Secret method.

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

Returns all statements for the specified user.

Authentication is handled via the API Key and Secret method.

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[]
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,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200,
              "ytdAmount": 2000
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50,
              "ytdAmount": 500
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5,
              "ytdAmount": 50
            }
          ],
          "earnings": [
            {
              "category": "benefit",
              "rawLabel": "Social Security (Disability)",
              "amount": 1000
            },
            {
              "category": "bonus",
              "rawLabel": "Quarterly Bonus",
              "amount": 2000,
              "ytdAmount": 6000
            },
            {
              "category": "overtime",
              "rawLabel": "Overtime Pay",
              "amount": 100,
              "ytdAmount": 1000,
              "hours": 10,
              "rate": 15
            },
            {
              "category": "reimbursement",
              "rawLabel": "Gas Card",
              "amount": 25.47,
              "ytdAmount": 85.74
            }
          ],
          "netAmountAdjustments": [
            {
              "label": "Mileage Reimbursement",
              "amount": 25
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fad",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        },
        {
          "date": "2020-06-30T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
          "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
          "grossAmount": 1000,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fae",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        }
      ],
      "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

Returns all timesheets for the specified user.

Authentication is handled via the API Key and Secret method.

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

Returns all tax data for the specified user.

Authentication is handled via the API Key and Secret method.

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[]
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",
              "city": "Preston",
              "state": "VA",
              "postalCode": "20191"
            },
            "controlNumber": "012547 WY/OA7",
            "employeeName": {
              "first": "Kris",
              "last": "Public"
            },
            "employeeAddress": {
              "line1": "1 Main St",
              "city": "Melrose",
              "state": "NY",
              "postalCode": "12121"
            },
            "wages": 44416.74,
            "federalTaxWithheld": 6907.16,
            "socialSecurityWages": 47162.92,
            "socialSecurityTaxWithheld": 2924.1,
            "medicareWages": 47162.92,
            "medicareTaxWithheld": 683.86,
            "socialSecurityTips": 134.25,
            "allocatedTips": 149.75,
            "dependentCareBenefit": 543.25,
            "nonQualifiedPlan": 354.23,
            "codes": [
              {
                "code": "C",
                "amount": 301.5
              },
              {
                "code": "D",
                "amount": 2746.18
              },
              {
                "code": "DD",
                "amount": 4781.88
              }
            ],
            "other": [
              {
                "description": "Housing",
                "amount": 6500
              },
              {
                "description": "Union Dues",
                "amount": 1500
              }
            ],
            "stateTaxWithholding": [
              {
                "stateTaxWithheld": 1726.78,
                "state": "OH",
                "stateTaxId": "OH 036-133505158F-01",
                "stateIncome": 44416.74
              }
            ],
            "localTaxWithholding": [
              {
                "localTaxWithheld": 427.62,
                "localityName": "Kirtland",
                "state": "OH",
                "localIncome": 44416.74
              }
            ]
          }
        },
        {
          "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"
    }
  ]
}