API

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:

HeaderDescription
x-api-keyAPI Key for your Atomic account
x-api-secretAPI Secret for your Atomic account

Access Token

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

HeaderDescription
x-public-token Public token generated during access token creation.

Errors

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

CodeTitleDescription
200OKThe request was successful.
400Bad RequestThe request was unacceptable.
401UnauthorizedMissing or invalid credentials.
404Not FoundThe resource does not exist.
422Validation ErrorA validation error occurred.
429Too Many RequestsToo may requests, please try again later.
50XInternal Server ErrorAn error occurred with our API.

Access Token

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

The required data depends on your use case. For PayLink Manage, only the identifier field is needed. For PayLink Switch, you must provide user identity information along with either card or account details. We also support flexible integration options for when and how data is provided—for example, allowing the user to enter their CVV manually if needed.

Create Access Token

This API initializes a flow through the Atomic experience by creating an AccessToken that is used to instantiate the Transact SDK. The required fields depend on your specific use case.

PayLink Manage: Only the identifier field is required.

PayLink Switch: You need the identifier, identity object, and either cards or accounts arrays. At least one card or account must be provided.

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.

For PayLink Switch use cases, when passing card data, make sure to send requests to our PCI-compliant environment. Use pci.atomicfi.com in production, and sandbox-pci.atomicfi.com in sandbox.

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.
cards[CardDetails]
An array of card detail objects which the end user can select from to update their payment method. Required for PayLink Switch when using cards as the payment method. At least one card or account must be provided.
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.
titlestring
Title for the card.
Optional Properties
brandstring
Brand of card. Possible values include mastercard, visa, american-express, or discover.
subtitlestring
Subtitle for the card.
cardStatusstring
Status of the card. Possible values are currently limited to: frozen.
accounts[AccountDetails]
An array of account detail objects which the end user can select from to update their payment method. Required for PayLink Switch when using bank accounts as the payment method. At least one card or account must be provided.
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.
identityobject
Details about the end user's identity. Required for PayLink Switch as these details are needed to update payment methods in merchant systems.
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
addressstring
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 10 digit phone number without () or -
Optional Properties
address2string
Optional second line for the end user's street address
emailstring
End user's email address

Optional Properties

tokenLifetimeinteger
The number of seconds until the token expires. The minimum allowed is 1,800 (30 min). The max allowed is 2,592,000 (30 days). Shorter token lifetimes are recommended for security purposes.

Default value: 86,400 (24 hours).

PayLink Manage

POST/access-token
https://sandbox-api.atomicfi.com/access-token

PayLink Switch

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

BaaS passthrough variation

Use this variation when your application is not PCI compliant and relies on a BaaS provider to handle card data. This allows Atomic to securely retrieve card information from your BaaS provider during the payment method update process.

See our guide on transmitting card data for details on whether this endpoint is right for your integration.

Properties not explicitly defined in this section function the same as the standard 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
lastFourstring
The last four digits of a card number.
titlestring
Title for the card
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.
apiUrlstring
The production url that your organization uses to connect to Galileo.
Optional Properties
brandstring
Brand of card. Possible values include visa, mastercard, american-express, or discover. Transact will use this field to display an icon specific to the card brand.
expirystring
Expiry for the card. MM/YY format expected
subtitlestring
Subtitle for the card

Optional Properties

tokenLifetimeinteger
The number of seconds until the token expires. The minimum allowed is 1,800 (30 min). The max allowed is 2,592,000 (30 days). Shorter token lifetimes are recommended for security purposes.

Default value: 86,400 (24 hours).

PayLink Switch - BaaS passthrough

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

CDE Bypass Variation

Use this variation when you want to transmit card and identity data directly from the user's device to third-party systems, bypassing Atomic's Card Data Environment (CDE). This is useful when you have all the card data accessible in your app and want to avoid sending it through Atomic's servers.

See our guide on CDE Bypass for complete implementation details and to determine if this flow is right for your integration.

For a CDE Bypass flow, only the identifier field is needed when creating an access token. Any card, account, or identity fields will be provided directly to the Transact SDK later in the flow.

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.

PayLink Switch - CDE Bypass

POST/access-token
https://sandbox-api.atomicfi.com/access-token

Access Token Response

Creating an Access Token in this manner will return a payload containing a publicToken. The publicToken will be used to initialize the Transact SDK.

Example response 
{
  "data": {
    "publicToken": "PUBLIC_TOKEN"
  }
}

Revoke Access Token

