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.

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

For PayLink Manage use cases, only an identifier for the user is required when creating an AccessToken to initialize the Transact SDK.

Create Access Token

This API is how a flow through the Atomic experience is initialized. You will first create an AccessToken which is used to instantiate the Transact SDK. There are variations on how this AccessToken is created and will vary depending on the operation to be called.

For PayLink Manage use cases, you only need to pass an identifier for the user.

For PayLink Switch use cases, you will need to pass all of the data fields listed below.

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

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

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 authenticated by an end user 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

supportedboolean
Optional query parameter to filter accounts based on whether the detected company is currently supported. When received, only an array of accounts will be returned.
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.
statusenum
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.
processingboolean
A boolean value indicating whether or not the account is processing.
namestring
A name that can be used to display the account to the user. This field will be selected based of off the availablilty of data. In most cases it will either be account.name or company.name. In cases where we cannot identify an appropriate name, it will be the string Unknown Expense.
typeenum
An enum of the status of the account. Options include: linked, suggested and unsupported. If linked, then the user has logged into the account and the user's data has been retrieved. If suggested, then the account has either been selected by the user or by our automated detection engine, but the user has not logged in yet. If unsupported, then the account has been detected by our automation engine, but Atomic does not currently support integration for the account.
accountAccount
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
sourceIdstring
An ID of the account pulled from the connected system.
typeenum
An enum of the type of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
namestring
The name of the account.
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.
billingobject
An object containing the billing details of the account.
Child Properties
Optional Properties
accountNumberstring
The account number associated with the billing details for this account.
amountnumber
The amount of the bill.
dueDatestring
The upcoming due date for the bill.
autopayobject
The autopay details of the bill, if enabled.
Child Properties
Optional Properties
statusenum
The status of the autopay. Options are:
    enableddisabledpaused
