Webhooks

Webhook Reference

Webhooks enable your application to receive real-time updates via HTTP/S, allowing you to send timely notifications to end users and automate actions when events such as task status changes occur.

On this page you'll find details about the contents of our webhook event requests. For in-depth guides on how to set up, test, and secure webhooks, check out the Webhooks Guides.

Cloud Events

All Atomic webhook events conform to the CloudEvents.io protocol using the binary content mode. This table shows the CloudEvents headers along with sample values to illustrate what is sent with each event.

HeaderValue
ce-specversion1.0
ce-sourcecom.atomicfi
ce-typecom.atomicfi.[event-type]
ce-time2022-04-13T21:36:42.985Z
ce-id257426ab237ac6786a23d52

Event object

Webhook events will include a set of standard properties in the request body, as described below. All keys in the event object are required in all webhooks.

eventTypestring
This indicates what type of event is being sent. The eventType attribute is the primary field for routing webhooks as they are received by your webhook endpoint. All available options are detailed on this page.
eventTimestring
The date and time of the event creation in ISO 8601 format at UTC+0.
userobject
Object containing _id and identifier where identifier is the identifier for this user in your system (used when creating the AccessToken) and the _id is an Atomic assigned id for the user.
dataobject
The payload of the event. This object will change depending on the eventType. Corresponding attributes are detailed for each webhook below.
Sample Request Body 
{
  "eventType": "sample-event-type",
  "eventTime": "2024-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "hello": "world"
  }
}

Tasks

Any discrete operation passed through the Atomic system such as verification of income or direct deposit switch will instantiate what is referred to as a Task in our system.

When a Task resolves, you will receive the task-status-updated webhook. If the Task was successful, the status attribute will be set to completed. If there was an issue with the Task processing, status will be failed along with a reason attribute containing the reason for the failure. The failure reasons are enumerated below.

If you will be using our API to retrieve data such as W-2's or employment status, please refer to the payroll data fetched webhook for real time notification of when that data is available to be pulled via the API.

Task event object

In addition to the standard event properties, all Task events will also include the following properties, unless noted otherwise:

publicTokenstring
Public Access Token used when initializing the Transact SDK.
productenum
The product relevant to the executed Task. Options are:
    depositverifytax
taskstring
The ID of the Task; used for pulling data from the API and debugging purposes.
taskWorkflowstring
The ID of the Task Workflow. A Task Workflow is a logical container in our backend for orchestrating series of Tasks.
authenticationMethodenum
The method the user used to authenticate into the payroll system, whether via a standard authentication flow, a true-auth flow, an Atomic smart authentication flow, or one of our payroll partnership flows, called "co-auth". Enum options are:
    standard-authtrue-authsmart-authco-auth