This endpoint is used to revoke an existing AccessToken. This action invalidates the token, preventing it from being used to access Atomic's API resources.

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

publicTokenstring
The publicToken associated with the AccessToken you wish to revoke. Passed with the URL as a path parameter (e.g., /access-token/:publicToken/revoke). Replace :publicToken with the value returned by the access-token API response.
PUT/access-token/:publicToken/revoke
https://sandbox-api.atomicfi.com/access-token/:publicToken/revoke

Response

A successful response will return a JSON object with a result object containing success equal to true.

Example response 
{
  "result": {
    "success": true
  }
}

Company

PayLink enables connectivity to merchant accounts, streaming services, and recurring bills to update payment methods and manage subscriptions. In this context, a 'Company' refers to the service or merchant that a user connects to in order to manage and update payment details.

Company Search

Use this endpoint to build a typeahead experience, as employed in our Transact SDK, or to get the company's _id for deeplinking to the login section of Transact.
Search for a Company using a text query. Searches can also be filtered by passing in additional properties detailed below.

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

Required Properties

querystring
Filters companies by name. Uses fuzzy matching to narrow results.
scopesenum
Filters companies by product suite. Further filtering is possible with the product property. Options are:
    pay-linkuser-link

Optional Properties

productstring
Filters companies by a specific product. Possible values include switch and present.
tags[string]
Filters companies by a specific tag. Some possible values include subscription, streaming, and telecom.
POST/company/search
https://sandbox-api.atomicfi.com/company/search

Accounts

An Account in the Atomic context refers to a connection to a third-party system. This connection enables both read and write operations on the linked system as authorized by the user. For instance, after linking a Netflix account, Atomic can retrieve account data or perform actions such as pausing the subscription or managing the user’s plan.

Get Accounts

This endpoint returns all Accounts associated with an end user.

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.

Optional Properties

connectedboolean
Optional query parameter to filter accounts based on whether the user has connected the account via Atomic. When received, only an array of accounts will be returned.
GET/pay-link/accounts
https://sandbox-api.atomicfi.com/pay-link/accounts

Response

The response includes an Account object.

accounts[Account]
An array of Account objects.
Child Properties
Required Properties
_idstring
Unique identifier for the PayLink Account connected by the end user.
processingboolean
A boolean value indicating whether or not the account is processing.
connectionStatusenum
The status of the account, either initial, connected, or disconnected. If the account is initial, then the account has been selected but the user has not attempted to connect to it. If the account is connected then the account can be accessed. If the account is disconnected, then we cannot access the account with the given credentials.
companyCompany
An object containing details of the company to which the PayLink Account is connected.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account.
    view-accountrefresh
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
bills[Bills]
The recurring expenses retrieved from the connected system, such as the actual Netflix expense on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
sourceIdstring
An ID of the account pulled from the connected system.
Optional Properties
namestring
The name of the bill.
amountnumber
The amount of the bill.
amountDisclaimerstring
A disclaimer about how the bill amount was determined.
autopayStatusenum
Whether the bill has autopay enabled. One of enabled, disabled, or paused.
billingCyclestring
The billing cycle. One of monthly, bi-monthly, every-three-months, every-six-months, or annually.
dueDatedate
The due date of the bill.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the bill.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
profiles[Profiles]
The profiles associated with the accounts.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
paymentMethodPaymentMethod
The payment method of the bill, if different from the account payment methods.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
subitems[BillingSubItems]
Subitems of the billing item.
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
usage[Usage]
The usage of resources limited by the bill.
Child Properties
Optional Properties
descriptionstring
The description of the limited resource.
limitnumber
The total amount of the limited resource available to use.
unitstring
The units of usage of the limited resource. One of gigabytes, megabytes, minutes, kilowatts-per-hour, or users.
usednumber
The amount of the limited resource used in the current billing cycle.
plans[Plan]
The plans associated with the bill.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
typeIdstring
The type ID of the plan.
statusstring
The status of the plan.
descriptionstring
The description of the plan.
amountnumber
The amount of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangeobject
The pending change of the plan.
Child Properties
Optional Properties
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
statusenum
The new plan status when the change takes effect, if status is changing. One Of active, inactive, paused, or cancelled.
amountnumber
The new plan amount when the change takes effect, if amount is changing.
typeIdstring
The new plan type id when the change takes effect, if plan type is changing.
descriptionstring
The new plan description when the change takes effect, if plan description is changing.
billingCyclestring
The new billing cycle when the change takes effect, if billing cycle is changing.
companyCompany
An object containing details of the company to which the bill connected. This field may not be returned in cases in which the company for the account does not exist in Atomic's system. An example is a subscription that is purchased via Amazon, like the Ad Free subscription for Prime Video. This bill will not have an associated company object, but is considered "managed by" the Amazon company stored in the bill's parent account.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on the bill. This list includes all actions available for a bill. However, each user will only see a subset of these actions, tailored to their specific account and bill.
    change-plancancel-planpause-plan
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
Optional Properties
lastSyncedAtdate
The last time the user's data was synced.
dataAccountData
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
categoryenum
An enum of the category of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
identities[Identity]
The identities connected to the account.
Child Properties
Optional Properties
firstNamestring
The first name of the identity.
lastNamestring
The last name of the identity.
emailstring
The email associated with the identity.
phonestring
The phone number associated with the identity.
addressstring
The address associated with the identity.
address2string
The line 2 of the address associated with the identity.
citystring
The city of the address associated with the identity.
statestring
The state of the address associated with the identity.
postalCodestring
The postalCode of the address associated with the identity.
paymentMethods[PaymentMethod]
An array of objects containing the payment methods associated with the account.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
recurringFinancialTransactionRecurringFinancialTransaction
The associated recurring expense detected from the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
typeenum
The type of the recurring financial transaction. One of incoming or outgoing.
financialTransactions[FinancialTransactions]
The financial transactions that were detected as recurring.
Child Properties
Required Properties
identifierstring
The identifier of the financial transaction
descriptionstring
The description of the financial transaction
amountnumber
The amount of the financial transaction
datedate
The date of the financial transaction
sourcestring
The source of the financial transaction
categoryenum
The category of the recurring financial transaction. Options include:
    subscriptionloanpolicytelecom
