API

PayLink API Reference

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

This document serves as a reference for the APIs available in our PayLink suite of products: PayLink Switch and PayLink Manage.

Account data is available only for companies the user has connected inside the Transact SDK. See the account lifecycle before you start.

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:

IP allowlisting can be enabled for your account. When it is, requests authenticated with your API Key and Secret from any other address are rejected with a 401 and error code 40111 (Invalid IP address.). Contact your Atomic representative to set up or change the list.
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.

Mutual TLS

Optionally, Atomic can require a client certificate on connections from your servers. Requests using mutual TLS go to a dedicated hostname per environment and still carry the API Key and Secret headers above. Endpoints routed through Atomic's PCI Card Data Environment do not support mutual TLS. See the Mutual TLS for API Requests guide for requirements and setup.

Request Body Encryption

Optionally, the JSON body of a request authenticated with your API Key and Secret can be encrypted as a JWE using a public key Atomic publishes for your account. Send the encrypted payload as { "encryptedBody": "..." } and include the header below. See the Request Body Encryption guide for details.

HeaderDescription
x-enc-key-id The _id of the public key used to encrypt the body, from Get JWE Public Keys.

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 Request The request was unacceptable. This includes request bodies or parameters that fail validation (message Invalid request payload, with details in data.errors) and requests that reference a user or other resource that does not exist (for example User not found.).
401Unauthorized Missing or invalid credentials. See Authentication errors below.
403Forbidden Your credentials are valid, but the endpoint is not enabled for your account, or the public token used does not belong to the user named in the request.
404Not Found The URL does not match any endpoint. Check the path and HTTP method. A user or resource that cannot be found returns 400, not 404.
422Unprocessable EntityThe requested product is not supported by this endpoint.
429Too Many RequestsToo many requests, please try again later.
50XInternal Server ErrorAn error occurred with our API.

Error response body

Every error response uses the same JSON shape. message is a human-readable summary. code is a numeric Atomic error code whose first three digits match the HTTP status; it is present on most errors but omitted on schema validation failures. type names the kind of error, and data carries additional detail when there is any. Validation failures include data.errors, a list of readable messages, and data.verboseErrors, the raw output of the schema validator.

Example validation error 
{
  "type": "BadRequestError",
  "message": "Invalid request payload",
  "data": {
    "errors": [
      "must have required property 'identifier'"
    ],
    "verboseErrors": [
      {
        "instancePath": "",
        "schemaPath": "#/required",
        "keyword": "required",
        "params": {
          "missingProperty": "identifier"
        },
        "message": "must have required property 'identifier'"
      }
    ]
  }
}
Example error with a code 
{
  "type": "ClientError",
  "message": "User not found.",
  "code": 40011
}

Authentication errors

A 401 response includes a code that identifies the cause. The most common are listed below.

CodeMessageCause
40101Unauthorized.The API key or secret is not valid.
40103Expired.The public token has expired. Create a new access token.
40104Invalid token.The public token is not recognized or has been revoked.
40106Authentication has not been configured for this endpoint. No credentials were sent, or the credentials sent are not the kind this endpoint accepts. Most often this means a x-public-token header was sent to an endpoint that requires x-api-key and x-api-secret, or the other way around. Check the authentication listed for the endpoint.
40111Invalid IP address. IP allowlisting is enabled for your account and the request came from an address that is not on the list.

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.

If the CVV is not available in your system, you may exclude it by using the x-skip-validation: card header. This will require users to enter the CVV manually which is a higher friction user experience.

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. When testing Switch in sandbox, only use card numbers from Basis Theory's test card list .

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.
titlestring
Title for the card.
expirystring
The card expiration date in MM/YY format.
cvvstring
The CVV for the card. If unavailable, may be excluded using the
x-skip-validation: card header.
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.
externalIdstring
Used to store an identifier for the card for later matching in callbacks or webhooks.
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 or savings.
titlestring
Title or nickname for the account.
Optional Properties
externalIdstring
Used to store an identifier for the account for later matching in callbacks or webhooks.
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.
Optional Properties
address2string
Optional second line for the end user's street address
phonestring
End user's 10 digit phone number without () or -
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
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER"
}
https://sandbox-api.atomicfi.com/access-token

PayLink Switch

POST/access-token
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER",
  "cards": [
    {
      "title": "Mastercard Super Card",
      "number": "5100000000000008",
      "expiry": "12/27",
      "cvv": "123",
      "brand": "mastercard"
    }
  ],
  "accounts": [
    {
      "accountNumber": "220000000",
      "routingNumber": "110000000",
      "type": "checking",
      "title": "Premier Plus Checking"
    }
  ],
  "identity": {
    "firstName": "John",
    "lastName": "Doe",
    "postalCode": "12345",
    "address": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "phone": "5551234567",
    "email": "john.doe@example.com"
  },
  "tokenLifetime": 86400
}
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
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER",
  "cards": [
    {
      "title": "Mastercard Super Card",
      "brand": "mastercard",
      "expiry": "12/26",
      "lastFour": "1234",
      "paymentService": {
        "galileo": {
          "apiLogin": "AbC123-9999",
          "apiTransKey": "4sb62fh6w4h7w34g",
          "providerId": "9999",
          "transactionId": "123e4567-e89b-12d3-a456-426614174000",
          "accountNo": "074103447228",
          "apiUrl": "https://example.galileo.com"
        }
      }
    }
  ],
  "accounts": [
    {
      "accountNumber": "220000000",
      "routingNumber": "110000000",
      "type": "checking",
      "title": "Premier Plus Checking"
    }
  ],
  "identity": {
    "firstName": "John",
    "lastName": "Doe",
    "postalCode": "12345",
    "address": "123 Lane St",
    "address2": "Apt 987",
    "city": "Provo",
    "state": "UT",
    "phone": "8011234576",
    "email": "john@example.com"
  }
}
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
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER"
}
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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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.

Use this lookup when you need to identify a merchant. If you need additional metadata for a specific result, use the returned _id with Company Details.

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
{
  "query": "Netflix",
  "scopes": [
    "pay-link"
  ]
}
https://sandbox-api.atomicfi.com/company/search

Response

Successfully querying the Company search endpoint will return a payload with a data array of Company objects.

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action until it has been restored.
_idstring
Unique identifier for the company.
branding.logo.backgroundColorstring
Background color for the company logo.
branding.logo.urlstring
Logo for the company, in PNG format.
branding.colorstring
Branding color for the company.
tags[string]
Tags with which a company is associated.
namestring
Company name.
connector.capabilities.supportedPaymentMethods[string]
List of supported payment method types for the switch product. This includes card or bank. Omitted when none are defined.
connector.availableProducts[string]
A list of compatible products.
statusstring
Possible values include operational or under-maintenance.
availableProducts[string]
A list of compatible products.
availableActions[string]
A list of actions currently available for the company.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
Example response 
{
  "success": true,
  "data": [
    {
      "_id": "64ecca15ec669e000851d5d2",
      "branding": {
        "logo": {
          "backgroundColor": "#000000",
          "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
        },
        "color": "#000000"
      },
      "alternativeConnectors": [],
      "unsupportedProducts": [],
      "tags": [],
      "name": "Netflix",
      "subtext": "",
      "connector": {
        "_id": "64ecc6bce71fea0008835583",
        "capabilities": {
          "distributionTypes": [],
          "blockedRoutingNumbers": [],
          "supportedPaymentMethods": [
            "card"
          ]
        },
        "availableProducts": [
          "action",
          "switch",
          "present"
        ]
      },
      "status": "operational",
      "createdAt": "2023-08-28T16:23:49.641Z",
      "coAuthConnectors": [],
      "score": 10.234648704528809,
      "availableProducts": [
        "action",
        "switch",
        "present"
      ],
      "availableActions": [
        "cancel-plan",
        "change-plan",
        "pause-plan",
        "switch"
      ]
    }
  ]
}

Company List

Use this endpoint to retrieve the list of companies available to your account. It is well suited for building a static merchant catalog, pulling a snapshot of the catalog for design or planning workflows, or pre-validating which merchants your customers can connect.

Results are sorted by popularity, with the most frequently selected companies appearing first. Popularity is based on how often users select each company in Transact over a rolling two-week window.

By default the list returns merchants that can be connected directly. Pass includeManaged=true to also include managed companies — merchants billed through a managing company such as Amazon or Apple — and add a managedBy array to each company identifying which companies can manage it.

For typeahead-style lookup by name, use Company Search. For a single company by _id, use Company Details.

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

These are query string parameters on the request URL (this endpoint is GET, so parameters are not sent as a JSON body). Pass a single value with product, scope, or action. Use the plural key actions and repeat the key when you need more than one action type.

Example: /company/list?scope=pay-link&product=switch

Pagination with total row count: /company/list?scope=pay-link&limit=50&skip=0&includeTotal=true

Include managed companies: /company/list?scope=pay-link&includeManaged=true

productenumOptional
Filters to companies that support the specified product.

switch — /company/list?product=switch
present — /company/list?product=present
scopeenumOptional
Filters companies by product suite. When omitted, your account’s configured scopes are applied.

pay-link — /company/list?scope=pay-link
    pay-link
actionstringOptional
Filters Pay Link companies by a single supported account-level action type. Use actions when the request must require several action types at once.

switch — /company/list?action=switch
connect-account — /company/list?action=connect-account
actions[string]Optional
Multiple action filter: companies must support all listed action types. Repeat the query key per value. Prefer action when one action type is enough.

/company/list?actions=switch&actions=connect-account
limitnumberOptional
Maximum number of companies to return per request. Must be between 1 and 100. Defaults to 100.
skipnumberOptional
Number of records to skip before returning results, for cursor-style pagination. Must be 0 or greater. Defaults to 0.
includeTotalbooleanOptional
When true, the response includes a meta object with total, limit, and skip for building paginated catalogs. Accepts formincludeTotal=true.
includeManagedbooleanOptional
When true, include managed companies — merchants billed through a managing company (for example a channel billed through Amazon or Apple) that are otherwise hidden from the list — and add a managedBy array to each company identifying which companies can manage it. Accepts form includeManaged=true.
GET/company/list
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/company/list

Response

A successful response returns a payload with a data array of Company objects. When includeTotal is omitted or false, the body is { success, data } only. When includeTotal is true, the body also includes a meta object with total (count of companies matching the request filters), limit, and skip echoing the pagination parameters used for the request (with defaults applied).

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action until it has been restored.

Each item includes connector.capabilities.supportedPaymentMethods when the supported payment mehtods so you can tell whether a merchant supports options such as card or bank without calling Company Details for every row.

When includeManaged=true is passed, each company includes a managedBy array of { id, name } objects — the companies that can manage that company's subscription. It contains a self-reference when the company can be managed directly, and is omitted when the parameter is not set.

