PayLink API Reference

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

To get going quickly, we recommend using Postman - an API collaboration tool. Atomic provides a public workspace which you can fork into your own workspace. Use the button below to get started.

The workspace comes fully documented with:

several useful flows using our APIs
requests for all of the Atomic endpoints
an environment containing placeholders for all the variables needed to connect to your Sandbox instance of Console

Authentication

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

API Key and Secret

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

Header	Description
`x-api-key`	API Key for your Atomic account
`x-api-secret`	API Secret for your Atomic account

Access Token

These headers are included in requests that are made via the end user from client-side code, e.g. searching for their employer. The public token defaults to a 24 hour expiry, but can be set to a minimum of 30 minutes by passing in the desired duration using the optional tokenLifetime property in the call to /access-token. This minimum is to allow for users to complete variations of the flows, such as MFA, which can take time.

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

Errors

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

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

API Versioning

The Atomic API accepts an x-atomic-version header. This is a mechanism we have put in place to ensure stability as the surface of the API changes over time. A new version will be released when there are backward incompatible changes to the API. We will publish a changelog and migration guides as new versions are rolled out to highlight any relevant changes and make migrations seamless for consumers of our API.

To use the version header, append the x-atomic-version header to all calls to the Atomic API. The value of the header will follow standardized CalVer practices. The current version is 2022-12-02.

x-atomic-versionDate: A Date-string in the form of YYYY-MM-DD. Specific versions to be provided by Atomic.

Header	Description
`x-atomic-version`	Date string of the required API version

Access Token

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

To create an access token pass in an identifier and identity data for the end user as well as associated account or card details.

If you control all the account and/or card data you would like the end user to select from when updating their payments in the vendor systems, use the Create an Access Token.

Create Access Token

This API is intended to be used when the calling application is able to send all required data fields to Atomic directly.

When passing card data, make sure to send this request to our PCI-compliant environment. You may use pci.atomicfi.com in production, and sandbox-pci.atomicfi.com in sandbox.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

identifierstring

A unique identifier from your system that will be used to reference this user. This could be a primary key used in your system or another unique identifier. Creating multiple access tokens with the same identifier will tie those tokens to the same user in Atomic's system.

identityobject

Details about the end user's identity. These details are regularly required to make an update to a vendor system.

Child Properties

Required Properties

firstNamestring: End user's first name
lastNamestring: End user's last name
postalCodestring: End user's postal code from their address

Optional Properties

addressstring

End user's street address

address2string

Optional second line for the end user's street address

citystring

End user's home city

statestring

End user's home state. 2 digit state code is expected

phonestring

End user's 9 digit phone number without () or -

accounts[AccountDetails]

An array of account detail objects which the end user can select from to update their account on file. Details for one of either an ACH account or card must be provided to complete the operation.

Child Properties

Required Properties

accountNumberstring: Account number used to identify the account
routingNumberstring: The ABA routing number.
typeenum: Type of account. Possible values include checking, savings, or paycard.
titlestring: Title or nickname for the account.

cards[CardDetails]

An array of card detail objects which the end user can select from to update their card on file. Details for either an account or a card must be provided to complete the operation.

Child Properties

Required Properties

numberstring: Card number, should be between 15 and 19 digits in length.
expirystring: Expiry for the card. MM/YY format expected.
cvvstring: CVV number associated with the card.

Optional Properties

brandstring

Brand of card. Possible values include visa, mastercard, american-express, or discover.

titlestring

Title for the card.

Optional Properties

tokenLifetimeinteger

The number of seconds until the token expires. The minimum allowed is 30 min.

Default value: 86,400 (24 hours).

POST/access-token

https://sandbox-pci.atomicfi.com/access-token

BaaS passthrough variation

This version of the API is intended to be used when the calling application is not PCI compliant itself, but rather relies on a BaaS provider to handle the card data. See our guide on transmitting card data for details on whether or not this endpoint is for you.

Properties not explicitly defined in this section will function and be required in the same manner as the Create Access Token flow.

Required Properties

cards[CardDetails]

An array of card detail objects which the end user can select from to update their card on file. Details for either an account or a card must be provided to complete the operation.

Child Properties

Required Properties

lastFourAccountNumberstring

The last four digits of a card number.

expirystring

Expiry for the card. MM/YY format expected

paymentServiceobject