Optional Properties
nextBillingDatedate
The next billing date of the recurring financial transaction.
Example response 
{
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "processing": false,
      "connectionStatus": "connected",
      "lastSynedAt": "2024-10-20T18:00:54.761Z",
      "data": {
        "category": "subscription",
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "paymentMethods": [
          {
            "type": "card",
            "lastFour": "2345",
            "brand": "Mastercard",
            "isPrimary": true
          }
        ]
      },
      "company": {
        "_id": "65272c415d8a530008e972df",
        "name": "Amazon",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
            "backgroundColor": "#FF9900"
          },
          "color": "#FF9900"
        }
      },
      "actions": [
        {
          "type": "view-account",
          "id": "BASE64_ENCODED_ID",
          "automated": false
        },
        {
          "type": "refresh",
          "id": "BASE64_ENCODED_ID",
          "automated": true
        }
      ],
      "bills": [
        {
          "_id": "67376c5befe988922e8adef5",
          "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
          "name": "Hulu",
          "amount": 20.7,
          "autopayStatus": "enabled",
          "billingCycle": "monthly",
          "dueDate": "2024-11-20T23:59:59.000Z",
          "paymentHistory": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "items": [
            {
              "description": "Standard plan",
              "amount": 17.99
            },
            {
              "description": "Taxes and fees",
              "amount": 2.71
            }
          ],
          "profiles": [
            {
              "name": "Test Profile",
              "lastUsed": "2024-10-31T17:34:55.376Z"
            }
          ],
          "plans": [
            {
              "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
              "typeId": "no_ads",
              "status": "active",
              "description": "Hulu (No Ads)",
              "amount": 17.99,
              "freeTrial": false
            }
          ],
          "company": {
            "_id": "6529a6eccb8e7200085c6ef6",
            "name": "Hulu",
            "branding": {
              "logo": {
                "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
                "backgroundColor": "#040405"
              },
              "color": "#040405"
            }
          },
          "actions": [
            {
              "type": "change-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": false
            },
            {
              "type": "cancel-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": true
            },
            {
              "type": "pause-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": true
            }
          ]
        }
      ]
    }
  ]
}

Get Account

This endpoint returns an account.

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

idstring
The id of the account in Atomic's system.
GET/pay-link/accounts/:id
https://sandbox-api.atomicfi.com/pay-link/accounts/:id

Response

The response includes an Account object.