data[object]
Array of company objects matching the request filters.
metaobject
Pagination metadata. Present only when includeTotal was set to true on the request.
Child Properties
Optional Properties
totalnumber
Number of companies matching the same filters as this request (before applying limit and skip to the returned data array).
limitnumber
Maximum number of companies returned in data for this response (resolved default or requested value).
skipnumber
Number of matching records skipped before the first item in data (resolved default or requested value).
_idstring
Unique identifier for the company.
namestring
Company name.
branding.logo.urlstring
Logo for the company, in PNG format.
branding.colorstring
Branding color for the company.
tags[string]
Tags with which a company is associated. Possible values include subscription, streaming, and telecom.
connector.availableProducts[string]
A list of compatible products.
connector.capabilities.supportedPaymentMethods[string]
List of supported payment method types for the switch product. This includes card or bank. Omitted when none are defined.
statusstring
Possible values include operational, under-maintenance, and disabled.
availableProducts[string]
A list of compatible products.
availableActions[string]
A list of actions currently available for the company.
managedBy[object]
The companies that can manage this company’s subscription. Included only when includeManaged=true is passed on the request. Contains a self-reference when the company can be managed directly (for example Netflix managed by Netflix).
Child Properties
Optional Properties
idstring
Unique identifier of a company that can manage this company’s subscription.
namestring
Display name of the managing company.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
Example response 
{
  "success": true,
  "data": [
    {
      "_id": "64ecca15ec669e000851d5d2",
      "name": "Netflix",
      "status": "operational",
      "createdAt": "2023-08-28T15:11:33.612Z",
      "tags": [
        "streaming",
        "subscription"
      ],
      "branding": {
        "logo": {
          "url": "https://atomicfi-public-production.s3.amazonaws.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
        },
        "color": "#000000"
      },
      "connector": {
        "_id": "64ecc6bce71fea0008835583",
        "availableProducts": [
          "switch",
          "present"
        ],
        "capabilities": {
          "distributionTypes": [],
          "supportedPaymentMethods": [
            "card",
            "bank"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "availableProducts": [
        "switch",
        "present"
      ],
      "availableActions": [
        "switch",
        "connect-account"
      ]
    },
    {
      "_id": "60ca3b42430aba0008f617cb",
      "name": "Acme Wireless",
      "status": "operational",
      "createdAt": "2021-06-16T20:18:10.123Z",
      "tags": [
        "telecom",
        "subscription"
      ],
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/logos/acme-wireless.png"
        },
        "color": "#1A73E8"
      },
      "connector": {
        "_id": "507f1f77bcf86cd799439012",
        "availableProducts": [
          "switch"
        ],
        "capabilities": {
          "distributionTypes": [],
          "supportedPaymentMethods": [
            "card"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "availableProducts": [
        "switch"
      ],
      "availableActions": [
        "switch"
      ]
    }
  ]
}
Example response with pagination metadata 
{
  "success": true,
  "data": [
    {
      "_id": "64ecca15ec669e000851d5d2",
      "name": "Netflix",
      "status": "operational",
      "createdAt": "2023-08-28T15:11:33.612Z",
      "tags": [
        "streaming",
        "subscription"
      ],
      "branding": {
        "logo": {
          "url": "https://atomicfi-public-production.s3.amazonaws.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
        },
        "color": "#000000"
      },
      "connector": {
        "_id": "64ecc6bce71fea0008835583",
        "availableProducts": [
          "switch",
          "present"
        ],
        "capabilities": {
          "distributionTypes": [],
          "supportedPaymentMethods": [
            "card",
            "bank"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "availableProducts": [
        "switch",
        "present"
      ],
      "availableActions": [
        "switch",
        "cancel-plan"
      ]
    }
  ],
  "meta": {
    "total": 247,
    "limit": 50,
    "skip": 0
  }
}
Example response with managedBy 
{
  "success": true,
  "data": [
    {
      "_id": "64ecca15ec669e000851d5d2",
      "name": "Netflix",
      "status": "operational",
      "createdAt": "2023-08-28T15:11:33.612Z",
      "tags": [
        "streaming",
        "subscription"
      ],
      "branding": {
        "logo": {
          "url": "https://atomicfi-public-production.s3.amazonaws.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
        },
        "color": "#000000"
      },
      "connector": {
        "_id": "64ecc6bce71fea0008835583",
        "availableProducts": [
          "switch",
          "present"
        ],
        "capabilities": {
          "distributionTypes": [],
          "supportedPaymentMethods": [
            "card"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "managedBy": [
        {
          "id": "6536d5456f184e00095f9df8",
          "name": "Apple"
        },
        {
          "id": "64ecca15ec669e000851d5d2",
          "name": "Netflix"
        }
      ],
      "availableProducts": [
        "switch",
        "present"
      ],
      "availableActions": [
        "switch",
        "connect-account"
      ]
    },
    {
      "_id": "67eb0c666ebc21e2aef61214",
      "name": "The Washington Post",
      "status": "operational",
      "createdAt": "2025-03-31T21:43:02.495Z",
      "tags": [
        "news",
        "subscription"
      ],
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/logos/washington-post.png"
        },
        "color": "#000000"
      },
      "connector": {
        "_id": "65298b4128c44100096f84b9",
        "availableProducts": [
          "switch",
          "present"
        ],
        "capabilities": {
          "distributionTypes": [],
          "supportedPaymentMethods": [
            "card"
          ]
        }
      },
      "alternativeConnectors": [],
      "coAuthConnectors": [],
      "managedBy": [
        {
          "id": "6536d5456f184e00095f9df8",
          "name": "Apple"
        },
        {
          "id": "65272c415d8a530008e972df",
          "name": "Amazon"
        }
      ],
      "availableProducts": [
        "switch",
        "present"
      ],
      "availableActions": [
        "switch"
      ]
    }
  ]
}

Company Details

Use this endpoint to retrieve all information Atomic has for a specific company.

The response includes company metadata such as branding, status, search information, and connector capabilities.

This can be useful when you need to render company branding in your own UI, evaluate whether a company is available before launching a flow, or inspect connector capabilities such as supported payment methods and authentication methods.

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.

Use this API to determine whether a company supports the payment methods a user has before launching them into the Single Switch experience for PayLink Switch.

Required Properties

companyIdstring
The _id of the company. Use the value returned by Company Search or another Atomic company lookup.
GET/company/:companyId/details
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

https://sandbox-api.atomicfi.com/company/:companyId/details

Response

A successful request returns the public company details payload for the specified company, including status, search metadata, connector capabilities, supported payment methods, supported authentication methods, and co-auth connector information.

When a company is under-maintenance, the affected products and actions will be listed in the response field, underMaintenanceProductsAndActions. Users will be unable to initiate authentication for the respective product or action until it has been restored.
_idstring
Unique identifier for the company.
namestring
Company name.
subtextstring
Optional descriptive text shown alongside the company name.
createdAtstring
Timestamp for when the company record was created.
brandingobject
Branding metadata for the company.
Child Properties
Optional Properties
logoobject
Logo metadata for the company.
Child Properties
Optional Properties
urlstring
URL for the company logo.
colorstring
Primary branding color used for the company.
tags[string]
Company tags associated with the merchant.
statusstring
Possible values include operational, under-maintenance, and disabled.
searchstring
Search text used to match the company in company lookup flows.
keywords[string]
Supplemental search keywords associated with the company.
isConfigurableConnectorboolean
Indicates whether the selected connector can be configured.
alternativeConnectors[]
Alternative connector options available for the company, if any.
coAuthConnectors[]
Co-auth connector options available for the company, if any.
franchiseParentobject
Metadata for the franchise parent company when the merchant is a franchise child.
Child Properties
Optional Properties
_idstring
Unique identifier for the franchise parent company.
namestring
Display name for the franchise parent company.
brandingobject
Branding metadata for the franchise parent company.
connectorobject
Connector metadata for this company.
Child Properties
Optional Properties
_idstring
Unique identifier for the connector.
namestring
Display name for the connector.
createdAtstring
Timestamp for when the connector record was created.
brandingobject
Branding metadata for the connector.
availableProducts[string]
Products that can be launched with this connector.
capabilitiesobject
Connector capabilities exposed by the public API.
Child Properties
Optional Properties
authenticationMethods[string]
Authentication methods supported by the connector. In this response, uplink is normalized to true-auth.
supportedPaymentMethods[string]
Payment method types supported by the connector. Use this field before Single Switch to confirm whether the merchant supports card or bank.
availableProducts[string]
A list of compatible products.
availableActions[string]
A list of actions currently available for the company.
underMaintenanceProductsAndActions[string]Optional
A list of products and actions currently under maintenance for the company.
Example response 
{
  "success": true,
  "data": {
    "_id": "60ca3b42430aba0008f617cb",
    "createdAt": "2021-06-16T20:18:10.123Z",
    "branding": {
      "logo": {
        "url": "https://cdn.atomicfi.com/logos/acme-wireless.png"
      },
      "color": "#1A73E8"
    },
    "name": "Acme Wireless",
    "subtext": "Mobile service",
    "tags": [
      "wireless",
      "subscription"
    ],
    "alternativeConnectors": [],
    "isConfigurableConnector": false,
    "coAuthConnectors": [],
    "search": "acme wireless acme",
    "keywords": [
      "mobile",
      "phone",
      "autopay"
    ],
    "connector": {
      "_id": "507f1f77bcf86cd799439012",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/logos/acme-wireless.png",
          "backgroundColor": "#FFFFFF"
        },
        "color": "#1A73E8"
      },
      "availableProducts": [
        "switch"
      ],
      "name": "Acme Wireless",
      "createdAt": "2021-06-16T20:18:10.123Z",
      "capabilities": {
        "authenticationMethods": [
          "true-auth",
          "standard-auth"
        ],
        "supportedPaymentMethods": [
          "card",
          "bank"
        ]
      }
    },
    "status": "operational",
    "franchiseParent": {
      "_id": "60ca3b42430aba0008f60000",
      "name": "Acme Holdings",
      "branding": {
        "logo": {
          "url": "https://cdn.atomicfi.com/logos/acme-holdings.png"
        }
      }
    },
    "availableProducts": [
      "switch"
    ],
    "availableActions": [
      "switch"
    ]
  }
}

Actions for Company

Actions allow both automated and interactive ways for the user to manage their expenses. This endpoint provides a way to look up what Actions are available for the current user based on a Company identifier, regardless of whether the user has connected an Account for that Company.

There are several ways to look up Actions. For more information, see the guide on Executing Actions.

Get Actions for Company

This endpoint returns the available Actions supported for the given Company for the current 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

companyIdstring
The _id of the company. Use the value returned by Company Search or another Atomic company lookup.

Optional Properties

hideDisabledActionsboolean
Whether to hide actions that are temporarily disabled for maintenance. By default, these actions are included.
ignorePlanStatusboolean
Whether to ignore plan status when determining available actions. By default, pause-plan and cancel-plan actions are filtered out for plans that are already paused or cancelled.
includeTestFlowsboolean
Whether to include test flows for certain actions. This is only available for test accounts created with test-good credentials.
GET/pay-link/actions-for-company/:companyId
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/actions-for-company/:companyId

Response

The response includes a list of Action objects.

actions[Actions]
An array of Action objects.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
Example response 
{
  "actions": [
    {
      "actionId": "eyJ0eXBlIjoidmlldy1hY2NvdW50IiwidXJsIjoiaHR0cHM6Ly9uZXRmbGl4LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDY1YWMzYTMtYjNlZS00MTRmLTg3YjUtNWNjMzZiZjFjOWU0IiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
      "type": "view-account",
      "automated": false,
      "disabled": false
    },
    {
      "actionId": "eyJ0eXBlIjoicmVmcmVzaCIsImZsb3ciOiJyZWZyZXNoIiwiYWNjb3VudCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDY1YWMzYTMtYjNlZS00MTRmLTg3YjUtNWNjMzZiZjFjOWU0IiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
      "type": "refresh",
      "automated": true,
      "disabled": false
    },
    {
      "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEifSwiYmlsbCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEiLCJzb3VyY2VJZCI6ImZjNjRiNmUxLTY5NWMtNDFhZS04ODk1LWY2MGY0ODRiNDcyOCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDY1YWMzYTMtYjNlZS00MTRmLTg3YjUtNWNjMzZiZjFjOWU0IiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
      "type": "change-plan",
      "automated": false,
      "disabled": false,
      "bill": {
        "_id": "69fb5c20e95230d715de5b3e",
        "name": "Netflix",
        "companyId": "64ecca15ec669e000851d5d2"
      }
    },
    {
      "actionId": "eyJ0eXBlIjoicGF1c2UtcGxhbiIsImZsb3ciOiJwYXVzZS1wbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEifSwiYmlsbCI6eyJfaWQiOiI2OWYxMzkyNjg2ZGQ2OWE1MTJhODZhODEiLCJzb3VyY2VJZCI6ImZjNjRiNmUxLTY5NWMtNDFhZS04ODk1LWY2MGY0ODRiNDcyOCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDY1YWMzYTMtYjNlZS00MTRmLTg3YjUtNWNjMzZiZjFjOWU0IiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
      "type": "pause-plan",
      "automated": true,
      "disabled": false,
      "bill": {
        "_id": "69fb5c20e95230d715de5b3e",
        "name": "Netflix",
        "companyId": "64ecca15ec669e000851d5d2"
      }
    },
    {
      "actionId": "eyJ0eXBlIjoiY2FuY2VsLXBsYW4iLCJmbG93IjoiY2FuY2VsLXBsYW4iLCJhY2NvdW50Ijp7Il9pZCI6IjY5ZjEzOTI2ODZkZDY5YTUxMmE4NmE4MSJ9LCJiaWxsIjp7Il9pZCI6IjY5ZjEzOTI2ODZkZDY5YTUxMmE4NmE4MSIsInNvdXJjZUlkIjoiZmM2NGI2ZTEtNjk1Yy00MWFlLTg4OTUtZjYwZjQ4NGI0NzI4In0sInBsYW4iOnsiZGVzY3JpcHRpb24iOiJTdGFuZGFyZCJ9LCJhY2NvdW50U3RhdHVzIjoibGlua2VkIiwiY29tcGFueUlkIjoiNjRlY2NhMTVlYzY2OWUwMDA4NTFkNWQyIiwicHVibGljVG9rZW4iOiIwNjVhYzNhMy1iM2VlLTQxNGYtODdiNS01Y2MzNmJmMWM5ZTQiLCJpc1Rlc3RBY2NvdW50IjpmYWxzZX0=",
      "type": "cancel-plan",
      "automated": true,
      "disabled": false,
      "bill": {
        "_id": "69fb5c20e95230d715de5b3e",
        "name": "Netflix",
        "companyId": "64ecca15ec669e000851d5d2"
      }
    }
  ]
}

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.

Each response is a snapshot taken at lastSyncedAt. An account with a connectionStatus of disconnected has lost its session and needs the user to sign in again before it can be read or acted on. See the account lifecycle.

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

companyIdstring
Optional query parameter to filter accounts based on the company ID.
hideDisabledActionsboolean
Whether to hide actions that are temporarily disabled for maintenance. By default, these actions are included.
ignorePlanStatusboolean
Whether to ignore plan status when determining available actions. By default, pause-plan and cancel-plan actions are filtered out for plans that are already paused or cancelled.
includeTestFlowsboolean
Whether to include test flows for certain actions. This is only available for test accounts created with test-good credentials.
GET/pay-link/accounts
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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

Response

The response includes an array of Account objects with nested objects containing information such as company, bill, and order data, as well as relevant actions a user can take on their account. Check connectionStatus and lastSyncedAt before relying on the data; a disconnected account needs the user to sign in again.

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, a connection attempt has not been made. If the account is connected then a successful connection attempt has been made the account can be accessed. If the account is disconnected, then we have lost connection to the account and it can no longer be accessed.
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. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
bills[Bills]
The recurring expenses of an account pulled directly from the connected system, such as the subscription on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
expenseIdstring
The id of the expense related to the bill, for determining when a bill and a recurring financial transaction represent the same expense.
sourceIdstring
The id of the bill as identified in 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.
billingCycleenum
The recurring cycle of the bill.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
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 bill.
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]
The actions that can be performed on the bill.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the bill.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
expenses[Expenses]
The recurring expenses of an account, both pulled directly from the connected system and based on the user's financial transactions.
Child Properties
Required Properties
_idstring
Unique identifier for the expense.
Optional Properties
billIdstring
The identifier of the associated bill, if the underlying expense is a bill.
recurringFinancialTransactionIdstring
The identifier of the associated bill, if the underlying expense is a recurring financial transaction.
namestring
The name of the expense.
amountnumber
The amount of the expense.
amountDisclaimerstring
A disclaimer about how the expense amount was determined.
autopayStatusenum
Whether the expense has autopay enabled. One of enabled, disabled, or paused.
billingCycleenum
The recurring cycle of the expense.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The due date of the expense.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the expense.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
paymentMethodPaymentMethod
The payment method of the expense, 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.
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.
profiles[Profiles]
The profiles associated with the expense.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
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 expense.
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.
actions[Actions]
The actions that can be performed on the expense.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the expense.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Optional Properties
lastSyncedAtdate
The date the user's data was last synced, provided in ISO format.
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.
recurringFinancialTransactionsRecurringFinancialTransactions
The recurring expenses of an account based on the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
amountnumber
The amount of the recurring financial transaction, typically the same as the amount of the most recent financial transaction.
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
expenseIdstring
The id of the expense related to the recurring financial transaction, for determining when a bill and a recurring financial transaction represent the same expense.
Optional Properties
billingCycleenum
The billing cycle of the recurring financial transaction
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The next billing date of the recurring financial transaction.
companyCompany
An object containing details of the company for the recurring financial transaction. This field may not be returned in cases in which the company for the recurring financial transaction does not exist 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.
accountIdstring
The account that owns the recurring financial transaction
actions[Actions]
The actions that can be performed on the recurring financial transaction.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
orders[Orders]
An array of objects containing the purchase orders associated with the account. Only returned when order monitoring is enabled for your account.
Child Properties
Required Properties
_idstring
Unique identifier for the order.
sourceIdstring
The identifier of the order in the the connected system.
datestring
The date the order was placed.
amountnumber
The total amount of the order.
lineItems[LineItems]
An array of objects containing the itemized amount breakdown of the order.
Child Properties
Optional Properties
descriptionstring
Description of the line item.
amountnumber
Amount of the line item.
paymentMethodPaymentMethod
The payment method of the order.
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.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the order. May be empty if the user used a gift card to complete the purchase.
Child Properties
Required Properties
paymentMethodPaymentMethod
The payment method of the order.
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.
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
products[Products]
An array of objects containing the products purchased in this order.
Child Properties
Required Properties
descriptionstring
The description of the purchased product.
amountnumber
The amount of the purchased product.
quantityobject
The purchased quantity of the product.
Child Properties
Required Properties
valuenumber
Optional Properties
unitstring
The source system's quantity unit for the product.
Optional Properties
sourceIdstring
The id of the product in the source system.
returnBydate
The max date for which the purchased product can be returned.
suggestions[Suggestions]
Suggestions about actions that can be performed on the account.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Example response 
{
  "accounts": [
    {
      "_id": "67376c5befe988922e8aabc4",
      "processing": false,
      "connectionStatus": "connected",
      "lastSyncedAt": "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",
          "actionId": "BASE64_ENCODED_ID",
          "automated": false,
          "disabled": false
        },
        {
          "type": "refresh",
          "actionId": "BASE64_ENCODED_ID",
          "automated": true,
          "disabled": false
        }
      ],
      "bills": [
        {
          "_id": "67376c5befe988922e8adef5",
          "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
          "name": "Hulu",
          "amount": 24.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": "view-account",
              "actionId": "BASE64_ENCODED_ID",
              "automated": false,
              "disabled": false
            },
            {
              "type": "refresh",
              "actionId": "BASE64_ENCODED_ID",
              "automated": true,
              "disabled": false
            },
            {
              "type": "change-plan",
              "actionId": "BASE64_ENCODED_ID",
              "automated": false,
              "disabled": false,
              "bill": {
                "_id": "67376c5befe988922e8adef5",
                "name": "Hulu",
                "companyId": "6529a6eccb8e7200085c6ef6"
              }
            },
            {
              "type": "cancel-plan",
              "actionId": "BASE64_ENCODED_ID",
              "automated": true,
              "disabled": false,
              "bill": {
                "_id": "67376c5befe988922e8adef5",
                "name": "Hulu",
                "companyId": "6529a6eccb8e7200085c6ef6"
              }
            },
            {
              "type": "pause-plan",
              "actionId": "BASE64_ENCODED_ID",
              "automated": true,
              "disabled": false,
              "bill": {
                "_id": "67376c5befe988922e8adef5",
                "name": "Hulu",
                "companyId": "6529a6eccb8e7200085c6ef6"
              }
            }
          ]
        }
      ],
      "orders": [
        {
          "_id": "67376c5befe988922e8adef6",
          "sourceId": "112-2968911-3747422",
          "date": "2024-10-20T18:00:54.761Z",
          "amount": 13.36,
          "lineItems": [
            {
              "description": "Item(s) Subtotal",
              "amount": 12.49
            },
            {
              "description": "Shipping & Handling",
              "amount": 0
            },
            {
              "description": "Estimated tax to be collected",
              "amount": 0.87
            }
          ],
          "paymentMethod": {
            "type": "card",
            "lastFour": "2345",
            "brand": "Mastercard",
            "isPrimary": true
          },
          "paymentHistory": [
            {
              "paymentMethod": {
                "type": "card",
                "lastFour": "2345",
                "brand": "Mastercard",
                "isPrimary": true
              },
              "date": "2024-10-20T18:00:54.761Z",
              "amount": 13.36
            }
          ],
          "products": [
            {
              "sourceId": "B1XX8WVCRJ",
              "description": "AAA Alkaline High-Performance Batteries",
              "amount": 12.49,
              "returnBy": "2024-12-19T23:59:59.000Z",
              "quantity": {
                "value": 1
              }
            }
          ]
        }
      ],
      "recurringFinancialTransactions": [
        {
          "_id": "6903d4ae324b0a223b44ac7c",
          "company": {
            "_id": "65272c415d8a530008e972df",
            "name": "Amazon",
            "branding": {
              "logo": {
                "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
                "backgroundColor": "#FF9900"
              },
              "color": "#FF9900"
            }
          },
          "financialTransactions": [
            {
              "identifier": "12345",
              "description": "Amazon",
              "amount": 24.99,
              "date": "2024-01-01T00:00:00.000Z",
              "_id": "68c1c9497306bf98e3daabe3"
            },
            {
              "identifier": "12346",
              "description": "Amazon",
              "amount": 24.99,
              "date": "2024-02-01T00:00:00.000Z",
              "_id": "68c1c9497306bf98e3daabe4"
            },
            {
              "identifier": "12347",
              "description": "Amazon",
              "amount": 24.99,
              "date": "2024-03-01T00:00:00.000Z",
              "_id": "68c1c9497306bf98e3daabe5"
            }
          ],
          "dueDate": "2024-04-01T00:00:00.000Z",
          "accountId": "67376c5befe988922e8aabc4",
          "name": "Amazon",
          "amount": 24.99,
          "billingCycle": "monthly",
          "expenseId": "6903d4ae324b0a223b44ac7d",
          "actions": []
        }
      ],
      "suggestions": [
        {
          "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsImJpbGxJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsInBsYW5JZCI6IjUyMDAifQ==",
          "monthlySavings": 9.99,
          "category": "better-plan-available",
          "text": {
            "listTitle": "$120/year",
            "listDescription": "Hulu (Ads) costs less and may suit your needs.",
            "detailTitle": "Save $120 per year on Hulu",
            "detailDescription": "Your current plan, Hulu (No Ads) ($17.99 monthly), is more expensive than another plan that includes ads, Hulu (Ads) ($7.99 monthly).",
            "cta": "Change Plan"
          },
          "action": {
            "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3NlY3VyZS5odWx1LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2NzM3NmM1YmVmZTk4ODkyMmU4YWFiYzQifSwiYmlsbCI6eyJfaWQiOiI2NzM3NmM1YmVmZTk4ODkyMmU4YWRlZjUiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NSJ9LCJhY2NvdW50U3RhdHVzIjoibGlua2VkIiwiY29tcGFueUlkIjoiNjUyOWE2ZWNjYjhlNzIwMDA4NWM2ZWY2IiwicHVibGljVG9rZW4iOiJkMzg1ZjczOS1mMzM3LTQxMGYtOWFlNy0zNWFkOTc1Y2NkMWUiLCJpc1Rlc3RBY2NvdW50IjpmYWxzZX0=",
            "type": "change-plan",
            "automated": false,
            "disabled": false,
            "bill": {
              "_id": "67376c5befe988922e8adef5",
              "name": "Hulu",
              "companyId": "6529a6eccb8e7200085c6ef6"
            }
          },
          "references": [
            {
              "company": {
                "_id": "6529a6eccb8e7200085c6ef6",
                "name": "Hulu",
                "branding": {
                  "color": "#040405",
                  "logo": {
                    "backgroundColor": "#040405",
                    "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png"
                  }
                }
              },
              "account": {
                "_id": "67376c5befe988922e8aabc4",
                "companyId": "6529a6eccb8e7200085c6ef6",
                "isConnected": true
              },
              "bill": {
                "_id": "67376c5befe988922e8adef5",
                "companyId": "6529a6eccb8e7200085c6ef6",
                "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685"
              }
            }
          ]
        }
      ]
    }
  ]
}

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.

Optional Properties

hideDisabledActionsboolean
Whether to hide actions that are temporarily disabled for maintenance. By default, these actions are included.
ignorePlanStatusboolean
Whether to ignore plan status when determining available actions. By default, pause-plan and cancel-plan actions are filtered out for plans that are already paused or cancelled.
includeTestFlowsboolean
Whether to include test flows for certain actions. This is only available for test accounts created with test-good credentials.
GET/pay-link/accounts/:id
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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

Response

The response includes an Account object with nested objects containing information such as company, bill, and order data, as well as relevant actions a user can take on their account.

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, a connection attempt has not been made. If the account is connected then a successful connection attempt has been made the account can be accessed. If the account is disconnected, then we have lost connection to the account and it can no longer be accessed.
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. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
bills[Bills]
The recurring expenses of an account pulled directly from the connected system, such as the subscription on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
expenseIdstring
The id of the expense related to the bill, for determining when a bill and a recurring financial transaction represent the same expense.
sourceIdstring
The id of the bill as identified in 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.
billingCycleenum
The recurring cycle of the bill.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
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 bill.
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]
The actions that can be performed on the bill.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the bill.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
expenses[Expenses]
The recurring expenses of an account, both pulled directly from the connected system and based on the user's financial transactions.
Child Properties
Required Properties
_idstring
Unique identifier for the expense.
Optional Properties
billIdstring
The identifier of the associated bill, if the underlying expense is a bill.
recurringFinancialTransactionIdstring
The identifier of the associated bill, if the underlying expense is a recurring financial transaction.
namestring
The name of the expense.
amountnumber
The amount of the expense.
amountDisclaimerstring
A disclaimer about how the expense amount was determined.
autopayStatusenum
Whether the expense has autopay enabled. One of enabled, disabled, or paused.
billingCycleenum
The recurring cycle of the expense.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The due date of the expense.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the expense.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
paymentMethodPaymentMethod
The payment method of the expense, 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.
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.
profiles[Profiles]
The profiles associated with the expense.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
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 expense.
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.
actions[Actions]
The actions that can be performed on the expense.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the expense.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Optional Properties
lastSyncedAtdate
The date the user's data was last synced, provided in ISO format.
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.
recurringFinancialTransactionsRecurringFinancialTransactions
The recurring expenses of an account based on the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
amountnumber
The amount of the recurring financial transaction, typically the same as the amount of the most recent financial transaction.
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
expenseIdstring
The id of the expense related to the recurring financial transaction, for determining when a bill and a recurring financial transaction represent the same expense.
Optional Properties
billingCycleenum
The billing cycle of the recurring financial transaction
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The next billing date of the recurring financial transaction.
companyCompany
An object containing details of the company for the recurring financial transaction. This field may not be returned in cases in which the company for the recurring financial transaction does not exist 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.
accountIdstring
The account that owns the recurring financial transaction
actions[Actions]
The actions that can be performed on the recurring financial transaction.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
orders[Orders]
An array of objects containing the purchase orders associated with the account. Only returned when order monitoring is enabled for your account.
Child Properties
Required Properties
_idstring
Unique identifier for the order.
sourceIdstring
The identifier of the order in the the connected system.
datestring
The date the order was placed.
amountnumber
The total amount of the order.
lineItems[LineItems]
An array of objects containing the itemized amount breakdown of the order.
Child Properties
Optional Properties
descriptionstring
Description of the line item.
amountnumber
Amount of the line item.
paymentMethodPaymentMethod
The payment method of the order.
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.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the order. May be empty if the user used a gift card to complete the purchase.
Child Properties
Required Properties
paymentMethodPaymentMethod
The payment method of the order.
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.
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
products[Products]
An array of objects containing the products purchased in this order.
Child Properties
Required Properties
descriptionstring
The description of the purchased product.
amountnumber
The amount of the purchased product.
quantityobject
The purchased quantity of the product.
Child Properties
Required Properties
valuenumber
Optional Properties
unitstring
The source system's quantity unit for the product.
Optional Properties
sourceIdstring
The id of the product in the source system.
returnBydate
The max date for which the purchased product can be returned.
suggestions[Suggestions]
Suggestions about actions that can be performed on the account.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Example response 
{
  "account": {
    "_id": "67376c5befe988922e8aabc4",
    "processing": false,
    "connectionStatus": "connected",
    "lastSyncedAt": "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",
        "actionId": "BASE64_ENCODED_ID",
        "automated": false,
        "disabled": false
      },
      {
        "type": "refresh",
        "actionId": "BASE64_ENCODED_ID",
        "automated": true,
        "disabled": false
      }
    ],
    "bills": [
      {
        "_id": "67376c5befe988922e8adef5",
        "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685",
        "name": "Hulu",
        "amount": 24.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": "view-account",
            "actionId": "BASE64_ENCODED_ID",
            "automated": false,
            "disabled": false
          },
          {
            "type": "refresh",
            "actionId": "BASE64_ENCODED_ID",
            "automated": true,
            "disabled": false
          },
          {
            "type": "change-plan",
            "actionId": "BASE64_ENCODED_ID",
            "automated": false,
            "disabled": false,
            "bill": {
              "_id": "67376c5befe988922e8adef5",
              "name": "Hulu",
              "companyId": "6529a6eccb8e7200085c6ef6"
            }
          },
          {
            "type": "cancel-plan",
            "actionId": "BASE64_ENCODED_ID",
            "automated": true,
            "disabled": false,
            "bill": {
              "_id": "67376c5befe988922e8adef5",
              "name": "Hulu",
              "companyId": "6529a6eccb8e7200085c6ef6"
            }
          },
          {
            "type": "pause-plan",
            "actionId": "BASE64_ENCODED_ID",
            "automated": true,
            "disabled": false,
            "bill": {
              "_id": "67376c5befe988922e8adef5",
              "name": "Hulu",
              "companyId": "6529a6eccb8e7200085c6ef6"
            }
          }
        ]
      }
    ],
    "orders": [
      {
        "_id": "67376c5befe988922e8adef6",
        "sourceId": "112-2968911-3747422",
        "date": "2024-10-20T18:00:54.761Z",
        "amount": 13.36,
        "lineItems": [
          {
            "description": "Item(s) Subtotal",
            "amount": 12.49
          },
          {
            "description": "Shipping & Handling",
            "amount": 0
          },
          {
            "description": "Estimated tax to be collected",
            "amount": 0.87
          }
        ],
        "paymentMethod": {
          "type": "card",
          "lastFour": "2345",
          "brand": "Mastercard",
          "isPrimary": true
        },
        "paymentHistory": [
          {
            "paymentMethod": {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            },
            "date": "2024-10-20T18:00:54.761Z",
            "amount": 13.36
          }
        ],
        "products": [
          {
            "sourceId": "B1XX8WVCRJ",
            "description": "AAA Alkaline High-Performance Batteries",
            "amount": 12.49,
            "returnBy": "2024-12-19T23:59:59.000Z",
            "quantity": {
              "value": 1
            }
          }
        ]
      }
    ],
    "recurringFinancialTransactions": [
      {
        "_id": "6903d4ae324b0a223b44ac7c",
        "company": {
          "_id": "65272c415d8a530008e972df",
          "name": "Amazon",
          "branding": {
            "logo": {
              "url": "https://cdn-public.atomicfi.com/8d97b6ca-595b-447c-8b86-8d690501c794_amazon.png",
              "backgroundColor": "#FF9900"
            },
            "color": "#FF9900"
          }
        },
        "financialTransactions": [
          {
            "identifier": "12345",
            "description": "Amazon",
            "amount": 24.99,
            "date": "2024-01-01T00:00:00.000Z",
            "_id": "68c1c9497306bf98e3daabe3"
          },
          {
            "identifier": "12346",
            "description": "Amazon",
            "amount": 24.99,
            "date": "2024-02-01T00:00:00.000Z",
            "_id": "68c1c9497306bf98e3daabe4"
          },
          {
            "identifier": "12347",
            "description": "Amazon",
            "amount": 24.99,
            "date": "2024-03-01T00:00:00.000Z",
            "_id": "68c1c9497306bf98e3daabe5"
          }
        ],
        "dueDate": "2024-04-01T00:00:00.000Z",
        "accountId": "67376c5befe988922e8aabc4",
        "name": "Amazon",
        "amount": 24.99,
        "billingCycle": "monthly",
        "expenseId": "6903d4ae324b0a223b44ac7d",
        "actions": []
      }
    ],
    "suggestions": [
      {
        "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsImJpbGxJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsInBsYW5JZCI6IjUyMDAifQ==",
        "monthlySavings": 9.99,
        "category": "better-plan-available",
        "text": {
          "listTitle": "$120/year",
          "listDescription": "Hulu (Ads) costs less and may suit your needs.",
          "detailTitle": "Save $120 per year on Hulu",
          "detailDescription": "Your current plan, Hulu (No Ads) ($17.99 monthly), is more expensive than another plan that includes ads, Hulu (Ads) ($7.99 monthly).",
          "cta": "Change Plan"
        },
        "action": {
          "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3NlY3VyZS5odWx1LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2NzM3NmM1YmVmZTk4ODkyMmU4YWFiYzQifSwiYmlsbCI6eyJfaWQiOiI2NzM3NmM1YmVmZTk4ODkyMmU4YWRlZjUiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NSJ9LCJhY2NvdW50U3RhdHVzIjoibGlua2VkIiwiY29tcGFueUlkIjoiNjUyOWE2ZWNjYjhlNzIwMDA4NWM2ZWY2IiwicHVibGljVG9rZW4iOiJkMzg1ZjczOS1mMzM3LTQxMGYtOWFlNy0zNWFkOTc1Y2NkMWUiLCJpc1Rlc3RBY2NvdW50IjpmYWxzZX0=",
          "type": "change-plan",
          "automated": false,
          "disabled": false,
          "bill": {
            "_id": "67376c5befe988922e8adef5",
            "name": "Hulu",
            "companyId": "6529a6eccb8e7200085c6ef6"
          }
        },
        "references": [
          {
            "company": {
              "_id": "6529a6eccb8e7200085c6ef6",
              "name": "Hulu",
              "branding": {
                "color": "#040405",
                "logo": {
                  "backgroundColor": "#040405",
                  "url": "https://cdn-public.atomicfi.com/60e83c17-cda4-4b5a-98c6-c83199c54d48.png"
                }
              }
            },
            "account": {
              "_id": "67376c5befe988922e8aabc4",
              "companyId": "6529a6eccb8e7200085c6ef6",
              "isConnected": true
            },
            "bill": {
              "_id": "67376c5befe988922e8adef5",
              "companyId": "6529a6eccb8e7200085c6ef6",
              "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6685"
            }
          }
        ]
      }
    ]
  }
}