user.connectedboolean
Indicates whether or not the user was present to view a confirmation of the Task's final outcome.
companyobject
The payroll provider or employer which this Task operated against. Returned as an object containing _id, name, and branding where this data is available.
metadataobjectOptional
The metadata object; available if provided by your system when the Task was initialized.
dataobject
Payload object containing previousStatus, status, and authenticated, along with values which are dependent on the outcome of the Task. These are documented in full detail below in the Task status updated section.
Sample webhook base 
{
  "eventType": "task-status-updated",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "publicToken": "PUBLIC_TOKEN",
  "product": "deposit",
  "user": {
    "_id": "5d8d3fecbf637ef3b11a877a",
    "identifier": "YOUR_INTERNAL_IDENTIFIER",
    "connected": true
  },
  "company": {
    "_id": "5d9a3fecbf637ef3b11ab442",
    "name": "Home Depot",
    "branding": {
      "logo": {
        "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
      }
    }
  },
  "metadata": {
    "orderId": "123"
  },
  "task": "5e30afde097146a8fc3d5cec",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "authenticated": true,
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}
JSON Schema 
{
  "type": "object",
  "title": "Atomic Webhook Event",
  "description": "Structure of a webhook event sent by Atomic Financial",
  "properties": {
    "eventType": {
      "type": "string",
      "description": "Indicates the type of the event being sent."
    },
    "eventTime": {
      "type": "string",
      "description": "The date and time of the event creation in ISO 8601 format."
    },
    "publicToken": {
      "type": "string",
      "description": "Public Access Token used when initializing the Transact SDK."
    },
    "product": {
      "type": "enum",
      "description": "The product relevant to the executed Task. Options are deposit, verify, or tax."
    },
    "user": {
      "type": "object",
      "description": "Object containing _id, identifier, and connected where identifier is your internal unique identifier and connected indicates whether or not the user was present to view a confirmation of the Task's final outcome.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "Identifier for the user created by Atomic."
        },
        "identifier": {
          "type": "string",
          "description": "Your unique identifier for the user."
        },
        "connected": {
          "type": "boolean",
          "description": "Indicates whether or not the user was present to view a confirmation of the Task's final outcome."
        }
      }
    },
    "company": {
      "type": "object",
      "description": "Object containing _id, name, and branding for the payroll company.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "Identifier for the company"
        },
        "name": {
          "type": "string",
          "description": "Company name"
        },
        "branding": {
          "type": "object",
          "description": "Metadata for the company's styling and branding.",
          "properties": {
            "logo": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "The metadata provided when the Task was initialized."
    },
    "task": {
      "type": "string",
      "description": "The ID of the Task."
    },
    "taskWorkflow": {
      "type": "string",
      "description": "The ID of the Task workflow."
    },
    "data": {
      "type": "object",
      "description": "Payload object containing reason (if a failed Task), previousStatus, status, distributionType (if applicable), distributionAmount (if applicable), and outputs.",
      "properties": {
        "reason": {
          "type": "string",
          "description": "For Tasks that failed, the reason why the Task failed. These are enumerated on in the Webhook reference page."
        },
        "previousStatus": {
          "type": "enum",
          "description": "Previous status of the Task. Options are queued or processing"
        },
        "status": {
          "type": "enum",
          "description": "Current status of the Task. Options are processing, failed, or completed."
        },
        "distributionType": {
          "type": "enum",
          "description": "For Deposit Tasks, the type of the distribution. Options are `total`, `fixed`, or `percent`. `total` indicates 100% of the paycheck is allocated for deposit, `fixed` is the specified amount, and `percent` is the specified percentage of the paycheck."
        },
        "distributionAmount": {
          "type": "number",
          "description": "For deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation. For total and percent distributionTypes, this number indicates the percentage of the paycheck allocated; total being 100 and percent indicating the percentage specified by the user."
        },
        "outputs": {
          "type": "object",
          "description": "For Verify Tasks, the data retrieved from the payroll system."
        }
      }
    }
  }
}

Task status updated

When a task-status-updated event is emitted, this indicates that the state of the Task has changed. For example, the Task has gone from processing to failed or completed. If the status is a final status, either failed or completed, no further updates will occur, although in very rare circumstances a task status patched event may be emitted.

If you need to grab payroll data once a Task has finished processing, you will need to listen for the payroll-data-fetched webhook . This webhook will notify you once the data is available to be retrieved through the Atomic API. The task-status-updated webhook may be sent out before the data has finished sync'ing to the Atomic system.

All task-status-updated webhooks will contain the properties listed in both the Event Object and Task Event Object sections. As well as the following properties, where applicable:

authenticatedboolean
Indicates whether or not the Task has successfully authenticated into the target system.
statusenum
The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum
The state which the Task was in before the current status. Options are queued and processing.
reasonenumOptional
For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
outputsobjectOptional
For Verify Tasks, this object will contain the data retrieved from the payroll system. For more information see the Task outputs section.
distributionTypeenumOptional
For Deposit Tasks, the type of the distribution. Options are total, fixed, or percent. total indicates 100% of the paycheck is allocated for deposit, fixed is the specified amount, and percent is the specified percentage of the paycheck.
distributionAmountenumOptional
For Deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation in dollars. For percent distributionTypes, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation was total, this attribute will be omitted.
Sample task-status-updated event 
{
  "eventType": "task-status-updated",
  "eventTime": "2024-12-20T18:19:58.561Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "deposit",
  "data": {
    "authenticated": true,
    "previousStatus": "processing",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}

Task authentication status updated

When eventType is task-authentication-status-updated, the authentication status of a Task was changed. Possible authenticated statuses include:

authenticatedboolean
Indicates whether or not the Task has successfully authenticated into the target system.
Sample task-authentication-status-updated event 
{
  "eventType": "task-authentication-status-updated",
  "eventTime": "2024-12-20T18:19:58.563Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "deposit",
  "data": {
    "authenticated": true
  }
}

Task status patched

When eventType is task-status-patched, the final status of a Task was updated. Cases where this may occur are rare and are generally associated with an audit or bug fix within our system. Possible statuses include:

statusenum
The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum
The state which the Task was in before the current status. Options are queued and processing.
distributionTypeenum
Optional. For Deposit Tasks, the type of the distribution. Options are total, fixed, or percent. total indicates 100% of the paycheck is allocated for deposit, fixed is the specified amount, and percent is the specified percentage of the paycheck.
distributionAmountenum
Optional. For deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation in dollars. For percent distributionTypes, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation was total, this attribute will be omitted.
authenticatedboolean
Indicates whether or not the Task has successfully authenticated into the target system.
Sample task-status-patched event 
{
  "eventType": "task-status-patched",
  "eventTime": "2024-12-20T18:19:58.566Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "deposit",
  "data": {
    "authenticated": true,
    "previousStatus": "failed",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}

Task outputs

Employment data is contained within an data.outputs object. The data delivered to you will depend on the Task's product and other considerations listed below. For your convenience, this data may include both raw and derived fields.

Verify

If you are using verify, you'll receive data as described in our Employment Data Reference. The data retrieved will depend on your data scoping configuration and what we are able to access within the payroll system.

Sample response for verify 
{
  "eventType": "task-status-updated",
  "eventTime": "2021-05-24T18:27:09.610Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "_id": "5eb62781b4b83f0008f639cc",
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "verify",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "authenticated": true,
    "outputs": {
      "income": 45000,
      "incomeType": "yearly",
      "annualIncome": 45000,
      "hourlyIncome": 21.63,
      "netHourlyRate": 18.44,
      "employeeType": "fulltime",
      "employmentStatus": "active",
      "jobTitle": "Product Manager",
      "startDate": "2017-04-19T12:00:00.000Z",
      "minimumMonthsOfEmployment": 58,
      "weeklyHours": 40,
      "payCycle": "semimonthly",
      "nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
      "currentPayPeriodStart": "2020-06-13T12:00:00.000Z",
      "currentPayPeriodEnd": "2020-06-27T12:00:00.000Z",
      "unpaidHoursInPayPeriod": 24,
      "firstName": "Jane",
      "lastName": "Appleseed",
      "dateOfBirth": "1984-04-12T19:00:00.000Z",
      "email": "jappleseed@example.org",
      "phone": "8015551111",
      "ssn": "111223333",
      "address": "123 Street St.",
      "city": "Provo",
      "state": "UT",
      "postalCode": "84606",
      "statements": [
        {
          "date": "2020-06-15T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
          "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
          "grossAmount": 1875,
          "ytdGrossAmount": 10000,
          "netAmount": 1620,
          "ytdNetAmount": 8000,
          "hours": 96,
          "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
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fad",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        },
        {
          "date": "2020-05-31T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-11T12:00:00.000Z",
          "payPeriodEndDate": "2020-05-26T12:00:00.000Z",
          "grossAmount": 1875,
          "hours": 88,
          "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]"
          }
        }
      ],
      "accounts": [
        {
          "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
        }
      ],
      "w2s": [
        {
          "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
              }
            ],
            "statutory": false,
            "retirementPlan": true,
            "thirdPartySickPay": false,
            "other": [
              {
                "description": "Housing",
                "amount": 6500
              },
              {
                "code": "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
              }
            ]
          }
        }
      ],
      "timesheets": [
        {
          "type": "unpaid",
          "duration": 420,
          "date": "2020-05-31T12:00:00.000Z"
        }
      ]
    }
  }
}

Task failures

Tasks may fail for many different reasons. If a Task fails, we will include a reason property with the event's data object. Possible values include:

account-lockout
The account is locked out, most likely the end user has had too many failed attempts.
account-setup-incomplete
The user's account in the payroll system is not fully set up and will require additional information from the user.
account-unusable
The user's bank account is unusable for the selected product or use case.
bad-credentials
Either the username or password was incorrect. This is our most common fail reason.
connection-error
A network error occurred which caused the connection between our system and the payroll system to be lost.
distribution-not-supported
The payroll system did not support the type of distribution requested. For example, the user attempted to allocate a percentage of their paycheck, but is only eligible for fixed amounts and remainder/net balance.
device-disconnected
The device used to start the task is no longer connected.
enrolled-in-paycard
The user is enrolled in a paycard program instead of direct deposit via their bank.
expired
The user's password has expired and they must create a new one.
no-data-found
No verify data was found for the user.
product-not-supported
The payroll system did not allow the action to be taken. Many payroll systems allow HR to customize what is allowed in their system. Direct Deposit may be allowed by a payroll system, but may be disallowed by a specific employer. Therefore, when an employee of that company goes to set up Direct Deposit it is rejected, resulting in this error code.
routing-number-not-supported
The account did not support the routing number entered.
session-timeout
The user's session timed out.
system-unavailable
The system was unavailable. For example, the site is undergoing maintenance or it is outside the window of scheduled availability for the site.
transaction-pending
There is a deposit allocation already in progress and additional updates cannot be made at this time. For example, if an employer has an approval process in place, they may disallow modifications until the update has been processed.
unknown-failure
We encountered an unexpected error.
user-abandon
The user was asked an MFA question, but did not answer the question.
work-status-terminated
The task could not be completed because the user's employment has been terminated.
Example Task Failure Event 
{
  "eventType": "task-status-updated",
  "eventTime": "2024-12-20T18:19:58.591Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "publicToken": "09601c31-1b54-4855-12ec-81810de154bd",
  "authenticationMethod": "true-auth",
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "product": "deposit",
  "data": {
    "authenticated": true,
    "previousStatus": "processing",
    "status": "failed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}

Task Workflow

All Tasks are run inside a Task Workflow, which allows you to run multiple Tasks in sequence. For example, if you need to run a Verify Task first to collect some data, then a Deposit Task to make an upate to the Deposit Accounts on file. Related webhooks are described below.

Task workflow finished

When eventType is task-workflow-finished, the task workflow is finished and no further tasks will be processed.

In addition to the standard event properties, the data property includes the following:

taskWorkflowstring
The ID of the Task Workflow.
statestring
The final state of the Task Workflow. Possible values are completed and failed. The Task Workflow state will equal the status of the last finished Task in the Task Workflow.
failReasonstringOptional
This value is only included if the Task Workflow fails. This value is equal to the fail reason of the last finished Task in the Task Workflow.
finishedTasks[Task]
The list of Tasks that have been processed.
Child Properties
Required Properties
_idstring
The identifier of the Task.
productstring
The product or operation of the Task.
statusstring
The status of the Task. Possible values are completed or failed
Optional Properties
failReasonstringOptional
The fail reason for the Task. This value is only included if the Task fails.
queuedTasks[Task]
The list of Tasks that have not been processed.
Child Properties
Required Properties
productstring
The product or operation of the Task.
Sample task-workflow-finished event 
{
  "eventType": "task-workflow-finished",
  "eventTime": "2024-12-20T18:19:58.596Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "data": {
    "taskWorkflow": "65d8e67c87dcfe39fa887be8",
    "state": "failed",
    "failReason": "bad-credentials",
    "finishedTasks": [
      {
        "_id": "65fdb065c555b36a6b290e8b",
        "product": "verify",
        "status": "failed",
        "failReason": "bad-credentials"
      }
    ],
    "queuedTasks": [
      {
        "product": "deposit"
      }
    ]
  }
}

Payroll Data

Payroll data refers to data Atomic has retrieved from a payroll system, such as employment status, job title, or details about the employer. This data can take a bit of time to sync and be ready for retrieval. This webhook serves to notify you once all the data has been fetched and is available to be retrieved via API.

The payroll data webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Payroll data fetched

When eventType is payroll-data-fetched, a user's Payroll data has been updated in Atomic's system. and is ready for retrieval via API.

In addition to the standard event properties, the data property includes the following:

payrollDataEventswebhook
this is a list of webhook events that have been sent.
Sample payroll-data-fetched event 
{
  "eventType": "payroll-data-fetched",
  "eventTime": "2024-12-20T18:19:58.599Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "metadata": {
    "orderId": "123"
  },
  "data": {
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d",
    "payrollDataEvents": [
      "deposit-accounts-synced",
      "deposit-accounts-updated",
      "statements-synced",
      "income-synced",
      "income-updated",
      "identity-synced",
      "identity-updated",
      "employment-synced",
      "employment-updated",
      "taxes-synced",
      "timesheets-synced"
    ]
  }
}