accountobject
An Account object.
Child Properties
Required Properties
_idstring
Unique identifier for the PayLink Account connected by the end user.
processingboolean
A boolean value indicating whether or not the account is processing.
connectionStatusenum
The status of the account, either initial, connected, or disconnected. If the account is initial, then the account has been selected but the user has not attempted to connect to it. If the account is connected then the account can be accessed. If the account is disconnected, then we cannot access the account with the given credentials.
companyCompany
An object containing details of the company to which the PayLink Account is connected.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account.
    view-accountrefresh
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
bills[Bills]
The recurring expenses retrieved from the connected system, such as the actual Netflix expense on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
sourceIdstring
An ID of the account pulled from the connected system.
Optional Properties
namestring
The name of the bill.
amountnumber
The amount of the bill.
amountDisclaimerstring
A disclaimer about how the bill amount was determined.
autopayStatusenum
Whether the bill has autopay enabled. One of enabled, disabled, or paused.
billingCyclestring
The billing cycle. One of monthly, bi-monthly, every-three-months, every-six-months, or annually.
dueDatedate
The due date of the bill.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the bill.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
profiles[Profiles]
The profiles associated with the accounts.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
paymentMethodPaymentMethod
The payment method of the bill, if different from the account payment methods.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
subitems[BillingSubItems]
Subitems of the billing item.
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
usage[Usage]
The usage of resources limited by the bill.
Child Properties
Optional Properties
descriptionstring
The description of the limited resource.
limitnumber
The total amount of the limited resource available to use.
unitstring
The units of usage of the limited resource. One of gigabytes, megabytes, minutes, kilowatts-per-hour, or users.
usednumber
The amount of the limited resource used in the current billing cycle.
plans[Plan]
The plans associated with the bill.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
typeIdstring
The type ID of the plan.
statusstring
The status of the plan.
descriptionstring
The description of the plan.
amountnumber
The amount of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangeobject
The pending change of the plan.
Child Properties
Optional Properties
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
statusenum
The new plan status when the change takes effect, if status is changing. One Of active, inactive, paused, or cancelled.
amountnumber
The new plan amount when the change takes effect, if amount is changing.
typeIdstring
The new plan type id when the change takes effect, if plan type is changing.
descriptionstring
The new plan description when the change takes effect, if plan description is changing.
billingCyclestring
The new billing cycle when the change takes effect, if billing cycle is changing.
companyCompany
An object containing details of the company to which the bill connected. This field may not be returned in cases in which the company for the account does not exist in Atomic's system. An example is a subscription that is purchased via Amazon, like the Ad Free subscription for Prime Video. This bill will not have an associated company object, but is considered "managed by" the Amazon company stored in the bill's parent account.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on the bill. This list includes all actions available for a bill. However, each user will only see a subset of these actions, tailored to their specific account and bill.
    change-plancancel-planpause-plan
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
Optional Properties
lastSyncedAtdate
The last time the user's data was synced.
dataAccountData
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
categoryenum
An enum of the category of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
identities[Identity]
The identities connected to the account.
Child Properties
Optional Properties
firstNamestring
The first name of the identity.
lastNamestring
The last name of the identity.
emailstring
The email associated with the identity.
phonestring
The phone number associated with the identity.
addressstring
The address associated with the identity.
address2string
The line 2 of the address associated with the identity.
citystring
The city of the address associated with the identity.
statestring
The state of the address associated with the identity.
postalCodestring
The postalCode of the address associated with the identity.
paymentMethods[PaymentMethod]
An array of objects containing the payment methods associated with the account.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
recurringFinancialTransactionRecurringFinancialTransaction
The associated recurring expense detected from the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
typeenum
The type of the recurring financial transaction. One of incoming or outgoing.
financialTransactions[FinancialTransactions]
The financial transactions that were detected as recurring.
Child Properties
Required Properties
identifierstring
The identifier of the financial transaction
descriptionstring
The description of the financial transaction
amountnumber
The amount of the financial transaction
datedate
The date of the financial transaction
sourcestring
The source of the financial transaction
categoryenum
The category of the recurring financial transaction. Options include:
    subscriptionloanpolicytelecom