Create Accounts

This endpoint creates Accounts for a specific end user based on one of the following:

  • Company ids. Atomic will create an Account (or match an existing one) for each input company identifier.
  • Company names. Atomic will create an Account (or match an existing one) for each input company name by matching to companies in the Atomic system. In many cases this is sufficient, but if you require more control over the matching algorithm, it is recommended to use Company search to look up and use specific company ids instead.

Provide exactly one of companyIds or companyNames in the request body. The response returns a data array with one entry per input, each containing the newly created (or existing matched) Account or an error.

Recurring payments detected from a user's financial transactions can be viewed via the recurring transactions endpoint.

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.

POST/pay-link/accounts
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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

Optional Properties

companyIds[string]
An array of Atomic company ids to create accounts for. Required if companyNames is not provided.
companyNames[string]
An array of company names to create accounts for. Required if companyIds is not provided.

Query parameters

hideDisabledActionsboolean
Whether to hide actions that are temporarily disabled for maintenance. By default, these actions are included.
ignorePlanStatusboolean
Whether to ignore plan status when determining available actions. By default, pause-plan and cancel-plan actions are filtered out for plans that are already paused or cancelled.
includeTestFlowsboolean
Whether to include test flows for certain actions. This is only available for test accounts created with test-good credentials.
Example request 
{
  "companyNames": [
    "netflix",
    "max",
    "merchant that does not exist"
  ]
}