cycleenum
The type of cycle the bill is paid on. Options are:
    biweeklymonthlysemimonthlyweekly
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billed item.
amountnumber
Amount of the bill.
history[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.
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.
dataobject
This object is dynamic based on the account type.
Child Properties
Optional Properties
plans[Plan]
The plans associated with the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
statusstring
The status of the plan.
titlestring
The title of the plan.
descriptionstring
The description of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangesobject
The pending changes of the plan.
Child Properties
Optional Properties
typeenum
The type of the change. One of status-update or plan-update.
changesobject
The changes to the plan.
Child Properties
Optional Properties
statusenum
The change to the status. One of active, inactive, paused or cancelled.
titlestring
The change to the title.
amountnumber
The change to the amount.
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
usage[Usage]
The usage of the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
titlestring
The title of the usage.
descriptionstring
The description of the usage.
usednumber
The quantity of the plan used.
limitnumber
The limit of the plan available to use.
unitstring
The units of usage of the plan. One of gigabytes, megabytes, minutes or kilowatts-per-hour.
lastUseddate
The last date the the plan was used.
profiles[Profile]
The profiles associated with the accounts. This field will be included if the account type is subscription.
Child Properties
Optional Properties
titlestring
The title of the profile.
lastUseddate
The date the profile was last used.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
companyCompany
An object containing details of the company to which the PayLink Account is 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 account will not have an associated company object, but it will have a managedBy object that will refer to the Amazon company in Atomic's system.
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.
managedByCompany
An object containing details of the company that manages the account. If this field is not returned, then the account is managed by the company object. An example of this would be a subscription of Max purchased through Amazon. The account for Max would have the company refer to the company Max in Atomic's system, but the managedBy object would refer to the company Amazon.
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.
suggestions[Suggestions]
An array of suggestion objects containing information about suggestions Atomic recommends presenting to the user based on the state of their account in the connected system
Child Properties
Required Properties
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
monthlySavingsnumber
The projected monthly savings if the user were to take the recommended action.
categoryenum
An enum of the types of categories of suggetions
    change-plancancel-plandowngrade-planremove-servicecommon-cancellationredundant-servicescostly-featurealternative-serviceunderutilizationhigh-interest-rate
shortDescriptionstring
A short description of the suggestion.
detailedDescriptionstring
A longer, more detailed description of the suggestion.
buttonTitlestring
A short string intended to be used as the CTA in a button for this suggestion.
identifierstring
A base64 encoded string that serves as the identifier for the suggestion.
Example response 
{
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "company": {
        "_id": "6529a6eccb8e7200085c6ef6",
        "name": "Hulu",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
            "backgroundColor": "#040405"
          },
          "color": "#040405"
        }
      },
      "managedBy": {
        "_id": "65272c415d8a530008e972df",
        "name": "Amazon",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
            "backgroundColor": "#FF9900"
          },
          "color": "#FF9900"
        }
      },
      "type": "linked",
      "status": "connected",
      "processing": false,
      "name": "Hulu",
      "account": {
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
        "type": "subscription",
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "billing": {
          "accountNumber": "8498390016491919",
          "amount": 20.46,
          "dueDate": "2024-11-20T23:59:59.000Z",
          "autopay": {
            "status": "enabled",
            "cycle": "monthly"
          },
          "items": [
            {
              "description": "Gibabit internet",
              "amount": 76.99
            },
            {
              "description": "Pay per view",
              "amount": 45.89
            }
          ],
          "history": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "paymentMethods": [
            {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            }
          ]
        },
        "data": {
          "plans": [
            {
              "sourceId": "Hulu (No Ads)",
              "status": "active",
              "title": "Family Hulu Account",
              "description": "Hulu (No Ads)",
              "freeTrial": false
            }
          ],
          "usage": [
            {
              "title": "profile",
              "description": "Test Profile"
            }
          ]
        },
        "_id": "67376c5befe988922e8aabc4"
      },
      "suggestions": [
        {
          "monthlySavings": 10,
          "category": "remove-service",
          "shortDescription": "Remove Disney Bundle",
          "detailedDescription": "You are currently paying $10 per month for the Disney Bundle. If you are not using this service, consider removing it to save $10 monthly.",
          "buttonTitle": "Remove Now",
          "identifier": "BASE64_ENCODED_ID",
          "action": {
            "type": "cancel-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": true
          }
        },
        {
          "monthlySavings": 5,
          "category": "underutilization",
          "shortDescription": "Switch to 5G Start Plan",
          "detailedDescription": "Your line is on the 5G Start plan with a $3 rate adjustment. Consider switching to a plan without the adjustment or a lower-tier plan if the current plan features are underutilized.",
          "buttonTitle": "Switch Plan",
          "action": {
            "type": "change-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": false
          }
        }
      ],
      "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.
statusenum
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.
processingboolean
A boolean value indicating whether or not the account is processing.
namestring
A name that can be used to display the account to the user. This field will be selected based of off the availablilty of data. In most cases it will either be account.name or company.name. In cases where we cannot identify an appropriate name, it will be the string Unknown Expense.
typeenum
An enum of the status of the account. Options include: linked, suggested and unsupported. If linked, then the user has logged into the account and the user's data has been retrieved. If suggested, then the account has either been selected by the user or by our automated detection engine, but the user has not logged in yet. If unsupported, then the account has been detected by our automation engine, but Atomic does not currently support integration for the account.
accountAccount
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
sourceIdstring
An ID of the account pulled from the connected system.
typeenum
An enum of the type of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
namestring
The name of the account.
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.
billingobject
An object containing the billing details of the account.
Child Properties
Optional Properties
accountNumberstring
The account number associated with the billing details for this account.
amountnumber
The amount of the bill.
dueDatestring
The upcoming due date for the bill.
autopayobject
The autopay details of the bill, if enabled.
Child Properties
Optional Properties
statusenum
The status of the autopay. Options are:
    enableddisabledpaused