Optional Properties
nextBillingDatedate
The next billing date of the recurring financial transaction.
Example response 
{
  "account": {
    "_id": "67376c5befe988922e8aabc4",
    "processing": false,
    "connectionStatus": "connected",
    "lastSynedAt": "2024-10-20T18:00:54.761Z",
    "data": {
      "category": "subscription",
      "identities": [
        {
          "firstName": "test",
          "email": "test@email.com",
          "phone": "5558675309"
        }
      ],
      "paymentMethods": [
        {
          "type": "card",
          "lastFour": "2345",
          "brand": "Mastercard",
          "isPrimary": true
        }
      ]
    },
    "company": {
      "_id": "65272c415d8a530008e972df",
      "name": "Amazon",
      "branding": {
        "logo": {
          "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
          "backgroundColor": "#FF9900"
        },
        "color": "#FF9900"
      }
    },
    "actions": [
      {
        "type": "view-account",
        "id": "BASE64_ENCODED_ID",
        "automated": false
      },
      {
        "type": "refresh",
        "id": "BASE64_ENCODED_ID",
        "automated": true
      }
    ],
    "bills": [
      {
        "_id": "67376c5befe988922e8adef5",
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
        "name": "Hulu",
        "amount": 20.7,
        "autopayStatus": "enabled",
        "billingCycle": "monthly",
        "dueDate": "2024-11-20T23:59:59.000Z",
        "paymentHistory": [
          {
            "date": "2024-10-20T18:00:54.761Z",
            "amount": 20.7
          },
          {
            "date": "2024-09-20T09:48:31.093Z",
            "amount": 19.38
          }
        ],
        "items": [
          {
            "description": "Standard plan",
            "amount": 17.99
          },
          {
            "description": "Taxes and fees",
            "amount": 2.71
          }
        ],
        "profiles": [
          {
            "name": "Test Profile",
            "lastUsed": "2024-10-31T17:34:55.376Z"
          }
        ],
        "plans": [
          {
            "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
            "typeId": "no_ads",
            "status": "active",
            "description": "Hulu (No Ads)",
            "amount": 17.99,
            "freeTrial": false
          }
        ],
        "company": {
          "_id": "6529a6eccb8e7200085c6ef6",
          "name": "Hulu",
          "branding": {
            "logo": {
              "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
              "backgroundColor": "#040405"
            },
            "color": "#040405"
          }
        },
        "actions": [
          {
            "type": "change-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": false
          },
          {
            "type": "cancel-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": true
          },
          {
            "type": "pause-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": true
          }
        ]
      }
    ]
  }
}

Detect Accounts

This endpoint accepts transaction data for a specific end user. Atomic uses this data to identify recurring payments and recommend companies for the user to connect to and manage via our APIs.

The response returns an array of Account objects, providing details on whether the detected merchants are supported by Atomic along with other relevant information.

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

financialTransactions[FinancialTransactions]
An array of financial transaction objects.
Child Properties
Required Properties
identifierstring
An ID of the transaction.
datestring
The date the transation was processed, in ISO8601 format.
descriptionstring
The transaction description from the merchant.
amountnumber
Amount of the transaction.
Optional Properties
currencyenum
Currency in which the transaction was processed.
    usdeurcad
merchantNamestring
The name of the merchant associated with the transaction.
typeenum
An enum of the type of transaction. Options are:
categorystring
Category of the transaction.
subCategorystring
Optional subcategory of the transaction.
POST/pay-link/accounts?accountId
https://sandbox-api.atomicfi.com/pay-link/accounts?accountId

Response

The response contains an array of Account objects containing and relevant metadata relating to the Accounts connected by the end user.