Response

The response contains a data array of objects that includes created or matched Accounts and relevant metadata.

errorboolean
Whether an error occurred for the input.
messagestring
The error message, if an error occurred.
accountAccount
An Account object, if an error did not occur.
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, a connection attempt has not been made. If the account is connected then a successful connection attempt has been made the account can be accessed. If the account is disconnected, then we have lost connection to the account and it can no longer be accessed.
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. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
bills[Bills]
The recurring expenses of an account pulled directly from the connected system, such as the subscription on a Netflix account or a list of managed subscriptions on an Amazon account.
Child Properties
Required Properties
_idstring
Unique identifier for the bill.
expenseIdstring
The id of the expense related to the bill, for determining when a bill and a recurring financial transaction represent the same expense.
sourceIdstring
The id of the bill as identified in 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.
billingCycleenum
The recurring cycle of the bill.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
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 bill.
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]
The actions that can be performed on the bill.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the bill.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
expenses[Expenses]
The recurring expenses of an account, both pulled directly from the connected system and based on the user's financial transactions.
Child Properties
Required Properties
_idstring
Unique identifier for the expense.
Optional Properties
billIdstring
The identifier of the associated bill, if the underlying expense is a bill.
recurringFinancialTransactionIdstring
The identifier of the associated bill, if the underlying expense is a recurring financial transaction.
namestring
The name of the expense.
amountnumber
The amount of the expense.
amountDisclaimerstring
A disclaimer about how the expense amount was determined.
autopayStatusenum
Whether the expense has autopay enabled. One of enabled, disabled, or paused.
billingCycleenum
The recurring cycle of the expense.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The due date of the expense.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the expense.
Child Properties
Optional Properties
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
paymentMethodPaymentMethod
The payment method of the expense, 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.
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.
profiles[Profiles]
The profiles associated with the expense.
Child Properties
Optional Properties
namestring
The name of the profile.
lastUseddate
The date the profile was last used.
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 expense.
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.
actions[Actions]
The actions that can be performed on the expense.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
suggestions[Suggestions]
Suggestions about actions that can be performed on the expense.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Optional Properties
lastSyncedAtdate
The date the user's data was last synced, provided in ISO format.
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.
recurringFinancialTransactionsRecurringFinancialTransactions
The recurring expenses of an account based on the user's financial transactions.
Child Properties
Required Properties
namestring
The name of the recurring financial transaction
amountnumber
The amount of the recurring financial transaction, typically the same as the amount of the most recent financial transaction.
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
expenseIdstring
The id of the expense related to the recurring financial transaction, for determining when a bill and a recurring financial transaction represent the same expense.
Optional Properties
billingCycleenum
The billing cycle of the recurring financial transaction
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedate
The next billing date of the recurring financial transaction.
companyCompany
An object containing details of the company for the recurring financial transaction. This field may not be returned in cases in which the company for the recurring financial transaction does not exist 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.
accountIdstring
The account that owns the recurring financial transaction
actions[Actions]
The actions that can be performed on the recurring financial transaction.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
orders[Orders]
An array of objects containing the purchase orders associated with the account. Only returned when order monitoring is enabled for your account.
Child Properties
Required Properties
_idstring
Unique identifier for the order.
sourceIdstring
The identifier of the order in the the connected system.
datestring
The date the order was placed.
amountnumber
The total amount of the order.
lineItems[LineItems]
An array of objects containing the itemized amount breakdown of the order.
Child Properties
Optional Properties
descriptionstring
Description of the line item.
amountnumber
Amount of the line item.
paymentMethodPaymentMethod
The payment method of the order.
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.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the order. May be empty if the user used a gift card to complete the purchase.
Child Properties
Required Properties
paymentMethodPaymentMethod
The payment method of the order.
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.
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
products[Products]
An array of objects containing the products purchased in this order.
Child Properties
Required Properties
descriptionstring
The description of the purchased product.
amountnumber
The amount of the purchased product.
quantityobject
The purchased quantity of the product.
Child Properties
Required Properties
valuenumber
Optional Properties
unitstring
The source system's quantity unit for the product.
Optional Properties
sourceIdstring
The id of the product in the source system.
returnBydate
The max date for which the purchased product can be returned.
suggestions[Suggestions]
Suggestions about actions that can be performed on the account.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
createdboolean
Whether this is a new account (true) or an existing one (false), if an error did not occur.
Example response 
{
  "data": [
    {
      "error": false,
      "account": {
        "_id": "69fb5c20e95230d715de5b3e",
        "processing": false,
        "connectionStatus": "connected",
        "lastSyncedAt": "2026-05-06T18:23:19.734Z",
        "data": {
          "category": "subscription",
          "identities": [
            {
              "firstName": "test",
              "email": "test@email.com",
              "phone": "5558675309"
            }
          ],
          "paymentMethods": [
            {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            }
          ]
        },
        "company": {
          "_id": "64ecca15ec669e000851d5d2",
          "name": "Netflix",
          "branding": {
            "color": "#000000",
            "logo": {
              "backgroundColor": "#000000",
              "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
            }
          }
        },
        "bills": [
          {
            "_id": "69fb5c20e95230d715de5b3e",
            "accountId": "69fb5c20e95230d715de5b3e",
            "expenseId": "69fb87181ec0a98f943cac53",
            "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6684",
            "name": "Netflix",
            "amount": 19.74,
            "amountDisclaimer": "Estimated based on billing history.",
            "autopayStatus": "enabled",
            "billingCycle": "monthly",
            "dueDate": "2026-05-15T00:00:00.000Z",
            "profiles": [
              {
                "name": "test",
                "lastUsed": "2026-05-06T00:00:00.000Z"
              }
            ],
            "paymentMethod": {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            },
            "paymentHistory": [
              {
                "date": "2026-04-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-03-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-02-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-01-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-12-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-11-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-10-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-09-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-08-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-07-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-06-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-05-15T00:00:00.000Z",
                "amount": 19.74
              }
            ],
            "items": [
              {
                "description": "Streaming Service",
                "amount": 19.74,
                "subitems": []
              }
            ],
            "usage": [],
            "plans": [
              {
                "typeId": "3088",
                "status": "active",
                "description": "Standard",
                "amount": 17.99,
                "freeTrial": false
              }
            ],
            "company": {
              "_id": "64ecca15ec669e000851d5d2",
              "name": "Netflix",
              "branding": {
                "color": "#000000",
                "logo": {
                  "backgroundColor": "#000000",
                  "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
                }
              }
            },
            "actions": [
              {
                "actionId": "eyJ0eXBlIjoidmlldy1hY2NvdW50IiwidXJsIjoiaHR0cHM6Ly9uZXRmbGl4LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "view-account",
                "automated": false,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoicmVmcmVzaCIsImZsb3ciOiJyZWZyZXNoIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "refresh",
                "automated": true,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoic3dpdGNoIiwiZmxvdyI6InN3aXRjaCIsImFjY291bnQiOnsiX2lkIjoiNjlmYjVjMjBlOTUyMzBkNzE1ZGU1YjNlIn0sImFjY291bnRTdGF0dXMiOiJsaW5rZWQiLCJjb21wYW55SWQiOiI2NGVjY2ExNWVjNjY5ZTAwMDg1MWQ1ZDIiLCJwdWJsaWNUb2tlbiI6IjAyYjA2ZWM3LTlkYzctNDNiYy1hZTQzLWE0ODY4NGJiNGRhMSIsImlzVGVzdEFjY291bnQiOmZhbHNlfQ==",
                "type": "switch",
                "automated": true,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "change-plan",
                "automated": false,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              },
              {
                "actionId": "eyJ0eXBlIjoicGF1c2UtcGxhbiIsImZsb3ciOiJwYXVzZS1wbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "pause-plan",
                "automated": true,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              },
              {
                "actionId": "eyJ0eXBlIjoiY2FuY2VsLXBsYW4iLCJmbG93IjoiY2FuY2VsLXBsYW4iLCJhY2NvdW50Ijp7Il9pZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSJ9LCJiaWxsIjp7Il9pZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsInNvdXJjZUlkIjoiNzAyMzZmMDItZGMzZS0zNDE5LWJiZjctMDZkM2RhOWQ2Njg0In0sInBsYW4iOnsiZGVzY3JpcHRpb24iOiJTdGFuZGFyZCJ9LCJhY2NvdW50U3RhdHVzIjoibGlua2VkIiwiY29tcGFueUlkIjoiNjRlY2NhMTVlYzY2OWUwMDA4NTFkNWQyIiwicHVibGljVG9rZW4iOiIwMmIwNmVjNy05ZGM3LTQzYmMtYWU0My1hNDg2ODRiYjRkYTEiLCJpc1Rlc3RBY2NvdW50IjpmYWxzZX0=",
                "type": "cancel-plan",
                "automated": true,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              }
            ],
            "suggestions": [
              {
                "userId": "69c5a0a5f21beccdd6e55c9a",
                "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsImJpbGxJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsInBsYW5JZCI6IjUyMDAifQ==",
                "monthlySavings": 10.999999999999998,
                "category": "better-plan-available",
                "text": {
                  "listTitle": "$132/year",
                  "listDescription": "Standard with ads costs less and may suit your needs.",
                  "detailTitle": "Save $132 per year on Netflix",
                  "detailDescription": "Your current plan, Standard ($19.99 / month), is more expensive than another plan that includes ads, Standard with ads ($8.99 / month).",
                  "cta": "Change Plan"
                },
                "action": {
                  "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                  "type": "change-plan",
                  "automated": false,
                  "disabled": false,
                  "bill": {
                    "_id": "69fb5c20e95230d715de5b3e",
                    "name": "Netflix",
                    "companyId": "64ecca15ec669e000851d5d2"
                  }
                },
                "references": [
                  {
                    "company": {
                      "_id": "64ecca15ec669e000851d5d2",
                      "name": "Netflix",
                      "branding": {
                        "color": "#000000",
                        "logo": {
                          "backgroundColor": "#000000",
                          "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
                        }
                      }
                    },
                    "account": {
                      "_id": "69fb5c20e95230d715de5b3e",
                      "companyId": "64ecca15ec669e000851d5d2",
                      "isConnected": true
                    },
                    "bill": {
                      "_id": "69fb5c20e95230d715de5b3e",
                      "companyId": "64ecca15ec669e000851d5d2",
                      "sourceId": "7T7S27WUCZFC5EGYJ6UM3B4WSY"
                    }
                  }
                ]
              }
            ]
          }
        ],
        "recurringFinancialTransactions": [],
        "expenses": [
          {
            "_id": "69fb87181ec0a98f943cac53",
            "billId": "69fb5c20e95230d715de5b3e",
            "accountId": "69fb5c20e95230d715de5b3e",
            "sourceId": "70236f02-dc3e-3419-bbf7-06d3da9d6684",
            "name": "Netflix",
            "amount": 19.74,
            "amountDisclaimer": "Estimated based on billing history.",
            "autopayStatus": "enabled",
            "billingCycle": "monthly",
            "dueDate": "2026-05-15T00:00:00.000Z",
            "profiles": [
              {
                "name": "test",
                "lastUsed": "2026-05-06T00:00:00.000Z"
              }
            ],
            "paymentMethod": {
              "type": "card",
              "lastFour": "2345",
              "brand": "Mastercard",
              "isPrimary": true
            },
            "paymentHistory": [
              {
                "date": "2026-04-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-03-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-02-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2026-01-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-12-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-11-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-10-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-09-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-08-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-07-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-06-15T00:00:00.000Z",
                "amount": 19.74
              },
              {
                "date": "2025-05-15T00:00:00.000Z",
                "amount": 19.74
              }
            ],
            "items": [
              {
                "description": "Streaming Service",
                "amount": 19.74,
                "subitems": []
              }
            ],
            "usage": [],
            "plans": [
              {
                "typeId": "3088",
                "status": "active",
                "description": "Standard",
                "amount": 17.99,
                "freeTrial": false
              }
            ],
            "company": {
              "_id": "64ecca15ec669e000851d5d2",
              "name": "Netflix",
              "branding": {
                "color": "#000000",
                "logo": {
                  "backgroundColor": "#000000",
                  "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
                }
              }
            },
            "actions": [
              {
                "actionId": "eyJ0eXBlIjoidmlldy1hY2NvdW50IiwidXJsIjoiaHR0cHM6Ly9uZXRmbGl4LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "view-account",
                "automated": false,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoicmVmcmVzaCIsImZsb3ciOiJyZWZyZXNoIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "refresh",
                "automated": true,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoic3dpdGNoIiwiZmxvdyI6InN3aXRjaCIsImFjY291bnQiOnsiX2lkIjoiNjlmYjVjMjBlOTUyMzBkNzE1ZGU1YjNlIn0sImFjY291bnRTdGF0dXMiOiJsaW5rZWQiLCJjb21wYW55SWQiOiI2NGVjY2ExNWVjNjY5ZTAwMDg1MWQ1ZDIiLCJwdWJsaWNUb2tlbiI6IjAyYjA2ZWM3LTlkYzctNDNiYy1hZTQzLWE0ODY4NGJiNGRhMSIsImlzVGVzdEFjY291bnQiOmZhbHNlfQ==",
                "type": "switch",
                "automated": true,
                "disabled": false
              },
              {
                "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "change-plan",
                "automated": false,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              },
              {
                "actionId": "eyJ0eXBlIjoicGF1c2UtcGxhbiIsImZsb3ciOiJwYXVzZS1wbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                "type": "pause-plan",
                "automated": true,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              },
              {
                "actionId": "eyJ0eXBlIjoiY2FuY2VsLXBsYW4iLCJmbG93IjoiY2FuY2VsLXBsYW4iLCJhY2NvdW50Ijp7Il9pZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSJ9LCJiaWxsIjp7Il9pZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsInNvdXJjZUlkIjoiNzAyMzZmMDItZGMzZS0zNDE5LWJiZjctMDZkM2RhOWQ2Njg0In0sInBsYW4iOnsiZGVzY3JpcHRpb24iOiJTdGFuZGFyZCJ9LCJhY2NvdW50U3RhdHVzIjoibGlua2VkIiwiY29tcGFueUlkIjoiNjRlY2NhMTVlYzY2OWUwMDA4NTFkNWQyIiwicHVibGljVG9rZW4iOiIwMmIwNmVjNy05ZGM3LTQzYmMtYWU0My1hNDg2ODRiYjRkYTEiLCJpc1Rlc3RBY2NvdW50IjpmYWxzZX0=",
                "type": "cancel-plan",
                "automated": true,
                "disabled": false,
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "name": "Netflix",
                  "companyId": "64ecca15ec669e000851d5d2"
                }
              }
            ],
            "suggestions": [
              {
                "userId": "69c5a0a5f21beccdd6e55c9a",
                "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsImJpbGxJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsInBsYW5JZCI6IjUyMDAifQ==",
                "monthlySavings": 10.999999999999998,
                "category": "better-plan-available",
                "text": {
                  "listTitle": "$132/year",
                  "listDescription": "Standard with ads costs less and may suit your needs.",
                  "detailTitle": "Save $132 per year on Netflix",
                  "detailDescription": "Your current plan, Standard ($19.99 / month), is more expensive than another plan that includes ads, Standard with ads ($8.99 / month).",
                  "cta": "Change Plan"
                },
                "action": {
                  "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
                  "type": "change-plan",
                  "automated": false,
                  "disabled": false,
                  "bill": {
                    "_id": "69fb5c20e95230d715de5b3e",
                    "name": "Netflix",
                    "companyId": "64ecca15ec669e000851d5d2"
                  }
                },
                "references": [
                  {
                    "company": {
                      "_id": "64ecca15ec669e000851d5d2",
                      "name": "Netflix",
                      "branding": {
                        "color": "#000000",
                        "logo": {
                          "backgroundColor": "#000000",
                          "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
                        }
                      }
                    },
                    "account": {
                      "_id": "69fb5c20e95230d715de5b3e",
                      "companyId": "64ecca15ec669e000851d5d2",
                      "isConnected": true
                    },
                    "bill": {
                      "_id": "69fb5c20e95230d715de5b3e",
                      "companyId": "64ecca15ec669e000851d5d2",
                      "sourceId": "7T7S27WUCZFC5EGYJ6UM3B4WSY"
                    }
                  }
                ]
              }
            ]
          }
        ],
        "suggestions": [
          {
            "userId": "69c5a0a5f21beccdd6e55c9a",
            "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsImJpbGxJZCI6IjY5ZmI1YzIwZTk1MjMwZDcxNWRlNWIzZSIsInBsYW5JZCI6IjUyMDAifQ==",
            "monthlySavings": 10.999999999999998,
            "category": "better-plan-available",
            "text": {
              "listTitle": "$132/year",
              "listDescription": "Standard with ads costs less and may suit your needs.",
              "detailTitle": "Save $132 per year on Netflix",
              "detailDescription": "Your current plan, Standard ($19.99 / month), is more expensive than another plan that includes ads, Standard with ads ($8.99 / month).",
              "cta": "Change Plan"
            },
            "action": {
              "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYmlsbCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UiLCJzb3VyY2VJZCI6IjcwMjM2ZjAyLWRjM2UtMzQxOS1iYmY3LTA2ZDNkYTlkNjY4NCJ9LCJwbGFuIjp7ImRlc2NyaXB0aW9uIjoiU3RhbmRhcmQifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
              "type": "change-plan",
              "automated": false,
              "disabled": false
            },
            "references": [
              {
                "company": {
                  "_id": "64ecca15ec669e000851d5d2",
                  "name": "Netflix",
                  "branding": {
                    "color": "#000000",
                    "logo": {
                      "backgroundColor": "#000000",
                      "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
                    }
                  }
                },
                "account": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "companyId": "64ecca15ec669e000851d5d2",
                  "isConnected": true
                },
                "bill": {
                  "_id": "69fb5c20e95230d715de5b3e",
                  "companyId": "64ecca15ec669e000851d5d2",
                  "sourceId": "7T7S27WUCZFC5EGYJ6UM3B4WSY"
                }
              }
            ]
          }
        ],
        "actions": [
          {
            "actionId": "eyJ0eXBlIjoidmlldy1hY2NvdW50IiwidXJsIjoiaHR0cHM6Ly9uZXRmbGl4LmNvbS9hY2NvdW50IiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
            "type": "view-account",
            "automated": false,
            "disabled": false
          },
          {
            "actionId": "eyJ0eXBlIjoicmVmcmVzaCIsImZsb3ciOiJyZWZyZXNoIiwiYWNjb3VudCI6eyJfaWQiOiI2OWZiNWMyMGU5NTIzMGQ3MTVkZTViM2UifSwiYWNjb3VudFN0YXR1cyI6ImxpbmtlZCIsImNvbXBhbnlJZCI6IjY0ZWNjYTE1ZWM2NjllMDAwODUxZDVkMiIsInB1YmxpY1Rva2VuIjoiMDJiMDZlYzctOWRjNy00M2JjLWFlNDMtYTQ4Njg0YmI0ZGExIiwiaXNUZXN0QWNjb3VudCI6ZmFsc2V9",
            "type": "refresh",
            "automated": true,
            "disabled": false
          },
          {
            "actionId": "eyJ0eXBlIjoic3dpdGNoIiwiZmxvdyI6InN3aXRjaCIsImFjY291bnQiOnsiX2lkIjoiNjlmYjVjMjBlOTUyMzBkNzE1ZGU1YjNlIn0sImFjY291bnRTdGF0dXMiOiJsaW5rZWQiLCJjb21wYW55SWQiOiI2NGVjY2ExNWVjNjY5ZTAwMDg1MWQ1ZDIiLCJwdWJsaWNUb2tlbiI6IjAyYjA2ZWM3LTlkYzctNDNiYy1hZTQzLWE0ODY4NGJiNGRhMSIsImlzVGVzdEFjY291bnQiOmZhbHNlfQ==",
            "type": "switch",
            "automated": true,
            "disabled": false
          }
        ]
      },
      "created": false
    },
    {
      "error": false,
      "account": {
        "_id": "6a02345ee95230d715e20960",
        "processing": false,
        "connectionStatus": "initial",
        "data": null,
        "company": {
          "_id": "6529ab9c85376a0008a76730",
          "name": "HBO Max",
          "branding": {
            "color": "#002BE7",
            "logo": {
              "backgroundColor": "#002BE7",
              "url": "https://cdn-public.atomicfi.com/90e2fd54-07f0-4596-b483-4317824e8046.png",
              "deprecatedFileTypeUrl": "https://cdn-public.atomicfi.com/6acbcff8-d32f-4550-82ec-e67ec0b1b088_max.svg"
            }
          }
        },
        "bills": [],
        "recurringFinancialTransactions": [],
        "expenses": [],
        "suggestions": [],
        "actions": []
      },
      "created": true
    },
    {
      "error": true,
      "message": "No company named \"merchant that does not exist\""
    }
  ]
}

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/
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/action-history?accountId

