
EmployerLink Webhook Reference
Webhooks are a useful way to receive automated updates via HTTP and send timely notifications to your user as a transaction progresses. 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.
Header | Value |
---|---|
ce-specversion | 1.0 |
ce-source | com.atomicfi |
ce-type | com.atomicfi.[event-type] |
ce-time | 2022-04-13T21:36:42.985Z |
ce-id | 257426ab237ac6786a23d52 |
Event object
Webhook events will include a set of standard properties in the request body, as described below.
eventType
string- 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. eventTime
string- The date and time of the event creation in ISO 8601 format at UTC+0.
user
object- Object containing
_id
andidentifier
whereidentifier
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. data
object- The payload of the event. This object will change depending on the
eventType
. Corresponding attributes are detailed for each webhook below.
{
"eventType": "sample-event-type",
"eventTime": "2020-01-28T22:04:18.778Z",
"user": {
"_id": "5c17c632e1d8ca3b08b2586f",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"hello": "world"
}
}
Tasks
Each discrete payroll operation, such as a verification of income or a direct deposit switch, will instantiate what is referred to as a Task in our system.
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.
Task event object
In addition to the standard event properties, all Task events will also include the following:
publicToken
string- Public Access Token used when initializing the Transact SDK.
product
enum- The product relevant to the executed task. Options are:
enroll
user.connected
boolean- Indicates whether or not the user was present to view a confirmation of the task's final outcome.
company
object- The payroll provider or employer which this Task interacts with. Returned as an object containing
_id
,name
, andbranding
. metadata
object- The
metadata
provided by your system when the task was initialized. task
string- The ID of the Task; useful for debugging purposes.
taskWorkflow
string- The ID of the Task Workflow; useful for debugging purposes. A Task Workflow is a logical container in our backend for orchestrating Tasks.
data
object- Payload object containing a
reason
attribute if a Task failed (see Task failures below),previousStatus
,status
,distributionType
(if applicable),distributionAmount
(if applicable), and outputs.
{
"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",
"distributionType": "fixed",
"distributionAmount": 25
}
}
{
"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, earn, 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 finished
or completed
. If the status is a final status, either finished
or completed
, no further updates will occur, though 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.
status
enum- The current state of the Task. Options are
processing
,failed
andcompleted
. Failed and completed are final states indicating either a successful or unsuccessful Task. previousStatus
enum- The state which the Task was in before the current status. Options are
queued
andprocessing
. reason
enum- Optional. For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
outputs
object- Optional. For Verify Tasks, this object will contain the data retrieved from the payroll system. For more information see the Task outputs section.
distributionType
enum- Optional. For Deposit Tasks, the type of the distribution. Options are
total
,fixed
, orpercent
.total
indicates 100% of the paycheck is allocated for deposit,fixed
is the specified amount, andpercent
is the specified percentage of the paycheck. distributionAmount
enum- Optional. For deposit Tasks, the amount of the distribution. When the
distributionType
isfixed
, this indicates the specific amount of the payroll allocation in dollars. Forpercent
distributionTypes
, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation wastotal
, this attribute will be omitted.
{
"eventType": "task-status-updated",
"eventTime": "2023-09-26T21:35:44.784Z",
"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": "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:
authenticated
boolean- Indicates whether or not the Task has successfully authenticated against the payroll system.
{
"eventType": "task-authentication-status-updated",
"eventTime": "2023-09-26T21:35:44.793Z",
"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": "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:
status
enum- The current state of the Task. Options are
processing
,failed
andcompleted
. Failed and completed are final states indicating either a successful or unsuccessful Task. previousStatus
enum- The state which the Task was in before the current status. Options are
queued
andprocessing
. distributionType
enum- Optional. For Deposit Tasks, the type of the distribution. Options are
total
,fixed
, orpercent
.total
indicates 100% of the paycheck is allocated for deposit,fixed
is the specified amount, andpercent
is the specified percentage of the paycheck. distributionAmount
enum- 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. Forpercent
distributionTypes
, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation wastotal
, this attribute will be omitted.
{
"eventType": "task-status-patched",
"eventTime": "2023-09-26T21:35:44.794Z",
"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": "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.
{
"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.
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.
{
"eventType": "task-status-updated",
"eventTime": "2023-09-26T21:35:44.817Z",
"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": "deposit",
"data": {
"authenticated": false,
"previousStatus": "processing",
"status": "failed",
"distributionType": "total",
"reason": "system-unavailable"
}
}
Employer
Once an Admin has gone through the Transact flow and provided access to their payroll system, we begin to pull data into our database. This webhook serves to notify your system that this sync process has completed and the data for this employer is available for retrieval.
Employer fetched
When eventType
is employer-fetched
, an employer's data has been fetched and is ready to be retrieved.
In addition to the standard event properties, the data
property includes the following:
uri
string- The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employer endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
{
"eventType": "employer-fetched",
"eventTime": "2023-09-26T21:35:44.821Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/5d77f95207085632a58945c3",
"employerId": "642c9aa6f8fc90e0dbb4c92f"
}
}
Employee
Once an Admin has gone through the Transact flow and provided access to their payroll system, we begin to pull data into our database. This webhook serves to notify your system that this sync process has completed and the employee data for this employer is available for retrieval.
Employees fetched
When eventType
is employees-fetched
, one or more employee's data has been fetched and is ready to be retrieved.
In addition to the standard event properties, the data
property includes the following:
uri
string- The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employee endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
{
"eventType": "employees-fetched",
"eventTime": "2023-09-26T21:35:44.826Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/5d77f95207085632a58945c3/employees",
"employerId": "642c9aa6f8fc90e0dbb4c92f"
}
}
Employee added
When eventType
is employee-added
, an employee has been added to the payroll system.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the data for the added employee. This URI be a constructed HTTPS request against our employees endpoint.
employerId
string- The unique identifier for the employer in the Atomic system.
employeeId
string- The unique identifier for the employee in the Atomic system. This identifier will be used in the uri to retrieve the added employee data.
{
"eventType": "employee-added",
"eventTime": "2023-09-26T21:35:44.829Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employees/5d77f95207085632a58945c3",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"employeeId": "5d77f95207085632a58945c3"
}
}
Employee updated
When eventType
is employee-updated
, an employee's identity, income, or employment data has been updated.
In addition to the standard event properties, the data
property includes the following:
uri
string- The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employee endpoints.
employerId
string- The unique identifier for the employer in the Atomic system.
employeeId
string- The unique identifier for the employee in the Atomic system. This identifier will be used in the uri to retrieve the updated employee data.
changes
object- An object with keys of the fields that have been changed. Each key shows the previous and current value of the field that has changed.
{
"eventType": "employee-updated",
"eventTime": "2023-09-26T21:35:44.831Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employees/5d77f95207085632a58945c3",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"employeeId": "5d77f95207085632a58945c3",
"changes": {
"employmentStatus": {
"previous": "active",
"current": "terminated"
},
"terminationDate": {
"previous": null,
"current": "2023-03-01T00:00:00.000Z"
}
}
}
}
Employee Deduction Requests
When we receive a deduction request for an employee, we will attempt to write that deduction to the payroll system and track the status of the request via what we call an Employee Deduction Request. This webhook serves to notify your system of the state of that request against the payroll system.
Employee deduction requests
When eventType
is employee-deductions-request
, the deduction process has resolved and the resulting state will be transmitted via this webhook or you can retrieve the details from the Employee Deduction Requests endpoint.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the employee deduction request data. This URI will be a constructed HTTPS request against our Employee Deduction Requests endpoint.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the URI to retrieve the updated employer data.
employeeDeductionRequest
[employeeDeductionRequest]- An array of employee deduction requests resulting from the processed deduction task. Each employee deduction request will contain the
state
,trackingId
if used,task
,employee
,employeeDeduction
andemployerDeductionType
. Each of these fields can be used to filter the Employee Deduction Requests endpoint.
{
"eventType": "employee-deductions-request",
"eventTime": "2023-09-26T21:35:44.835Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/642c9aa6f8fc90e0dbb4c92f/employee-deduction-requests?taskId=6501f8249f904b6a29e6cc1c",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"employeeDeductionRequests": [
{
"state": "applied",
"trackingId": "0b6385c9-f1e4-4b3c-8881-3c8b124609e1",
"employee": "642df289af36e2ef5e1679dc",
"employerDeductionType": "64c3d74f9326b2e09de96089",
"task": "6501f8249f904b6a29e6cc1c",
"employeeDeduction": {
"_id": "6508ca7ebc39bd78ca1fb87d",
"label": "retirement",
"calculation": "fixed",
"category": "401k",
"categoryType": "post-tax",
"amount": 4,
"startDate": "2023-09-13T17:57:56.230Z"
}
},
{
"state": "failed",
"trackingId": "9681a900-d7a1-4fd2-a5da-0f1f3335dfcf",
"employee": "642df289af36e2ef5e1679d9",
"employerDeductionType": "64c3d74f9326b2e09de96089",
"task": "6501f8249f904b6a29e6cc1c",
"employeeDeduction": {
"_id": "6508ca8b882f46254b6934b7",
"label": "retirement",
"calculation": "percent",
"category": "other",
"categoryType": "pre-tax",
"amount": 20,
"startDate": "2023-09-13T17:57:56.230Z"
}
}
]
}
}
Employer Document
Once an Admin has gone through the Transact flow and provided access to their payroll system, we begin to pull data into our database. This webhook serves to notify your system that this sync process has completed and the documents for this employer are available for retrieval.
Employer documents fetched
When eventType
is employer-documents-fetched
, an employer's documents have been fetched and are ready to be retrieved.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our employer document endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
{
"eventType": "employer-documents-fetched",
"eventTime": "2023-09-26T21:35:44.838Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/5d77f95207085632a58945c3/employer-documents",
"employerId": "642c9aa6f8fc90e0dbb4c92f"
}
}
Payroll Runs
Once an Admin has gone through the Transact flow and provided access to their payroll system, we begin to pull data about payroll runs into our database. These webhooks serve to update your system about the status of this process and notify you when payroll runs for this employer are available for retrieval.
Payroll runs fetched
When eventType
is payroll-runs-fetched
, the initial pull of the employer's payroll runs have been fetched from the payroll system and are ready to be retrieved.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
{
"eventType": "payroll-runs-fetched",
"eventTime": "2023-09-26T21:35:44.841Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/642c9aa6f8fc90e0dbb4c92f/payroll-runs",
"employerId": "642c9aa6f8fc90e0dbb4c92f"
}
}
Payroll runs added
When eventType
is payroll-runs-added
, one or more new employer payroll runs have been added to the payroll system and are ready to be retrieved from Atomic.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
payrollRuns
[PayrollRuns]- An array of payroll run
_id
's for the payroll runs which have been added. You can use these_id
's to retrieve the updated payroll run data.
{
"eventType": "payroll-runs-added",
"eventTime": "2023-09-26T21:35:44.842Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/642c9aa6f8fc90e0dbb4c92f/payroll-runs",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"payrollRuns": [
{
"_id": "6488cbae47db79e7ebf0c3d9"
}
]
}
}
Payroll runs updated
When eventType
is payroll-runs-updated
, one or more of the employer's payroll runs have been updated in the payroll system. This webhook will contain an array of the payroll run _id
's where we detected a change.
In addition to the standard event properties, the data
property includes the following:
uri
string- The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerId
string- The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.
payrollRuns
[PayrollRuns]- An array of payroll run
_id
's for the payroll runs which have been updated. You can use these_id
's to retrieve the new payroll run data.
{
"eventType": "payroll-runs-updated",
"eventTime": "2023-09-26T21:35:44.844Z",
"user": {
"_id": "602c4d53dc89c40008db562a",
"identifier": "YOUR_UNIQUE_IDENTIFIER"
},
"data": {
"uri": "https://api.atomicfi.com/employers/642c9aa6f8fc90e0dbb4c92f/payroll-runs",
"employerId": "642c9aa6f8fc90e0dbb4c92f",
"payrollRuns": [
{
"_id": "6488cb8e98c1ac681cd635f8"
}
]
}
}