accounts[Account]
An array of Account objects.
Child Properties
Required Properties
_idstring
Unique identifier for the PayLink Account connected by the end user.
processingboolean
A boolean value indicating whether or not the account is processing.
connectionStatusenum
The status of the account, either initial, connected, or disconnected. If the account is initial, then the account has been selected but the user has not attempted to connect to it. If the account is connected then the account can be accessed. If the account is disconnected, then we cannot access the account with the given credentials.
companyCompany
An object containing details of the company to which the PayLink Account is connected.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account.
    view-accountrefresh
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
bills[Bills]
The recurring expenses retrieved from the connected system, such as the actual Netflix expense on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
sourceIdstring
An ID of the account pulled from the connected system.
Optional Properties
namestring
The name of the bill.
amountnumber
The amount of the bill.
amountDisclaimerstring
A disclaimer about how the bill amount was determined.
autopayStatusenum
Whether the bill has autopay enabled. One of enabled, disabled, or paused.
billingCyclestring
The billing cycle. One of monthly, bi-monthly, every-three-months, every-six-months, or annually.
dueDatedate
The due date of the bill.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the bill.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
profiles[Profiles]
The profiles associated with the accounts.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
paymentMethodPaymentMethod
The payment method of the bill, if different from the account payment methods.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
subitems[BillingSubItems]
Subitems of the billing item.
Child Properties
Optional Properties
descriptionstring
Description of the billing item.
amountnumber
Amount of the billing item.
usage[Usage]
The usage of resources limited by the bill.
Child Properties
Optional Properties
descriptionstring
The description of the limited resource.
limitnumber
The total amount of the limited resource available to use.
unitstring
The units of usage of the limited resource. One of gigabytes, megabytes, minutes, kilowatts-per-hour, or users.
usednumber
The amount of the limited resource used in the current billing cycle.
plans[Plan]
The plans associated with the bill.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
typeIdstring
The type ID of the plan.
statusstring
The status of the plan.
descriptionstring
The description of the plan.
amountnumber
The amount of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangeobject
The pending change of the plan.
Child Properties
Optional Properties
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
statusenum
The new plan status when the change takes effect, if status is changing. One Of active, inactive, paused, or cancelled.
amountnumber
The new plan amount when the change takes effect, if amount is changing.
typeIdstring
The new plan type id when the change takes effect, if plan type is changing.
descriptionstring
The new plan description when the change takes effect, if plan description is changing.
billingCyclestring
The new billing cycle when the change takes effect, if billing cycle is changing.
companyCompany
An object containing details of the company to which the bill connected. This field may not be returned in cases in which the company for the account does not exist in Atomic's system. An example is a subscription that is purchased via Amazon, like the Ad Free subscription for Prime Video. This bill will not have an associated company object, but is considered "managed by" the Amazon company stored in the bill's parent account.
Child Properties
Optional Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Optional Properties
logoobject
A PNG of the logo of the company.
Child Properties
Optional Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
actions[Actions]
Child Properties
Optional Properties
actionIdstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on the bill. This list includes all actions available for a bill. However, each user will only see a subset of these actions, tailored to their specific account and bill.
    change-plancancel-planpause-plan
automatedboolean
Whether or not the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitorieed using webhooks. If false, then the user will perform the action on their device.
Optional Properties
lastSyncedAtdate
The last time the user's data was synced.
dataAccountData
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
categoryenum
An enum of the category of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
identities[Identity]
The identities connected to the account.
Child Properties
Optional Properties
firstNamestring
The first name of the identity.
lastNamestring
The last name of the identity.
emailstring
The email associated with the identity.
phonestring
The phone number associated with the identity.
addressstring
The address associated with the identity.
address2string
The line 2 of the address associated with the identity.
citystring
The city of the address associated with the identity.
statestring
The state of the address associated with the identity.
postalCodestring
The postalCode of the address associated with the identity.
paymentMethods[PaymentMethod]
An array of objects containing the payment methods associated with the account.
Child Properties
Optional Properties
typeenum
The type of the payment method. One of bank, card or paypal.
lastFourstring
The last four digits of the payment method.
brandstring
The brand of the payment method.
isPrimaryboolean
Whether the payment method is the primary payment method.
descriptionstring
The description of the payment method.
expirydate
The date the payment method expires.
accountNumberstring
The account number of the payment method. Only applicable for type of bank.
routingNumberstring
The routing number of the payment method. Only applicable for type of bank.
recurringFinancialTransactionRecurringFinancialTransaction
The associated recurring expense detected from the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
typeenum
The type of the recurring financial transaction. One of incoming or outgoing.
financialTransactions[FinancialTransactions]
The financial transactions that were detected as recurring.
Child Properties
Required Properties
identifierstring
The identifier of the financial transaction
descriptionstring
The description of the financial transaction
amountnumber
The amount of the financial transaction
datedate
The date of the financial transaction
sourcestring
The source of the financial transaction
categoryenum
The category of the recurring financial transaction. Options include:
    subscriptionloanpolicytelecom