Response

Successfully querying the Action History endpoint will return a payload with a data array of Action History objects.

accountIdstring
The Atomic ID for the account. Retrieved from the Accounts API, or from events emitted from the Transact SDK.
typestring
The type of action. Possible values are refresh, connect-account, disconnect-account, view-account, switch, pay-now, cancel-plan, pause-plan, and change-plan.
statusstring
The status of the action. Possible values are processing, completed, and failed.
failReasonstringOptional
The reason the action failed. For example, action-failed, auth-expired, or subscription-not-found. See Task failures for the full list of possible fail reasons.
createdAtdate
The date the action was created.
Example response 
{
  "data": [
    {
      "accountId": "123",
      "type": "refresh",
      "status": "completed",
      "createdAt": "2025-05-06T17:25:09.924Z"
    },
    {
      "accountId": "681914318941b89b9a6747b9",
      "type": "pause-plan",
      "status": "completed",
      "createdAt": "2025-05-06T17:24:59.049Z"
    },
    {
      "accountId": "681914318941b89b9a6747b9",
      "type": "cancel-plan",
      "status": "completed",
      "createdAt": "2025-05-06T17:24:59.049Z"
    },
    {
      "accountId": "681914318941b89b9a6747b9",
      "type": "cancel-plan",
      "status": "failed",
      "failReason": "action-failed",
      "createdAt": "2025-05-06T17:24:59.049Z"
    }
  ]
}