Deposit switch

Deposit switch removed

When eventType is deposit-switch-removed, a deposit allocation that was previously completed through your integration with Atomic has been removed from the user's account in the payroll system.

This webhook is only available when Continuous Access is enabled.

In addition to the standard event properties, the data property includes the following:

removedDepositAccountDeposit Account
A snapshot of the deposit account that was previously added through Atomic, but has been removed from the payroll system.
depositAccounts[Deposit Account]
An array of deposit accounts that represent the current state of the user's deposit accounts in the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample deposit-switch-removed event 
{
  "eventType": "deposit-switch-removed",
  "eventTime": "2024-12-20T18:19:58.603Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "removedDepositAccount": {
      "routingNumber": "456456456",
      "accountNumber": "XXXX1111",
      "type": "savings",
      "bankName": "Molecular Bank",
      "distributionType": "percent",
      "distributionAmount": 20
    },
    "depositAccounts": [
      {
        "routingNumber": "123123123",
        "accountNumber": "1122330000",
        "type": "checking",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 100
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Deposit Accounts

A Deposit Account refers to a direct deposit allocation in a payroll system. There can be zero or more Deposit Accounts configured in a payroll system for a single user. More details can be found in the Deposit Account section of the Employment Data page.

The Deposit Accounts webhooks are only available if Continuous Access is enabled and the Deposit Accounts fields have been selected in the Features section of the Settings page in Console.

Deposit accounts synced

When eventType is deposit-accounts-synced, a user's Deposit Accounts have finished their initial sync. This occurs when the Deposit allocation has been set for the first time and the Deposit Accounts in the payroll system have been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

depositAccounts[Deposit Account]
An array of Deposit Account objects, representing the most recent state.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample deposit-accounts-synced event 
{
  "eventType": "deposit-accounts-synced",
  "eventTime": "2024-12-20T18:19:58.614Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Deposit accounts added

When eventType is deposit-accounts-added, one or more Deposit Accounts have been added to a user's account.

In addition to the standard event properties, the data property includes the following:

depositAccounts[Deposit Account]
An array of Deposit Account objects, representing the most recent state.
changes[Deposit Account]
An array of Deposit Accounts that were added.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample deposit-accounts-added event 
{
  "eventType": "deposit-accounts-added",
  "eventTime": "2024-12-20T18:19:58.619Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
      }
    ],
    "changes": [
      {
        "routingNumber": "123123123",
        "accountNumber": "1122330000",
        "type": "checking",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 80
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Deposit accounts updated

When eventType is deposit-accounts-updated, one or more Deposit Accounts have been updated in the payroll system. Atomic runs a weekly job to check the state of the Deposit Accounts in the payroll system; if there is a difference from the last sync, this webhook is emitted. This requires Continuous Access.

In addition to the standard event properties, the data property includes the following:

depositAccounts[Deposit Account]
An array of Deposit Account objects, representing the most recent state.
changes[Deposit Account]
An array of Deposit Accounts that were updated.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample deposit-accounts-updated event 
{
  "eventType": "deposit-accounts-updated",
  "eventTime": "2024-12-20T18:19:58.623Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
      }
    ],
    "changes": [
      {
        "routingNumber": "123123123",
        "accountNumber": "1122330000",
        "type": "checking",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 80
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Deposit accounts removed

When eventType is deposit-accounts-removed, one or more Deposit Accounts have been removed from the payroll system. Atomic runs a weekly job to check the state of the Deposit Accounts in the payroll system; if a Deposit Account has been removed since the last sync, this webhook is emitted. This requires Continuous Access.

In addition to the standard event properties, the data property includes the following:

depositAccounts[Deposit Account]
An array of Deposit Account objects, representing the most recent state.
changes[Deposit Account]
An array of Deposit Accounts that were removed.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample deposit-accounts-removed event 
{
  "eventType": "deposit-accounts-removed",
  "eventTime": "2024-12-20T18:19:58.627Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
      }
    ],
    "changes": [
      {
        "routingNumber": "456456456",
        "accountNumber": "XXXX1111",
        "type": "savings",
        "bankName": "Molecular Bank",
        "distributionType": "percent",
        "distributionAmount": 20
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Linked Account

A Linked Account is an account in which the end user has given Atomic permission to maintain a persistent connection with their payroll provider. Once the user has successfully authenticated with the payroll provider, a Linked Account is created in the Atomic system.

We are then able to run a weekly job which can access data or detect changes in the payroll system. This is how we establish Continuous Access to the payroll provider on behalf of the user.

Linked account connected

When eventType is linked-account-connected, the user has successfully authenticated with the payroll provider and the Linked Account has been created in the Atomic system.

In addition to the standard event properties, the data property includes the following:

linkedAccountLinked Account
The data for the Linked Account associated with the user's persistent connection. The _id is needed for your system to make calls to Atomic and use the connection again.
Sample linked-account-connected event 
{
  "eventType": "linked-account-connected",
  "eventTime": "2024-12-20T18:19:58.632Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "data": {
    "linkedAccount": {
      "_id": "5f7212103a40e91f95ba376d",
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c5",
        "name": "Mocky",
        "branding": {
          "logo": {
            "url": "https://cdn.atomicfi.com/mocky-logo.svg"
          }
        }
      }
    }
  }
}

Linked account disconnected

When eventType is linked-account-disconnected, a user's Linked Account has been disconnected. Typically this occurs when a password expires or another change in the payroll system has severed the connection. This requires the user to go through Transact again and re-establish the connection.

In addition to the standard event properties, the data property includes the following:

linkedAccountLinked Account
The data for the Linked Account associated with the user's persistent connection. The _id is needed for your system to make calls to Atomic and use the connection again.
Sample linked-account-disconnected event 
{
  "eventType": "linked-account-disconnected",
  "eventTime": "2024-12-20T18:19:58.634Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "data": {
    "linkedAccount": {
      "_id": "5f7212103a40e91f95ba376d",
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c5",
        "name": "Mocky",
        "branding": {
          "logo": {
            "url": "https://cdn.atomicfi.com/mocky-logo.svg"
          }
        }
      }
    }
  }
}

Employment

Employment refers to the employment data as retrieved from a payroll system, such as employment status, job title, or details about the employer.

The Employment webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Employment synced

When eventType is employment-synced, a user's Employment data has finished its initial sync. This occurs when the connection is first established and the Employment data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

employment{Employment}
An Employment object, representing the most recent state of the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample employment-synced event 
{
  "eventType": "employment-synced",
  "eventTime": "2024-12-20T18:19:58.638Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Employment updated

When eventType is employment-updated, a user's Employment data has been modified in the payroll system and the changes have been stored in Atomic. This webhook contains both the current state as well as indicates the changed data fields.

In addition to the standard event properties, the data property includes the following:

employment{Employment}
An Employment object, representing the most recent state of the payroll system.
changesobject
The changes that took place within the user's data, previous representing the former value, and current being the latest value. If new data is detected, then the value of previous could be null.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample employment-updated event 
{
  "eventType": "employment-updated",
  "eventTime": "2024-12-20T18:19:58.643Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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"
        }
      }
    },
    "changes": {
      "jobTitle": {
        "previous": "Product Intern",
        "current": "Product Manager"
      }
    },
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Identity

Identity refers to the identity data as retrieved from a payroll system, such as first and last name, date of birth, and email address.

The Identity webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Identity synced

When eventType is identity-synced, a user's Identity has finished its initial sync. This occurs when the connection is first established and the Identity data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

identity{Identity}
An Identity object, representing the most recent state of the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample identity-synced event 
{
  "eventType": "identity-synced",
  "eventTime": "2024-12-20T18:19:58.653Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Identity updated

When eventType is identity-updated, a user's Identity has been modified in the payroll system and the changes have been stored in Atomic. This webhook contains both the current state as well as indicates the changed data fields.

In addition to the standard event properties, the data property includes the following:

identity{Identity}
An Identity object, representing the most recent state of the payroll system.
changesobject
The changes that took place within the user's data, previous representing the former value, and current being the latest value. If new data is detected, then the value of previous could be null.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample identity-updated event 
{
  "eventType": "identity-updated",
  "eventTime": "2024-12-20T18:19:58.657Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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"
    },
    "changes": {
      "email": {
        "previous": "jillappleseed@example.com",
        "current": "janeappleseed@example.com"
      }
    },
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Income

Income refers to income information as retrieved from a payroll system, such as an income amount, pay cycle, information about the pay periods, etc.

The Income webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Income synced

When eventType is income-synced, a user's Income has finished its initial sync. This occurs when the connection is first established and the Income data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

income{Income}
An Income object, representing the most recent state of the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample income-synced event 
{
  "eventType": "income-synced",
  "eventTime": "2024-12-20T18:19:58.662Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Income updated

When eventType is income-updated, Income data for the specified user has been modified in the payroll system and the changes have been stored in Atomic. This webhook contains both the current state as well as indicates the changed data fields.

In addition to the standard event properties, the data property includes the following:

income{Income}
An Income object, representing the most recent state of the payroll system.
changesobject
The changes that took place within the user's data, previous representing the former value, and current being the latest value. If new data is detected, then the value of previous could be null.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample income-updated event 
{
  "eventType": "income-updated",
  "eventTime": "2024-12-20T18:19:58.665Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "company": {
    "_id": "5d77f9e1070856f3828945c5",
    "name": "Mocky",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/mocky-logo.svg"
      }
    }
  },
  "publicToken": "PUBLIC_TOKEN",
  "product": "deposit",
  "metadata": {
    "orderId": "123"
  },
  "task": "5e30afde097146a8fc3d5cec",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}