Optional Properties
nextBillingDatedate
The next billing date of the recurring financial transaction.
Example response 
{
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "processing": false,
      "connectionStatus": "connected",
      "lastSynedAt": "2024-10-20T18:00:54.761Z",
      "data": {
        "category": "subscription",
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "paymentMethods": [
          {
            "type": "card",
            "lastFour": "2345",
            "brand": "Mastercard",
            "isPrimary": true
          }
        ]
      },
      "company": {
        "_id": "65272c415d8a530008e972df",
        "name": "Amazon",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
            "backgroundColor": "#FF9900"
          },
          "color": "#FF9900"
        }
      },
      "actions": [
        {
          "type": "view-account",
          "id": "BASE64_ENCODED_ID",
          "automated": false
        },
        {
          "type": "refresh",
          "id": "BASE64_ENCODED_ID",
          "automated": true
        }
      ],
      "bills": [
        {
          "_id": "67376c5befe988922e8adef5",
          "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
          "name": "Hulu",
          "amount": 20.7,
          "autopayStatus": "enabled",
          "billingCycle": "monthly",
          "dueDate": "2024-11-20T23:59:59.000Z",
          "paymentHistory": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "items": [
            {
              "description": "Standard plan",
              "amount": 17.99
            },
            {
              "description": "Taxes and fees",
              "amount": 2.71
            }
          ],
          "profiles": [
            {
              "name": "Test Profile",
              "lastUsed": "2024-10-31T17:34:55.376Z"
            }
          ],
          "plans": [
            {
              "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
              "typeId": "no_ads",
              "status": "active",
              "description": "Hulu (No Ads)",
              "amount": 17.99,
              "freeTrial": false
            }
          ],
          "company": {
            "_id": "6529a6eccb8e7200085c6ef6",
            "name": "Hulu",
            "branding": {
              "logo": {
                "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
                "backgroundColor": "#040405"
              },
              "color": "#040405"
            }
          },
          "actions": [
            {
              "type": "change-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": false
            },
            {
              "type": "cancel-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": true
            },
            {
              "type": "pause-plan",
              "id": "BASE64_ENCODED_ID",
              "automated": true
            }
          ]
        }
      ]
    }
  ]
}

Delete Accounts

This endpoint will delete all accounts for the specified user.

A successful response will return a JSON object with a result object containing success equal to true.

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.

DELETE/pay-link/accounts/
https://sandbox-api.atomicfi.com/pay-link/accounts/

Delete Account

This endpoint will delete an account.

A successful response will return a JSON object with a result object containing success equal to true.

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

idstring
The id of the account in Atomic's system.
DELETE/pay-link/accounts/:id
https://sandbox-api.atomicfi.com/pay-link/accounts/:id

Action History

Atomic maintains a log of all automated actions performed by a user or on their behalf. This API allows you to retrieve the history of those actions, providing visibility into what was executed and when.

Note: This endpoint does not include interactive (non-automated) actions that require user input, such as selecting a plan or entering MFA codes.

Get Action History

Use this endpoint to get the action history for a given account.

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

Optional Properties

accountIdstringOptional
The Atomic ID for the account. Retrieved from the Accounts API, or from events emitted from the Transact SDK. If this is omitted, actions for all accounts from the user scoped in the header are returned.
GET/pay-link/action-history?accountId
https://sandbox-api.atomicfi.com/pay-link/action-history?accountId

Financial Transactions

An Financial Transaction in the Atomic context refers to a document that represents financial transaction.

Find Company

This endpoint is used to find a company in the Atomic system that matches the provided financial transactions.

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
The unique identifier of the transaction.
descriptionstring
The description of the transactions.
POST/pay-link/financial-transactions/find-company
https://sandbox-api.atomicfi.com/pay-link/financial-transactions/find-company

Response

A successful request will return the provided financial transactions with an associate company if found.

identifierstring
The unique identifier of the transaction.
descriptionstring
The description of the transactions.
companyCompany
The company, in the Atomic system, that was found for the provided financial transaction. If no company is found, this value will not be returned.
Child Properties
Required Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company. Useful if you are surfacing logos in your experience.
Child Properties
Required Properties
logoobject
A PNG of the logo of the company.
Child Properties
Required Properties
urlstring
The URL of the logo, served from our CDN.
backgroundColorstring
The background color of the logo.
colorstring
The color of the company. Atomic uses this color to style the experience - buttons and other UI elements.
Example response 
{
  "data": {
    "financialTransactions": [
      {
        "identifier": "ff1e11abe",
        "description": "POS Transaction Netflixcom NETFLIXCOM LOS GATOS CAUS",
        "company": {
          "_id": "64ecca15ec669e000851d5d2",
          "branding": {
            "logo": {
              "backgroundColor": "#000000",
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
            },
            "color": "#000000"
          },
          "name": "Netflix"
        }
      },
      {
        "identifier": "4f89277",
        "description": "POS Transaction Hulu HLUHULUPLUS SANTA MONICA CAUS",
        "company": {
          "_id": "6529a6eccb8e7200085c6ef6",
          "branding": {
            "logo": {
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
              "backgroundColor": "#040405"
            },
            "color": "#040405"
          },
          "name": "Hulu"
        }
      },
      {
        "identifier": "5115abe3",
        "description": "POS Transaction SPOTIFY 4 WORLD TRACE CENTER 68777781161 NYUS",
        "company": {
          "_id": "652801e35d8a530008e9e2cd",
          "branding": {
            "logo": {
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
              "backgroundColor": "#000000"
            },
            "color": "#000000"
          },
          "name": "Spotify"
        }
      }
    ]
  }
}