Financial Transactions

Financial Transactions represent monetary activity data from connected financial accounts. These endpoints allow you to retrieve transaction, once they've been processed by Atomic. Details include merchant information, transaction amounts, descriptions, and dates. You can use this data to identify recurring payments, analyze spending patterns, or match transactions to known companies in the Atomic system.

Find Company

Match financial transaction data to companies in the Atomic network. Submit transaction identifiers and descriptions to receive enriched company information including names, IDs, and branding assets.

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[]
An array of financial transaction objects to match to companies.
Child Properties
Required Properties
descriptionstring
The raw transaction description string as provided by the financial institution. This typically includes merchant name, location, and other transaction details. Atomic uses this text to identify and match the company.
Optional Properties
identifierstring
A unique identifier for this transaction from your system. It is returned unchanged in the response so you can correlate results back to your original transaction data.
POST/financial-transactions/find-company
{
  "financialTransactions": [
    {
      "identifier": "4f89277",
      "description": "POS Transaction Hulu HLUHULUPLUS SANTA MONICA CAUS"
    },
    {
      "identifier": "5115abe3",
      "description": "POS Transaction SPOTIFY 4 WORLD TRACE CENTER 68777781161 NYUS"
    },
    {
      "identifier": "ff1e11abe",
      "description": "POS Transaction Netflixcom NETFLIXCOM LOS GATOS CAUS"
    }
  ]
}
https://sandbox-api.atomicfi.com/financial-transactions/find-company

Response

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

identifierstring
The unique identifier of the transaction.
descriptionstring
The description of the transaction.
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",
          "name": "Netflix",
          "branding": {
            "logo": {
              "backgroundColor": "#000000",
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
            },
            "color": "#000000"
          }
        }
      },
      {
        "identifier": "4f89277",
        "description": "POS Transaction Hulu HLUHULUPLUS SANTA MONICA CAUS",
        "company": {
          "_id": "6529a6eccb8e7200085c6ef6",
          "name": "Hulu",
          "branding": {
            "logo": {
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
              "backgroundColor": "#040405"
            },
            "color": "#040405"
          }
        }
      },
      {
        "identifier": "5115abe3",
        "description": "POS Transaction SPOTIFY 4 WORLD TRACE CENTER 68777781161 NYUS",
        "company": {
          "_id": "652801e35d8a530008e9e2cd",
          "name": "Spotify",
          "branding": {
            "logo": {
              "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]",
              "backgroundColor": "#000000"
            },
            "color": "#000000"
          }
        }
      }
    ]
  }
}

Get Most Recent

Returns a user's most recent financial transaction based on the transaction date.

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.

GET/financial-transactions/most-recent
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/financial-transactions/most-recent

Response

A successful request will return the most recent financial transaction.

identifierstring
The unique identifier of the transaction.
_idstring
The identifier of the transaction in the Atomic system.
descriptionstring
The description of the transaction.
amountnumber
The amount of the transaction.
datedate
The date of the transaction in ISO format.
Example response 
{
  "data": {
    "financialTransaction": {
      "identifier": "ff1e11abe",
      "_id": "68d70242e82e372ad8fdc0b9",
      "description": "Netflix",
      "amount": 20,
      "date": "2024-03-01T00:00:00.000Z"
    }
  }
}

Create Financial Transactions

Submit financial transactions in bulk for processing. Transactions are associated with the given users and processed asynchronously, for example to classify employers or detect recurring transactions, based on the products enabled for your 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

users[]
An array of user objects, each containing an identifier and their associated financial transactions.
Child Properties
Required Properties
identifierstring
A unique identifier for the user in your system.
financialTransactions[]
An array of financial transaction objects for this user.
Child Properties
Required Properties
descriptionstring
The description of the transaction.
datedate
The date of the transaction. Accepts an ISO 8601 date (2025-09-16) or a date-time with a timezone (2025-09-16T00:00:00Z).
amountnumber
The amount of the transaction.
identifierstring
A unique identifier for the transaction in your system.
POST/financial-transactions/bulk
{
  "users": [
    {
      "identifier": "YOUR_INTERNAL_GUID",
      "financialTransactions": [
        {
          "description": "Mocky Employer Deposit",
          "date": "2025-09-16",
          "amount": 200,
          "identifier": "rw4X16KOpnuLDgO1e8XmsO4Mdj7qbEtrm4em3"
        },
        {
          "description": "Mocky Employer Deposit",
          "date": "2025-10-16",
          "amount": 200,
          "identifier": "ZARy593qakT1aOQEXqDbfL5J0qgQ3pt86Bjnr"
        },
        {
          "description": "Mocky Employer Deposit",
          "date": "2025-11-16",
          "amount": 200,
          "identifier": "80kJVy7KPrhVMeL9JwjBc5MzwLapy3SYaeB8N"
        }
      ]
    }
  ]
}
https://sandbox-api.atomicfi.com/financial-transactions/bulk