Object containing details required for Atomic to connect to and utilitize a BaaS card provider

Child Properties

Required Properties

galileoobject

String which indicates the associated BaaS you use as your card provider. This example uses Galileo, if another other BaaS provider is required, please reach out to your contacts at Atomic.

Child Properties

Required Properties

apiLoginstring: Web service username, as provided by Galileo.
apiTransKeystring: Web service password, as provided by Galileo.
providerIdstring: Galileo-issued provider identifier.
transactionIdstring: A unique provider-generated ID to identify this API call. A UUID is preferred.
accountNostring: The PRN, PAN or CAD of the account. For card-specific endpoints such as this one, the CAD is preferred. Do not use the PRN if more than one card has ever been associated with this account.

Optional Properties

brandstring

Brand of card. Possible values include visa, mastercard, american-express, or discover. If passed, Transact will display an icon specific to the card brand.

titlestring

Title for the card

Optional Properties

tokenLifetimeinteger

The number of seconds until the token expires. The minimum allowed is 30 min.

Default value: 86,400 (24 hours).

POST/access-token

https://sandbox-pci.atomicfi.com/access-token

Response

Successfully creating an Access Token will return a payload with a data object containing a publicToken. The publicToken may be used to initialize the Transact SDK and is valid for tokenLifetime seconds.

Example response

{
  "data": {
    "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48"
  }
}

Task

Each discrete payroll operation, such as a verification of income, direct deposit switch, or update to a payment account of file, will instantiate what is referred to as a Task in our system. A Task consists of an authentication step where Atomic logs into a payroll or service provider and an operation step where we read data or write to the system; either a direct deposit allocation or updating a payment account on file, depending on the Task.

Get Task Details

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

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

taskIdstring: The id of the Task. The taskId property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.

GET/task/:taskId/details

https://sandbox-api.atomicfi.com/task/:taskId/details

Response

A successful request will return the details of the task.

_idstring

The id of the task.

authenticatedboolean

Indicates whether or not the task has successfully authenticated against the payroll system.

companyobject

Metadata for the employer.

Child Properties

Required Properties

_idstring: Unique identifier for the company.
namestring: The name of the company

Optional Properties

brandingobject

Metadata for the company's branding.

Child Properties

Optional Properties

logoobject

Metadata for the company's logo.

Child Properties

Optional Properties

urlstring

URL for the company's logo.

connectorobject

Metadata for the connector.

Child Properties

Required Properties

_idstring: Unique identifier for the connector.
namestring: The name of the connector

Optional Properties

brandingobject

Metadata for the connector's branding.

Child Properties

Optional Properties

logoobject

Metadata for the connector's logo.

Child Properties

Optional Properties

urlstring

URL for the connector's logo.

createdAtdate

The timestamp when the task was created, stored in UTC and ISO 8601 format.

updatedAtdate

The timestamp when the task was last updated, stored in UTC and ISO 8601 format.

depositDataobjectOptional

If the task is a deposit task, this data will indicate the type of deposit switch performed.

Child Properties

Optional Properties

accountTypestring

The type of the account. Possible values include savings, checking, or paycard.

distributionAmountnumber

The amount being distributed to the account. When distributionType is percent, the number represents a percentage of the total pay. When distributionType is fixed, this number represents a fixed dollar amount. This value is not set when distributionType is total.

distributionTypestring

The type of distribution for the account. Possible values include total, percent, or fixed.

lastFourstring

The last digits of the account number.

routingNumberstring

The routing number.

titlestring

The title of the account.

failReasonstringOptional

The failure reason associated with a failed task. Will consist of one of the failure values.

linkedAccountstringOptional

The id of the linked account used to create the task.

metadataobjectOptional

The metadata provided by your system when the task was initialized.

payrollDataAvailableboolean

A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.

productstring

The product of the task. Possible values include deposit, verify, and tax.

statusstring

The status of the task which may be queued, processing, failed, or completed.

taskWorkflowobject

The task workflow of the task.

Child Properties

Optional Properties

_idstring

The id of the task workflow.

userobject

The user that ran the task.

Child Properties

Optional Properties

_idstring

The id of the user in atomic's system.

identifierstring

The user's unique identifier, as sent to Atomic during AccessToken creation.

Example response