Suggestions

An Suggestion in the Atomic context refers to a document that represents a possible method that a user could use to save money on their bill.

Review a Suggestion

This endpoint is used to review a Suggestion. Reviews are used to improve our suggestion generation engine. Suggestions reviewed with the rating of not-interested will be filtered out when accounts are returned via webhooks and api endpoints. Currently, only the rating value not-interested is supported.

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

ratingstring
Currently, only a rating of not-interested is accepted.
suggestionIdstring
This is the identifier of the suggestion.
accountIdstring
This is the id of the account that the suggestion is associated with.
POST/pay-link/suggestion-review
https://sandbox-api.atomicfi.com/pay-link/suggestion-review

Task

Each discrete operation processed through the Atomic system, such as an update to a payment account on file or an action against a merchant system on behalf of a user, will instantiate what is referred to as a Task. A Task consists of an authentication step where Atomic logs into merchant system or service provider and an operation step either data is read or an update is written to the system in question.

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 multiple 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 merchant 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.
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.
productstring
The product of the task. Possible values include present and switch.
statusstring
The status of the task which may be queued, processing, failed, or completed.
taskWorkflowobject
The Task Workflow of the Task. When multiple tasks are associated with a single workflow, they will all have the same taskWorkflow object. Every Task is associated with a Task Workflow, even if it not associated with another Task.
Child Properties
Required Properties
_idstring
The id of the Task Workflow.
userobject
The user who processed the Task.
Child Properties
Required 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",
      "failReason": "unknown-failure",
      "linkedAccount": "645963a0b754649972f3d4ac",
      "metadata": {
        "data": "test"
      },
      "product": "switch",
      "status": "completed",
      "taskWorkflow": {
        "_id": "643f2ed34253e21bdbd2de31"
      },
      "user": {
        "_id": "607e249736b9f053b536bdea",
        "identifier": "IDENTIFIER_FROM_YOUR_SYSTEM"
      }
    }
  }
}

Get Task Status

Calling this API returns the status of a Task. Submit the corresponding taskId and receive the status of that Task.

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 multiple 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 
{
  "createdAt": "2023-01-03T16:40:48.009Z",
  "status": "failed",
  "failReason": "payment-method-not-supported"
}

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.

End Monitoring

This endpoint is used to remove monitoring for users that have payroll data monitoring enabled via continuous access.

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
The user's unique identifier, as sent to Atomic during AccessToken creation.
PUT/user/:identifier/end-monitoring
https://sandbox-api.atomicfi.com/user/:identifier/end-monitoring

Response

A successful response will return a json object with success equal to true.

Example response 
{
  "success": true
}

Get Tasks

This endpoint is used to retrieve tasks for the specified user.

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
The user's unique identifier, as sent to Atomic during AccessToken creation.

Optional Properties

statusstring
The status of the task, provided as a query string parameter, which may be queued, processing, failed, or completed.
payrollDataAvailablestring
A boolean value, provided as a query string parameter, indicating whether or not the user's payroll data is ready for retrieval via API.
GET/user/:identifier/tasks
https://sandbox-api.atomicfi.com/user/:identifier/tasks

Response

A successful response will return an object with data.tasks equal to an array of task objects with the following properties.

_idstring
The id of the task.
authenticatedboolean
A boolean value indication whether or not the task has successfully authenticated against the payroll system.
createdAtdate
The timestamp when the task was created, stored in UTC and ISO 8601 format.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
payrollDataAvailableboolean
A boolean value indicating whether or not the user's payroll data is ready for retrieval via api.
productenum
The product relevant to the executed task. Options are:
    depositverify
statusstring
The status of the task which may be queued, processing, failed, or completed.
Example response 
{
  "data": {
    "tasks": [
      {
        "_id": "65b3f3c8b871a9626c36d103",
        "authenticated": true,
        "createdAt": "2024-01-26T18:02:55.795Z",
        "payrollDataAvailable": true,
        "product": "verify",
        "status": "completed"
      },
      {
        "_id": "65b3f3c8b871a9626c36d103",
        "authenticated": true,
        "createdAt": "2024-01-26T18:02:55.795Z",
        "failReason": "bad-credentials",
        "payrollDataAvailable": false,
        "product": "deposit",
        "status": "failed"
      }
    ]
  }
}

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