Response

A successful request will return a success confirmation.

successboolean
Indicates whether the bulk submission was successful.
Example response 
{
  "data": {
    "success": true
  }
}

Get Employer Matches

Retrieve employer matches for a user's financial transactions. Returns companies identified as employers based on the transactions submitted via the bulk endpoint.

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.

GET/financial-transactions/employer-matches
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/financial-transactions/employer-matches

Response

A successful request will return a list of employer matches with associated financial transactions.

_idstring
The unique identifier of the employer match record.
companyobject
The company identified as an employer.
Child Properties
Required Properties
_idstring
Unique identifier for the company.
namestring
The name of the company.
brandingobject
The branding information of the company.
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 primary color of the company.
financialTransactions[]
The financial transactions associated with this employer.
Child Properties
Required Properties
identifierstring
The unique identifier of the transaction from your system.
_idstring
The identifier of the transaction in the Atomic system.
descriptionstring
The description of the transaction.
amountnumber
The amount of the transaction.
datedate
The date of the transaction in ISO format.
Example response 
{
  "data": [
    {
      "_id": "69c1ac7a49c6374f78640f83",
      "company": {
        "branding": {
          "logo": {
            "url": "https://cdn-public.atomicfi.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png",
            "backgroundColor": null
          },
          "color": "#090721"
        },
        "_id": "5e4c4d18b7d75c37aac54a47",
        "name": "Mocky"
      },
      "financialTransactions": [
        {
          "identifier": "rw4X16KOpnuLDgO1e8XmsO4Mdj7qbEtrm4em3",
          "description": "Mocky Employer Deposit",
          "amount": 200,
          "date": "2025-09-16T00:00:00.000Z",
          "_id": "69c1aaea9f910439aaa71c7a"
        },
        {
          "identifier": "ZARy593qakT1aOQEXqDbfL5J0qgQ3pt86Bjnr",
          "description": "Mocky Employer Deposit",
          "amount": 200,
          "date": "2025-10-16T00:00:00.000Z",
          "_id": "69c1aaea9f910439aaa71c7b"
        },
        {
          "identifier": "80kJVy7KPrhVMeL9JwjBc5MzwLapy3SYaeB8N",
          "description": "Mocky Employer Deposit",
          "amount": 200,
          "date": "2025-11-16T00:00:00.000Z",
          "_id": "69c1aaea9f910439aaa71c7c"
        }
      ]
    }
  ]
}

Plaid

Plaid endpoints allow you to manage Plaid processor links for your users. Use these endpoints to store and remove Plaid processor tokens, which enable Atomic to pull financial transaction data directly from a user's linked financial accounts.

Create Processor Link

Create or update a Plaid processor link for a user. Atomic stores the Plaid processor token, retrieves the linked account's transaction history through Plaid, and processes the transactions asynchronously.

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

processorTokenstring
A Plaid processor token associated with the user's financial account. This token is generated through Plaid's processor token creation flow.
POST/plaid/processor-links
{
  "processorToken": "processor-sandbox-0asd1-a92nc"
}
https://sandbox-api.atomicfi.com/plaid/processor-links

Response

A successful request will return the identifier of the processor link.

Processing runs asynchronously after the processor link is created. Once it completes, Atomic emits a webhook for each type of processing enabled for your account (for example, employer-classification-completed or recurring-transaction-detection-completed). If Plaid returns an error while Atomic retrieves the user's transactions, Atomic instead emits the plaid-error webhook.

_idstring
The identifier of the processor link in the Atomic system.
Example response 
{
  "_id": "69fb5c20e95230d715de5b3e"
}

Delete Processor Links

Delete all Plaid processor links for a user. This removes every processor token stored for the user and stops further processing of their Plaid transaction data.

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/plaid/processor-links
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/plaid/processor-links

Response

A successful request will return a success confirmation.

successboolean
Indicates whether the processor links were successfully deleted.
Example response 
{
  "success": true
}

Orders

Orders represent purchases made from 3rd party services e.g. Amazon. Use these endpoints to identify and analyze a user's orders.

Get Orders

This endpoint returns all orders associated with an end user. The query string parameters accountId, startDate, endDate and sortOrder can be used to filter on which orders are returned.

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

accountIdstring
Only orders only associated to the specified account will be returned.
startDatestring
Only orders with date on or after the provided date will be returned.
endDatestring
Only orders with date on or before the provided date will be returned.
sortOrderstring
Orders will be returned sorted by the date. Possible values include 'ascending' or 'descending'. This value is defaulted to 'ascending'.
GET/pay-link/orders
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/orders

Response

The response includes an array of Order objects.

orders[Order]
An array of Order objects.
Child Properties
Required Properties
_idstring
Unique identifier for the order.
accountIdstring
The identifier for the account that the order belongs to.
sourceIdstring
The identifier of the order in the the connected system.
datestring
The date the order was placed.
amountnumber
The total amount of the order.
lineItems[LineItems]
An array of objects containing the itemized amount breakdown of the order.
Child Properties
Optional Properties
descriptionstring
Description of the line item.
amountnumber
Amount of the line item.
paymentMethodPaymentMethod
The payment method of the order.
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.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the order. May be empty if the user used a gift card to complete the purchase.
Child Properties
Required Properties
paymentMethodPaymentMethod
The payment method of the order.
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.
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
products[Products]
An array of objects containing the products purchased in this order.
Child Properties
Required Properties
descriptionstring
The description of the purchased product.
amountnumber
The amount of the purchased product.
quantityobject
The purchased quantity of the product.
Child Properties
Required Properties
valuenumber
Optional Properties
unitstring
The source system's quantity unit for the product.
Optional Properties
sourceIdstring
The id of the product in the source system.
returnBydate
The max date for which the purchased product can be returned.
Example response 
{
  "orders": [
    {
      "_id": "67376c5befe988922e8adef6",
      "accountId": "6939f5d131acddd3742dd852",
      "sourceId": "112-2968911-3747422",
      "date": "2024-10-20T18:00:54.761Z",
      "amount": 13.36,
      "lineItems": [
        {
          "description": "Item(s) Subtotal",
          "amount": 12.49
        },
        {
          "description": "Shipping & Handling",
          "amount": 0
        },
        {
          "description": "Estimated tax to be collected",
          "amount": 0.87
        }
      ],
      "paymentMethod": {
        "type": "card",
        "lastFour": "2345",
        "brand": "Mastercard",
        "isPrimary": true
      },
      "paymentHistory": [
        {
          "paymentMethod": {
            "type": "card",
            "lastFour": "2345",
            "brand": "Mastercard",
            "isPrimary": true
          },
          "date": "2024-10-20T18:00:54.761Z",
          "amount": 13.36
        }
      ],
      "products": [
        {
          "sourceId": "B1XX8WVCRJ",
          "description": "AAA Alkaline High-Performance Batteries",
          "amount": 12.49,
          "returnBy": "2024-12-19T23:59:59.000Z",
          "quantity": {
            "value": 1
          }
        }
      ]
    },
    {
      "_id": "6939f917120156b95b5bcba9",
      "accountId": "6939f5d131acddd3742dd852",
      "sourceId": "113-1974941-0414645",
      "date": "2025-11-04T00:00:00.000Z",
      "amount": 19.82,
      "lineItems": [
        {
          "description": "Item(s) Subtotal",
          "amount": 18.16
        },
        {
          "description": "Taxes and Fees",
          "amount": 1.66
        }
      ],
      "paymentMethod": {
        "description": "card",
        "lastFour": "4321",
        "brand": "Mastercard",
        "isPrimary": false
      },
      "paymentHistory": [
        {
          "paymentMethod": {
            "description": "card",
            "lastFour": "4321",
            "brand": "Mastercard",
            "isPrimary": false
          },
          "date": "2025-11-04T00:00:00.000Z",
          "amount": 19.82
        }
      ],
      "products": [
        {
          "sourceId": "B07FF78VVT",
          "description": "Grapefruit Star Conventional, 1 Each",
          "amount": 6.21,
          "quantity": {
            "value": 3.12,
            "unit": "lb"
          }
        },
        {
          "sourceId": "B0747VTT4O",
          "description": "Bell & Evans Boneless Skinless Chicken Breast",
          "amount": 11.95,
          "quantity": {
            "value": 1.71,
            "unit": "lb"
          }
        }
      ]
    }
  ]
}

Get Order

This endpoint returns the full details of a single order 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.

Required Properties

_idstring
The _id of the order.
GET/pay-link/orders/:id
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/orders/:id

Response

The response includes an Order object.

orderobject
An Order objects.
Child Properties
Required Properties
_idstring
Unique identifier for the order.
accountIdstring
The identifier for the account that the order belongs to.
sourceIdstring
The identifier of the order in the the connected system.
datestring
The date the order was placed.
amountnumber
The total amount of the order.
lineItems[LineItems]
An array of objects containing the itemized amount breakdown of the order.
Child Properties
Optional Properties
descriptionstring
Description of the line item.
amountnumber
Amount of the line item.
paymentMethodPaymentMethod
The payment method of the order.
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.
paymentHistory[BillingHistory]
An array of objects containing the transaction history of the order. May be empty if the user used a gift card to complete the purchase.
Child Properties
Required Properties
paymentMethodPaymentMethod
The payment method of the order.
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.
datestring
The date of the associated transaction.
amountnumber
The amount of the associated transaction.
products[Products]
An array of objects containing the products purchased in this order.
Child Properties
Required Properties
descriptionstring
The description of the purchased product.
amountnumber
The amount of the purchased product.
quantityobject
The purchased quantity of the product.
Child Properties
Required Properties
valuenumber
Optional Properties
unitstring
The source system's quantity unit for the product.
Optional Properties
sourceIdstring
The id of the product in the source system.
returnBydate
The max date for which the purchased product can be returned.
Example response 
{
  "order": {
    "_id": "67376c5befe988922e8adef6",
    "accountId": "6939f5d131acddd3742dd852",
    "sourceId": "112-2968911-3747422",
    "date": "2024-10-20T18:00:54.761Z",
    "amount": 13.36,
    "lineItems": [
      {
        "description": "Item(s) Subtotal",
        "amount": 12.49
      },
      {
        "description": "Shipping & Handling",
        "amount": 0
      },
      {
        "description": "Estimated tax to be collected",
        "amount": 0.87
      }
    ],
    "paymentMethod": {
      "type": "card",
      "lastFour": "2345",
      "brand": "Mastercard",
      "isPrimary": true
    },
    "paymentHistory": [
      {
        "paymentMethod": {
          "type": "card",
          "lastFour": "2345",
          "brand": "Mastercard",
          "isPrimary": true
        },
        "date": "2024-10-20T18:00:54.761Z",
        "amount": 13.36
      }
    ],
    "products": [
      {
        "sourceId": "B1XX8WVCRJ",
        "description": "AAA Alkaline High-Performance Batteries",
        "amount": 12.49,
        "returnBy": "2024-12-19T23:59:59.000Z",
        "quantity": {
          "value": 1
        }
      }
    ]
  }
}

Recurring Financial Transactions

Recurring financial transactions are payments that occur on a regular schedule, such as subscription payments, utility bills, and loan payments. Use these endpoints to identify and analyze a user's recurring expenses.

Get Recurring Financial Transactions

Retrieves all recurring financial transactions for a user, including subscription payments, utility bills, and other regular expenses. Recurring transactions are detected from the financial transactions you submit through the Create Financial Transactions endpoint or a Plaid processor token.

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.

GET/pay-link/recurring-financial-transactions
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/recurring-financial-transactions

Response

A successful request will return all the recurring financial transactions for the user.

_idstring
The identifier of the transaction in the Atomic system.
namestring
The name of the recurring financial transaction.
amountnumber
The estimated amount of the recurring financial transaction.
billingCycleenumOptional
The estimated billing cycle of the recurring financial transaction.
    weeklybiweeklyevery-three-weeksevery-four-weeksevery-six-weekssemimonthlymonthlybi-monthlyevery-three-monthsevery-four-monthsevery-six-monthsannually