Statements

A Statement refers to payroll information, such as when the pay period starts and ends, amounts for the paycheck, deductions, etc.

The Statements webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Statements synced

When eventType is statements-synced, a user's Statements have finished their initial sync. This occurs when the connection is first established and the Statements data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

statements[Statement]
An array of Statement objects containing payroll data for the user.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample statements-synced event 
{
  "eventType": "statements-synced",
  "eventTime": "2024-12-20T18:19:58.669Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
          }
        ],
        "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Statements added

When eventType is statements-added, one or more Statements have been added to a user's account in the payroll system. For example, when payroll is processed.

In addition to the standard event properties, the data property includes the following:

statements[Statement]
An array of Statement objects containing newly added payroll data for the user.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample statements-added event 
{
  "eventType": "statements-added",
  "eventTime": "2024-12-20T18:19:58.676Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
          }
        ],
        "paystub": {
          "_id": "60abeff50836730008616fad",
          "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
        }
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Timesheets

Timesheets refer to timesheet data as retrieved from a payroll system, such as whether the entry has been paid, clocked-in and/or clocked-out times, and the duration.

The Timesheet webhooks require that Verify and Continuous Access are enabled. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Timesheets synced

When eventType is timesheets-synced, a user's Timesheets have finished their initial sync. This occurs when the connection is first established and the Timesheet data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

