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.

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

publicTokenstring: Public Access Token used when initializing the Transact SDK.
productenum: The product relevant to the executed task. Options are:
enroll
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 interacts with. Returned as an object containing _id, name, and branding.
metadataobject: The metadata provided by your system when the task was initialized.
taskstring: The ID of the Task; useful for debugging purposes.
taskWorkflowstring: The ID of the Task Workflow; useful for debugging purposes. A Task Workflow is a logical container in our backend for orchestrating Tasks.
dataobject: Payload object containing a reason attribute if a Task failed (see Task failures below), previousStatus, status, distributionType (if applicable), distributionAmount (if applicable), and outputs.

Sample

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

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

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.
reasonenum: Optional. For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
outputsobject: Optional. For Verify Tasks, this object will contain the data retrieved from the payroll system. For more information see the Task outputs section.
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.

Sample task-status-updated event

{
  "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:

authenticatedboolean: Indicates whether or not the Task has successfully authenticated against the payroll system.

Sample task-authentication-status-updated event

{
  "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:

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.

Sample task-status-patched event

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

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

uristring: The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employer endpoints.
employerIdstring: The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.

Sample employer-fetched event

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

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:

uristring: The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employee endpoints.
employerIdstring: The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.

Sample employees-fetched event

{
  "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:

uristring: 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.
employerIdstring: The unique identifier for the employer in the Atomic system.
employeeIdstring: The unique identifier for the employee in the Atomic system. This identifier will be used in the uri to retrieve the added employee data.

Sample employee-added event

{
  "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:

uristring: The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employee endpoints.
employerIdstring: The unique identifier for the employer in the Atomic system.
employeeIdstring: The unique identifier for the employee in the Atomic system. This identifier will be used in the uri to retrieve the updated employee data.
changesobject: 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.

Sample employee-updated event

{
  "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:

uristring: 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.
employerIdstring: 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 and employerDeductionType. Each of these fields can be used to filter the Employee Deduction Requests endpoint.

Sample employee-deductions-request event

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

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:

uristring: The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our employer document endpoints.
employerIdstring: The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.

Sample employer-documents-fetched event

{
  "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:

uristring: The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerIdstring: The unique identifier for the employer in the Atomic system. This identifier will be used in the uri to retrieve the updated employer data.

Sample payroll-runs-fetched event

{
  "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:

uristring: The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerIdstring: 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.

Sample payroll-runs-added event

{
  "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:

uristring: The URI that can be used to retrieve the updated data. This URI will be a constructed HTTPS request against our payroll run endpoints.
employerIdstring: 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.

Sample payroll-runs-updated event

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