cycleenum
The type of cycle the bill is paid on. Options are:
    biweeklymonthlysemimonthlyweekly
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billed item.
amountnumber
Amount of the bill.
history[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.
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.
dataobject
This object is dynamic based on the account type.
Child Properties
Optional Properties
plans[Plan]
The plans associated with the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
statusstring
The status of the plan.
titlestring
The title of the plan.
descriptionstring
The description of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangesobject
The pending changes of the plan.
Child Properties
Optional Properties
typeenum
The type of the change. One of status-update or plan-update.
changesobject
The changes to the plan.
Child Properties
Optional Properties
statusenum
The change to the status. One of active, inactive, paused or cancelled.
titlestring
The change to the title.
amountnumber
The change to the amount.
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
usage[Usage]
The usage of the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
titlestring
The title of the usage.
descriptionstring
The description of the usage.
usednumber
The quantity of the plan used.
limitnumber
The limit of the plan available to use.
unitstring
The units of usage of the plan. One of gigabytes, megabytes, minutes or kilowatts-per-hour.
lastUseddate
The last date the the plan was used.
profiles[Profile]
The profiles associated with the accounts. This field will be included if the account type is subscription.
Child Properties
Optional Properties
titlestring
The title of the profile.
lastUseddate
The date the profile was last used.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
companyCompany
An object containing details of the company to which the PayLink Account is 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 account will not have an associated company object, but it will have a managedBy object that will refer to the Amazon company in Atomic's system.
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.
managedByCompany
An object containing details of the company that manages the account. If this field is not returned, then the account is managed by the company object. An example of this would be a subscription of Max purchased through Amazon. The account for Max would have the company refer to the company Max in Atomic's system, but the managedBy object would refer to the company Amazon.
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.
suggestions[Suggestions]
An array of suggestion objects containing information about suggestions Atomic recommends presenting to the user based on the state of their account in the connected system
Child Properties
Required Properties
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
monthlySavingsnumber
The projected monthly savings if the user were to take the recommended action.
categoryenum
An enum of the types of categories of suggetions
    change-plancancel-plandowngrade-planremove-servicecommon-cancellationredundant-servicescostly-featurealternative-serviceunderutilizationhigh-interest-rate
shortDescriptionstring
A short description of the suggestion.
detailedDescriptionstring
A longer, more detailed description of the suggestion.
buttonTitlestring
A short string intended to be used as the CTA in a button for this suggestion.
identifierstring
A base64 encoded string that serves as the identifier for the suggestion.
Example response 
{
  "account": {
    "_id": "67376c5befe988922e8aabc4",
    "company": {
      "_id": "6529a6eccb8e7200085c6ef6",
      "name": "Hulu",
      "branding": {
        "logo": {
          "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
          "backgroundColor": "#040405"
        },
        "color": "#040405"
      }
    },
    "managedBy": {
      "_id": "65272c415d8a530008e972df",
      "name": "Amazon",
      "branding": {
        "logo": {
          "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
          "backgroundColor": "#FF9900"
        },
        "color": "#FF9900"
      }
    },
    "type": "linked",
    "status": "connected",
    "processing": false,
    "name": "Hulu",
    "account": {
      "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
      "type": "subscription",
      "identities": [
        {
          "firstName": "test",
          "email": "test@email.com",
          "phone": "5558675309"
        }
      ],
      "billing": {
        "accountNumber": "8498390016491919",
        "amount": 20.46,
        "dueDate": "2024-11-20T23:59:59.000Z",
        "autopay": {
          "status": "enabled",
          "cycle": "monthly"
        },
        "items": [
          {
            "description": "Gibabit internet",
            "amount": 76.99
          },
          {
            "description": "Pay per view",
            "amount": 45.89
          }
        ],
        "history": [
          {
            "date": "2024-10-20T18:00:54.761Z",
            "amount": 20.7
          },
          {
            "date": "2024-09-20T09:48:31.093Z",
            "amount": 19.38
          }
        ],
        "paymentMethods": [
          {
            "type": "card",
            "lastFour": "2345",
            "brand": "Mastercard",
            "isPrimary": true
          }
        ]
      },
      "data": {
        "plans": [
          {
            "sourceId": "Hulu (No Ads)",
            "status": "active",
            "title": "Family Hulu Account",
            "description": "Hulu (No Ads)",
            "freeTrial": false
          }
        ],
        "usage": [
          {
            "title": "profile",
            "description": "Test Profile"
          }
        ]
      },
      "_id": "67376c5befe988922e8aabc4"
    },
    "suggestions": [
      {
        "monthlySavings": 10,
        "category": "remove-service",
        "shortDescription": "Remove Disney Bundle",
        "detailedDescription": "You are currently paying $10 per month for the Disney Bundle. If you are not using this service, consider removing it to save $10 monthly.",
        "buttonTitle": "Remove Now",
        "identifier": "BASE64_ENCODED_ID",
        "action": {
          "type": "cancel-plan",
          "id": "BASE64_ENCODED_ID",
          "automated": true
        }
      },
      {
        "monthlySavings": 5,
        "category": "underutilization",
        "shortDescription": "Switch to 5G Start Plan",
        "detailedDescription": "Your line is on the 5G Start plan with a $3 rate adjustment. Consider switching to a plan without the adjustment or a lower-tier plan if the current plan features are underutilized.",
        "buttonTitle": "Switch Plan",
        "action": {
          "type": "change-plan",
          "id": "BASE64_ENCODED_ID",
          "automated": false
        }
      }
    ],
    "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
idstring
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
https://sandbox-api.atomicfi.com/pay-link/accounts

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.
statusenum
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.
processingboolean
A boolean value indicating whether or not the account is processing.
namestring
A name that can be used to display the account to the user. This field will be selected based of off the availablilty of data. In most cases it will either be account.name or company.name. In cases where we cannot identify an appropriate name, it will be the string Unknown Expense.
typeenum
An enum of the status of the account. Options include: linked, suggested and unsupported. If linked, then the user has logged into the account and the user's data has been retrieved. If suggested, then the account has either been selected by the user or by our automated detection engine, but the user has not logged in yet. If unsupported, then the account has been detected by our automation engine, but Atomic does not currently support integration for the account.
accountAccount
An object containing specific details of the account connected by the end user.
Child Properties
Required Properties
sourceIdstring
An ID of the account pulled from the connected system.
typeenum
An enum of the type of account. Options include:
    subscriptionloanpolicytelecom
Optional Properties
namestring
The name of the account.
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.
billingobject
An object containing the billing details of the account.
Child Properties
Optional Properties
accountNumberstring
The account number associated with the billing details for this account.
amountnumber
The amount of the bill.
dueDatestring
The upcoming due date for the bill.
autopayobject
The autopay details of the bill, if enabled.
Child Properties
Optional Properties
statusenum
The status of the autopay. Options are:
    enableddisabledpaused
cycleenum
The type of cycle the bill is paid on. Options are:
    biweeklymonthlysemimonthlyweekly
items[BillingItems]
Breakdown of billed items
Child Properties
Optional Properties
descriptionstring
Description of the billed item.
amountnumber
Amount of the bill.
history[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.
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.
dataobject
This object is dynamic based on the account type.
Child Properties
Optional Properties
plans[Plan]
The plans associated with the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
sourceIdstring
The source ID of the plan.
statusstring
The status of the plan.
titlestring
The title of the plan.
descriptionstring
The description of the plan.
freeTrialboolean
Whether the plan is on a free trial.
pendingChangesobject
The pending changes of the plan.
Child Properties
Optional Properties
typeenum
The type of the change. One of status-update or plan-update.
changesobject
The changes to the plan.
Child Properties
Optional Properties
statusenum
The change to the status. One of active, inactive, paused or cancelled.
titlestring
The change to the title.
amountnumber
The change to the amount.
startDatedate
The date that the changes will take effect.
endDatedate
The date that the changes will no longer be in effect.
usage[Usage]
The usage of the account. This field will be included if the account type is either subscription or telecom.
Child Properties
Optional Properties
titlestring
The title of the usage.
descriptionstring
The description of the usage.
usednumber
The quantity of the plan used.
limitnumber
The limit of the plan available to use.
unitstring
The units of usage of the plan. One of gigabytes, megabytes, minutes or kilowatts-per-hour.
lastUseddate
The last date the the plan was used.
profiles[Profile]
The profiles associated with the accounts. This field will be included if the account type is subscription.
Child Properties
Optional Properties
titlestring
The title of the profile.
lastUseddate
The date the profile was last used.
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
companyCompany
An object containing details of the company to which the PayLink Account is 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 account will not have an associated company object, but it will have a managedBy object that will refer to the Amazon company in Atomic's system.
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.
managedByCompany
An object containing details of the company that manages the account. If this field is not returned, then the account is managed by the company object. An example of this would be a subscription of Max purchased through Amazon. The account for Max would have the company refer to the company Max in Atomic's system, but the managedBy object would refer to the company Amazon.
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.
suggestions[Suggestions]
An array of suggestion objects containing information about suggestions Atomic recommends presenting to the user based on the state of their account in the connected system
Child Properties
Required Properties
actions[Actions]
The actions that can be performed on the account.
Child Properties
Optional Properties
idstring
The ID of the action.
typeenum
An enum representing the possible actions that can be performed on a PayLink Account. This comprehensive list includes all actions available for a company. However, each user will only see a subset of these actions, tailored to their specific account and plan.
    change-plancancel-planpause-planview-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.
Optional Properties
monthlySavingsnumber
The projected monthly savings if the user were to take the recommended action.
categoryenum
An enum of the types of categories of suggetions
    change-plancancel-plandowngrade-planremove-servicecommon-cancellationredundant-servicescostly-featurealternative-serviceunderutilizationhigh-interest-rate
shortDescriptionstring
A short description of the suggestion.
detailedDescriptionstring
A longer, more detailed description of the suggestion.
buttonTitlestring
A short string intended to be used as the CTA in a button for this suggestion.
identifierstring
A base64 encoded string that serves as the identifier for the suggestion.
Example response 
{
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "company": {
        "_id": "6529a6eccb8e7200085c6ef6",
        "name": "Hulu",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png",
            "backgroundColor": "#040405"
          },
          "color": "#040405"
        }
      },
      "managedBy": {
        "_id": "65272c415d8a530008e972df",
        "name": "Amazon",
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
            "backgroundColor": "#FF9900"
          },
          "color": "#FF9900"
        }
      },
      "type": "linked",
      "status": "connected",
      "processing": false,
      "name": "Hulu",
      "account": {
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
        "type": "subscription",
        "identities": [
          {
            "firstName": "test",
            "email": "test@email.com",
            "phone": "5558675309"
          }
        ],
        "billing": {
          "accountNumber": "8498390016491919",
          "amount": 20.46,
          "dueDate": "2024-11-20T23:59:59.000Z",
          "autopay": {
            "status": "enabled",
            "cycle": "monthly"
          },
          "items": [
            {
              "description": "Gibabit internet",
              "amount": 76.99
            },
            {
              "description": "Pay per view",
              "amount": 45.89
            }
          ],
          "history": [
            {
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 20.7
            },
            {
              "date": "2024-09-20T09:48:31.093Z",
              "amount": 19.38
            }
          ],
          "paymentMethods": [
            {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            }
          ]
        },
        "data": {
          "plans": [
            {
              "sourceId": "Hulu (No Ads)",
              "status": "active",
              "title": "Family Hulu Account",
              "description": "Hulu (No Ads)",
              "freeTrial": false
            }
          ],
          "usage": [
            {
              "title": "profile",
              "description": "Test Profile"
            }
          ]
        },
        "_id": "67376c5befe988922e8aabc4"
      },
      "suggestions": [
        {
          "monthlySavings": 10,
          "category": "remove-service",
          "shortDescription": "Remove Disney Bundle",
          "detailedDescription": "You are currently paying $10 per month for the Disney Bundle. If you are not using this service, consider removing it to save $10 monthly.",
          "buttonTitle": "Remove Now",
          "identifier": "BASE64_ENCODED_ID",
          "action": {
            "type": "cancel-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": true
          }
        },
        {
          "monthlySavings": 5,
          "category": "underutilization",
          "shortDescription": "Switch to 5G Start Plan",
          "detailedDescription": "Your line is on the 5G Start plan with a $3 rate adjustment. Consider switching to a plan without the adjustment or a lower-tier plan if the current plan features are underutilized.",
          "buttonTitle": "Switch Plan",
          "action": {
            "type": "change-plan",
            "id": "BASE64_ENCODED_ID",
            "automated": false
          }
        }
      ],
      "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

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