timesheets[Timesheet]
An array of Timesheet objects.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample timesheets-synced event 
{
  "eventType": "timesheets-synced",
  "eventTime": "2024-12-20T18:19:58.687Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Timesheets added

When eventType is timesheets-added, one or more Timesheets have been added to a user's account in the payroll system.

In addition to the standard event properties, the data property includes the following:

timesheets[Timesheet]
An array of newly added Timesheet objects.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample timesheets-added event 
{
  "eventType": "timesheets-added",
  "eventTime": "2024-12-20T18:19:58.691Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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"
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Taxes

Taxes refers to Tax data as retrieved from a payroll system, such as an wages, parsed W-2 details, and other withholding data.

The Tax webhooks require our Tax use case be part of your contract. You will need to select the data fields you are interested in for your use case on the Features section of the Settings page in Console.

Taxes synced

When eventType is taxes-synced, a user's Tax data has finished its initial sync. This occurs when the connection is first established and the Tax data from the payroll system has been stored in the Atomic system.

In addition to the standard event properties, the data property includes the following:

taxes[Taxes]
A combined array of Tax data objects, representing the most recent state of the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample taxes-synced event 
{
  "eventType": "taxes-synced",
  "eventTime": "2024-12-20T18:19:58.695Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Taxes added

When eventType is taxes-added, one or more tax data objects have been added to a user's account.

In addition to the standard event properties, the data property includes the following:

taxes[Taxes]
A combined array of Tax data objects, representing the most recent state of the payroll system.
companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.

Optional attributes

linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample taxes-added event 
{
  "eventType": "taxes-added",
  "eventTime": "2024-12-20T18:19:58.702Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "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
            }
          ]
        }
      }
    ],
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}