dueDatedateOptional
The estimated next billing date, inferred from the billing cycle and the most recent financial transaction. Only returned when the estimated date is in the future.
financialTransactions[FinancialTransactions]
An array of financial transaction objects.
Child Properties
Required Properties
identifierstring
The provided identifier of the financial transaction.
descriptionstring
The transaction description from the merchant.
amountnumber
The amount of the transaction.
datestring
The date the transation was processed, in ISO8601 format.
_idstring
The identifier of the transaction in the Atomic system.
companyCompanyOptional
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
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.
accountIdstringOptional
The identifier of the account that owns the transaction.
expenseIdstringOptional
The identifier of the expense related to the recurring financial transaction, for determining when a bill and a recurring financial transaction represent the same expense.
actions[Actions]
The actions that can be performed on the recurring financial transaction.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
Example response 
{
  "data": {
    "recurringFinancialTransactions": [
      {
        "_id": "68dc4132744a229545ebc44b",
        "name": "Netflix",
        "amount": 18.53,
        "billingCycle": "monthly",
        "financialTransactions": [
          {
            "identifier": "KR6yp7qz9Nf59PjLMEnbtkLgkkk1w1cLm1yvA",
            "description": "Netflix",
            "amount": 18.53,
            "date": "2025-09-28T00:00:00.000Z",
            "_id": "68dc4131b2408505bf4a4991"
          },
          {
            "identifier": "KR6yp7qz9Nf59PjLMEnbtkLgkkk1w1cLm1yvA",
            "description": "Netflix",
            "amount": 18.53,
            "date": "2025-10-28T00:00:00.000Z",
            "_id": "68dc4131b2408505bf2341"
          }
        ],
        "company": {
          "branding": {
            "logo": {
              "backgroundColor": "#000000",
              "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
            },
            "color": "#000000"
          },
          "_id": "64ecca15ec669e000851d5d2",
          "name": "Netflix"
        },
        "expenseId": "68dc4132744a229545ebc44c",
        "dueDate": "2025-11-28T00:00:00.000Z",
        "actions": []
      },
      {
        "_id": "68d702581c1b340a8a85e348",
        "name": "Electric Bill",
        "amount": 20,
        "billingCycle": "monthly",
        "financialTransactions": [
          {
            "identifier": "8890d7db-6ce5-49d6-b6d6-2ecb964dd478",
            "description": "Electric Bill",
            "amount": 20,
            "date": "2024-01-01T00:00:00.000Z",
            "_id": "68d70242e82e372ad8fdc0b7"
          },
          {
            "identifier": "6bdb5f59-51f0-4f74-895e-4f9b393b32b8",
            "description": "Electric Bill",
            "amount": 20,
            "date": "2024-02-01T00:00:00.000Z",
            "_id": "68d70242e82e372ad8fdc0b8"
          }
        ],
        "expenseId": "68d702581c1b340a8a85e349",
        "actions": []
      }
    ]
  }
}

SuggestionsBeta

A Suggestion is an actionable insight about an end user’s accounts or financial transactions. For instance, Atomic can offer the insight that a user is overpaying for Netflix and suggest taking action to change to a cheaper plan.

Suggestions are currently in beta. Behavior and response shapes may change before general availability.

Get Suggestions

This endpoint returns all Suggestions 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.

GET/pay-link/suggestions
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

https://sandbox-api.atomicfi.com/pay-link/suggestions

Response

The response includes a list of Suggestion objects.

suggestions[Suggestions]
An array of Suggestion objects.
Child Properties
Optional Properties
identifierstring
A unique identifier for the suggestion.
monthlySavingsnumber
The amount of money the suggestion is expected to save, normalized to a monthly amount.
categoryenum
The category of the suggestion.
    account-availablebetter-plan-availablebundle-availablediscount-availableprice-changepricey-feature-detectedstale-account-dataunderutilization
textSuggestionText
Child Properties
Optional Properties
listTitlestring
Text that describes the suggestion, suitable for the title in a list view.
listDescriptionstring
Text that describes the suggestion, suitable for the description in a list view.
detailTitlestring
Text that describes the suggestion, suitable for the title in a detail view.
detailDescriptionstring
Text that describes the suggestion, suitable for the description in a detail view.
ctastring
A call to action for the suggestion.
actionAction
The action associated with the suggestion.
Child Properties
Optional Properties
actionIdstring
The ID of the action. Use this to launch the action with Transact.
typeenum
The type of the action.
    connect-accountrefreshview-accountcancel-planpause-planchange-planswitchpay-now
automatedboolean
Whether the action is automated. If true, a task will be created to track and peform the automation. The status of the task can be monitored using webhooks. If false, then the user will perform the action on their device via a webview.
disabledboolean
Whether the merchant associated with this action is temporarily disabled for maintenance.
billBill
An object containing billing details associated with the action, when applicable.
Child Properties
Optional Properties
_idstring
The bill identifier
namestring
The name of the bill, such as Netflix or Paramount+
companyIdstring
The company identifier the bill references. This may be different from the company associated with the action if the bill is a subscription managed by a third party, e.g. the value will be Paramount+ for a Paramount+ subscription managed by Apple.
testFlowenum
The test case this action represents. This is only available for test accounts created with test-good credentials.
    paylink-action-failedauth-expiredsystem-unavailableunexpected-responsereconnect
references[SuggestionReferences]
Child Properties
Optional Properties
companyCompany
The company referenced by the suggestion.
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.
accountReferencedAccount
The account referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced account.
companyIdstring
The company id of the referenced account.
isConnectedboolean
Whether the referenced account has been connected.
billReferencedBill
The bill referenced by the suggestion.
Child Properties
Optional Properties
_idstring
The id of the referenced bill.
companyIdstring
The company id of the referenced bill.
sourceIdstring
The source id of the referenced bill.
planReferencedPlan
The plan referenced by the suggestion.
Child Properties
Optional Properties
sourceIdstring
The source id of the referenced plan.
descriptionstring
The description of the referenced plan.
Example response 
{
  "suggestions": [
    {
      "identifier": "eyJjYXRlZ29yeSI6ImJldHRlci1wbGFuLWF2YWlsYWJsZSIsImFjY291bnRJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsImJpbGxJZCI6IjY5MjRlMzRlNGUwZjdjMTdmYjgwODZhOSIsInBsYW5JZCI6IjUyMDAifQ==",
      "monthlySavings": 9.99,
      "category": "better-plan-available",
      "text": {
        "listTitle": "$120/year",
        "listDescription": "Standard with ads costs less and may suit your needs.",
        "detailTitle": "Save $120 per year on Netflix",
        "detailDescription": "Your current plan, Standard ($17.99 monthly), is more expensive than another plan that includes ads, Standard with ads ($7.99 monthly).",
        "cta": "Change Plan"
      },
      "action": {
        "actionId": "eyJ0eXBlIjoiY2hhbmdlLXBsYW4iLCJ1cmwiOiJodHRwczovL3d3dy5uZXRmbGl4LmNvbS9DaGFuZ2VQbGFuIiwiYWNjb3VudCI6eyJfaWQiOiI2OTI0ZTM0ZTRlMGY3YzE3ZmI4MDg2YTkifSwiYmlsbCI6eyJfaWQiOiI2OTI0ZTM0ZTRlMGY3YzE3ZmI4MDg2YTkiLCJzb3VyY2VJZCI6IjdUN1MyN1dVQ1pGQzVFR1lKNlVNM0I0V1NZIn0sImFjY291bnRTdGF0dXMiOiJsaW5rZWQiLCJjb21wYW55SWQiOiI2NGVjY2ExNWVjNjY5ZTAwMDg1MWQ1ZDIiLCJwdWJsaWNUb2tlbiI6ImQzODVmNzM5LWYzMzctNDEwZi05YWU3LTM1YWQ5NzVjY2QyZCIsImlzVGVzdEFjY291bnQiOmZhbHNlfQ==",
        "type": "change-plan",
        "automated": false,
        "disabled": false
      },
      "references": [
        {
          "company": {
            "_id": "64ecca15ec669e000851d5d2",
            "name": "Netflix",
            "branding": {
              "color": "#000000",
              "logo": {
                "backgroundColor": "#000000",
                "url": "https://cdn-public.atomicfi.com/a246ba37-4491-4da6-955a-3778b0c67e69_92a85256-f90a-43e9-a201-5450781bd7c8_netflix.png"
              }
            }
          },
          "account": {
            "_id": "6924e34e4e0f7c17fb8086a9",
            "companyId": "64ecca15ec669e000851d5d2",
            "isConnected": true
          },
          "bill": {
            "_id": "6924e34e4e0f7c17fb8086a9",
            "companyId": "64ecca15ec669e000851d5d2",
            "sourceId": "7T7S27WUCZFC5EGYJ6UM3B4WSY"
          }
        }
      ]
    },
    {
      "identifier": "eyJjYXRlZ29yeSI6ImFjY291bnQtYXZhaWxhYmxlIiwiY29tcGFueUlkIjoiNjUyODAxZTM1ZDhhNTMwMDA4ZTllMmNkIn0=",
      "category": "account-available",
      "text": {
        "listTitle": "Account available",
        "listDescription": "Connect to Spotify to find savings opportunities.",
        "detailTitle": "Account available",
        "detailDescription": "Your Spotify account hasn't been connected yet, so you may be missing out on some savings opportunities.",
        "cta": "Connect Account"
      },
      "action": {
        "actionId": "eyJ0eXBlIjoiY29ubmVjdC1hY2NvdW50IiwiZmxvdyI6ImNvbm5lY3QtYWNjb3VudCIsImFjY291bnQiOnsiX2lkIjoiNjkxN2ExMGI1YmY0YzdhMjIxYmYwMzAzIn0sImFjY291bnRTdGF0dXMiOiJzdWdnZXN0ZWQiLCJjb21wYW55SWQiOiI2NTI4MDFlMzVkOGE1MzAwMDhlOWUyY2QiLCJwdWJsaWNUb2tlbiI6ImQzODVmNzM5LWYzMzctNDEwZi05YWU3LTM1YWQ5NzVjY2QyZCJ9",
        "type": "connect-account",
        "automated": true,
        "disabled": false
      },
      "references": [
        {
          "company": {
            "_id": "652801e35d8a530008e9e2cd",
            "name": "Spotify",
            "branding": {
              "color": "#000000",
              "logo": {
                "backgroundColor": "#000000",
                "url": "https://cdn-public.atomicfi.com/80ed8aee-f253-4635-aae2-ea02e255e181.png",
                "deprecatedFileTypeUrl": "https://cdn-public.atomicfi.com/6281673d-b9bf-4d22-9091-f8b7b865ff4c_spotify.svg"
              }
            }
          },
          "account": {
            "_id": "6917a10b5bf4c7a221bf0303",
            "companyId": "652801e35d8a530008e9e2cd",
            "isConnected": false
          }
        }
      ]
    }
  ]
}

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.
POST/pay-link/suggestion-review
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

user-identifier

The identifier of the user

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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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.. Other transitional values may appear while a task is being processed; treat any value other than completed or failed as in progress.
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
x-api-key

API Key for your Atomic account

x-api-secret

API Secret for your Atomic account

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

Response

A successful request will return a data object containing the task, with its _id, createdAt date, status, and if a Task failed (Tasks with a status of "failed") a failReason.

_idstring
The id of the Task.
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.. Other transitional values may appear while a task is being processed; treat any value other than completed or failed as in progress.
failReasonstringOptional
The failure reason associated with a failed task. Will consist of one of the failure values.
Example response 
{
  "data": {
    "task": {
      "_id": "63b4620ab1b1e2a0dfb1a3f4",
      "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.

Response

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

Example response 
{
  "success": true
}

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.

Please note, you can only update a single card OR account at a time. You cannot include both a card and an account in the same request.

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.

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.
When testing Switch in sandbox, only use card numbers from Basis Theory's test card list .

Example request (single item): card

PUT/user
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER",
  "data": {
    "card": {
      "title": "Premium Card",
      "number": "5100000000000008",
      "expiry": "12/29",
      "cvv": "887"
    }
  }
}
https://sandbox-pci.atomicfi.com/user
Example response 
{
  "success": true
}

Example request (single item): account

PUT/user
{
  "identifier": "YOUR_INTERNAL_IDENTIFIER",
  "data": {
    "account": {
      "accountNumber": "220000000",
      "routingNumber": "110000000",
      "type": "checking",
      "title": "Premier Plus Checking"
    }
  }
}
https://sandbox-pci.atomicfi.com/user
Example response 
{
  "success": true
}