{
  "data": {
    "task": {
      "_id": "65b15fd99b3f03aa9edff9de",
      "authenticated": true,
      "company": {
        "_id": "607e249736b9f053b536bde0",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
          }
        },
        "name": "Test Company"
      },
      "connector": {
        "_id": "607e249736b9f053b536bde1",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/b02670fa-ce1b-4171-855b-6856b37bb938.png"
          }
        },
        "name": "Test Connector"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:05.000Z",
      "depositData": {
        "accountType": "checking",
        "distributionAmount": 10,
        "distributionType": "fixed",
        "lastFourAccountNumber": "0000",
        "routingNumber": "22000000",
        "title": "Checking Account"
      },
      "failReason": "unknown-failure",
      "linkedAccount": "645963a0b754649972f3d4ac",
      "metadata": {
        "data": "test"
      },
      "payrollDataAvailable": false,
      "product": "deposit",
      "status": "failed",
      "taskWorkflow": {
        "_id": "643f2ed34253e21bdbd2de31"
      },
      "user": {
        "_id": "607e249736b9f053b536bdea",
        "identifier": "GUID"
      }
    }
  }
}

Get Task Status

Calling this API returns the status of a Task. Submit the corresponding taskId and receive the status of that Task and payrollDataAvailable which indicates that any fetchable data is ready to be pulled via the corresponding API calls.

This endpoint is designed to be lightweight and intended for polling use cases.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

taskIdstring: The id of the Task. The taskId property is sent in mulitple webhooks or any of the interaction events which are fired after the authentication phase of the flow has begun.

GET/task/:taskId/status

https://sandbox-api.atomicfi.com/task/:taskId/status

Response

A successful request will return the createdAt date, status, and if a Task failed (Tasks with a status of "failed") a failReason.

createdAtdate: The timestamp when the Task was created, stored in UTC and ISO 8601 format.
statusstring: The status of the task which may be queued, processing, failed, or completed.
failReasonstringOptional: The failure reason associated with a failed task. Will consist of one of the failure values.

Example response

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

Generate File URL

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

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

taskIdstring: The _id of the Task, which can be retrieved either from interaction events during the Transact session with the user or from the associated webhooks.
fileIdstring: The _id of the file. This is returned in API calls for relevant data categories, such as /taxes for W-2's, or sent via relevant webhooks when a file is retrieved from the payroll system.

GET/task/:taskId/file/:fileId/generate-url

https://sandbox-api.atomicfi.com/task/:taskId/file/:fileId/generate-url

Response

A successful request will return a URL that can be used to download the file.

urlstring: A URL that can be used to download the file. The URL is valid for 1 hour.

Example response

{
  "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
}

PrescreenBeta

This endpoint is currently in beta. If you would like access please reach out to your Customer Success Manager.

Prescreen is an endpoint you can call prior to task creation in order to get a predicted conversion confidence, offering additional insight into your user and the likelihood they will succeed using our service.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

Required Properties

companyobject

Child Properties

Required Properties

namestring: The name of the employer provided to you by the end user.

Optional Properties

idstring

If you have our company IDs mapped you can use an ID instead of relying on our search.

productstring

The name of the product for which you would like a conversion confidence prediction. Currently Verify is the only product supported.

POST/task/prescreen

https://sandbox-api.atomicfi.com/task/prescreen

Response

The response returns an object with a single confidence property as a string value. We will make this determination based on a variety of proprietary considerations such as traffic volumes and calculations with other similar connector types.

confidencestring: The likelihood of the user being successful using our flow. Will return a value of "HIGH" or "LOW".

Example response

{
  "data": {
    "confidence": "HIGH"
  }
}

User

A User is an entity in the Atomic system that is created during the access token creation process. Details about a user's accounts are stored on the user object for reference as needed in an operation; ie. for adding a deposit account to a payroll system or updating the card-on-file for a merchant service.

Update User

This endpoint is used to add data to a user in response to an onDataRequest event emitted from our Transact SDK. Any data passed will be upserted into the user's object. The typical use case is to delay the transmission of sensitive data (bank accounts, cards, identity information, etc.) until our system has need for such data.

The shape of the request body is similar to our access token creation endpoint, except the data to be added/updated will be nested in a data key, and the identifier will not be nested, but remain on the first-level of the object.

Authentication is handled via the API Key and Secret method. This API is intended to be called from your backend service so your API Keys and Secrets are not deployed to your client side application.

PUT/user

https://sandbox-pci.atomicfi.com/user