Conversion

We've built a webhook for letting you know when we've identified a user as a good candidate for re-engagement. When you receive this webhook, request that the user re-initialize the Transact flow with the conversionToken passed in through the Transact Parameters.

Conversion opportunity

When eventType is conversion-opportunity, the user should be notified to re-attempt completing the previously attempted Task in Transact. This event is triggered when there is an opportunity to convert a user. The conversionToken should be used as a Transact SDK parameter to pull in necessary context for re-initialization of the user's task.

In addition to the standard event properties, the data property includes the following:

conversionReasonstring
The category of the opportunity to convert a previously unsuccessful attempt. Currently, the only supported conversionReason is retry-task.
conversionTokenstring
The conversion token to be used when re-initializing Transact.
Sample conversion-opportunity event 
{
  "eventType": "conversion-opportunity",
  "eventTime": "2024-12-20T18:19:58.713Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "data": {
    "conversionReason": "retry-task",
    "conversionToken": "eyJ0eXBlIjoicmV0cnktdGFzayIsInRyYW5zYWN0Q29uZmlnIjp7InRhc2tJZFRvQ29udmVydCI6IjYzMzM2MTRlNzBkNzcwZjFhODE2MTdkMyIsInRhc2tzIjpbeyJwcm9kdWN0IjoiZGVwb3NpdCJ9XX19"
  }
}

Continuous Access

Continuous Access Tasks are Tasks which process without the need for the user to be present. Using our Linked Account feature, these Tasks are used to keep the user's payroll data up to date in the Atomic system.

Continuous access task failed

When eventType is continuous-access-task-failed, a Continuous Access Task has failed. In cases where the failure was due to stale credentials, the linked-account-disconnected event will also be triggered. If payroll data monitoring is enabled, then the next Continuous Access Task will run on the next sync cycle.

In addition to the standard event properties, the data property includes the following:

companyobject
The employer to which the payroll is linked.
connectorobject
The payroll system to which the data is linked.
taskstring
The ID of the Task associated with this job in the Atomic system.
taskWorkflowstring
The ID of the Task Workflow of the Tasks which were run.
reasonenum
The reason for the failure. These are enumerated in the Task Failures section.
linkedAccountstring
The unique identifier for the Linked Account associated with this user.
Sample continuous-access-task-failed event 
{
  "eventType": "continuous-access-task-failed",
  "eventTime": "2024-12-20T18:19:58.716Z",
  "user": {
    "_id": "602c4d53dc89c40008db562a",
    "identifier": "YOUR_UNIQUE_IDENTIFIER",
    "connected": true
  },
  "task": "602414d84f9a1980cf5eafcc",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "company": {
      "_id": "5d77f9e1070856f3828945c5",
      "name": "Mocky",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/mocky-logo.svg"
        }
      }
    },
    "connector": {
      "_id": "5d77f95207085632a58945c3",
      "name": "ADP",
      "branding": {
        "logo": {
          "_id": "5eb62781b4b83f0008f6343c",
          "url": "https://cdn.atomicfi.com/adp-logo.svg"
        }
      }
    },
    "reason": "unknown-error",
    "linkedAccount": "5f7212103a40e91f95ba376d"
  }
}