Overview

Introduction

Production Base URL

https://api.atomicfi.com

Sandbox Base URL

https://sandbox-api.atomicfi.com

Welcome to Atomic's developer documentation!

You'll find resources to help you integrate with Transact, our web app that handles the heavy-lifting of integration, as well as a number of RESTful API endpoints.

We've tried our best to make this documentation comprehensive and helpful. If you have suggestions or find issues, please let us know.

To get going quickly, we recommend using an API collaboration tool called Postman. You can use the button below to import our collection of endpoints. Be sure to set your apiUrl, apiKey, and apiSecret environment variables.

Authentication

Atomic uses a combination of API keys and access tokens to authenticate requests.

You can retrieve and manage your API keys in the Atomic Dashboard.

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.

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.

Products

Payroll Connect

Atomic's Payroll Connect products empower users to access and update their payroll data.

When users are authenticating with their payroll account, Atomic requires that the process be facilitated through Transact.

deposit

Update the destination bank account of paychecks

verify

Verify a user’s income and employment status.

identify

Reduce fraud and onboarding friction with verified profile data from a user’s employer.

Testing

To aid in testing various user experiences, you may use any of these pre-determined "test" credentials for employer authentication. Any password will work, as long as the username is found in this list. When answering MFA questions, any answer will be accepted. If the authentication requires an email, simply append @test.com to the end of the chosen username.

Transfer

Atomic's Transfer products facilitate the movement of assets and liabilities between financial institutions.

balance

Move a user’s credit card or loan balance to a new account.

Deployment options

Transact

Transact allows the user to easily choose the source of their transfer, while the destination is pre-configured during Access Token creation.

Atomic Dashboard

The Atomic Dashboard may be used to initiate a transfer, as well as monitor it's progress as it travels through various states of processing.

API

Atomic's API may be used to initiate a transfer by first creating an Access Token, and subsequently generating a Task. The status of the task may be monitored through webhooks and the Atomic Dashboard.

Testing

When testing balance, you may use 4111111111111111 as the origin account number. This will mimic a transfer.

Transact SDK

Atomic Transact SDK is a UI designed to securely handle interactions with our products, while performing the heavy-lifting of integration.

Integration

Initalize Transact via Javascript

Sandbox URL

<script src="https://cdn-sandbox.atomicfi.com/transact.js"></script>

Production URL

<script src="https://cdn.atomicfi.com/transact.js"></script>

const startTransact = () => {
    Atomic.transact({
        // Replace with the server-side generated `publicToken`
        publicToken: "PUBLIC_TOKEN",
        // Could be either 'balance', `verify`, `identify`, or 'deposit'
        product: "balance",
        // Optionally theme Transact
        theme: {
            brandColor: "#FF0000",
            overlayColor: "#000000",
        },
        // Optionally theme Transact with a *dark* color. *DEPRICATED*
        color: "#4B39EF",
        // Optionally change the language. Could be either 'en' for English or 'es' for Spanish. Default is 'en'.
        language: "en",
        onFinish: function (data) {
            // Called when the user finishes the transaction
            // We recommend saving the `data` object which could be useful for support purposes
        },
        onClose: function () {
            // Called when the user exits Transact prematurely
        },
    });
};

// `startTransact` would typically be user-initiated, such as a button click or tap
startTransact();

An AccessToken is required to initialize Transact, and is generated server-side using your API key, and the publicToken from the response is returned to your client-side code.

Mobile & Web

Transact can be initialized by including our JavaScript SDK into your page, and then calling the Atomic.start method.

Within the context of a mobile app, we recommend loading Transact into a web view (for example, WKWebView on iOS) by building a simple self-hosted wrapper page. The URL used in the webview will be https://transact.atomicfi.com/initialize/BASE64_ENCODED_STRING. The BASE64 Encoded String is made up of an object containing the parameters used within the SDK (excluding onFinish and onClose).

Initialize Transact within a Webview

Sandbox URL

https://transact-sandbox.atomicfi.com/initialize/BASE64_ENCODED_STRING

Production URL

https://transact.atomicfi.com/initialize/BASE64_ENCODED_STRING

//Object to be BASE64 Encoded
{
  publicToken: "PUBLIC_TOKEN",
  // Could be either 'balance', 'verify', 'identify', or 'deposit'
  product: "deposit",
  // Optionally theme Transact with a *dark* color
  color: '#1b1464',
  // Optionally start on a specific step. Accepts an object
  deeplink: {
    step: 'search-company'
  },
  // Optionally change the language. Could be either 'en' for English or 'es' for Spanish. Default is 'en'.
  language: 'en'
}

Here are examples for Swift (iOS), Kotlin (Android), React Native, and Flutter

SMS

To invite a user to use Transact over SMS, follow the instructions as described in the AccessToken section.

Javascript SDK parameters

Event Listeners

When using the SDK, events will be emitted and passed to the native application. Such events allow native applications to react and perform functions as needed. Some events will be passed with a data object with additional information.

Event Interactions

{
  name: "EVENT_NAME"
  value: {
    //Default property
    customer: "Atomic",
    //Default property. Possible values are 'en' or 'es'
    language: "en"
    //Default property. Possible values are 'deposit', 'verify', 'identify', or 'balance'
    product: "deposit"
    //Additional properties will be included based on the event that has occurred.
  }
}

Each event, by default, will have customer, product, and language in the value object. Most events have additional data. See the Additional Properties table below

Additional Properties

Webhooks

Webhooks are a useful way to receive automated updates, and send timely notification to your user as a transaction progresses.

You can configure webhook endpoints via the Atomic Dashboard or during the initialization of Transact. Atomic will issue POST requests to the designated endpoint(s). We recommend using Request Bin as a way to inspect the payload of events during development without needing to stand up a server.

Securing webhooks

To validate a webhook request came from Atomic, we suggest verifying the payloads with the X-HMAC-Signature-Sha-256 header (which we pass with every request).

Event object

Sample

{
    "eventType": "task-status-updated",
    "eventTime": "2020-01-28T22:04:18.778Z",
    "product": "deposit",
    "user": {
        "_id": "5d8d3fecbf637ef3b11a877a",
        "identifier": "YOUR_INTERNAL_GUID"
    },
    "company": {
        "name": "Home Depot",
        "branding": {
            "logo": {
                "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
            }
        }
    },
    "task": "5e30afde097146a8fc3d5cec",
    "data": {
        "previousStatus": "processing",
        "status": "completed",
        "distributionType": "total"
    }
}

Event types

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn't rely on only these types existing in your code.

Each event object includes a data property which contains unique data points for each type of event. Each event type below describes these unique data points.

Task status updated

Example task-status-updated event

{
    "_id": "5c1821dbc6b7baf3435e1d23",
    "eventType": "task-status-updated",
    "eventTime": "2021-01-13T19:43:26.097Z",
    "product": "deposit",
    "user": {
        "_id": "5c17c632e1d8ca3b08b2586f",
        "identifier": "YOUR_UNIQUE_GUID"
    },
    "company": {
        "name": "Home Depot",
        "branding": {
            "logo": {
                "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
            }
        }
    },
    "task": "5d97e4abc90a0a0007993e9c",
    "data": {
        "previousStatus": "processing",
        "status": "completed"
    }
}

The status of a Task was changed. Possible statuses include:

Task status patched

Example task-status-patched event

{
    "_id": "5c1821dbc6b7baf3435e1d23",
    "eventType": "task-status-patched",
    "eventTime": "2021-01-13T19:43:26.097Z",
    "product": "deposit",
    "user": {
        "_id": "5c17c632e1d8ca3b08b2586f",
        "identifier": "YOUR_UNIQUE_GUID"
    },
    "company": {
        "name": "Home Depot",
        "branding": {
            "logo": {
                "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
            }
        }
    },
    "task": "5d97e4abc90a0a0007993e9c",
    "data": {
        "previousStatus": "failed",
        "status": "completed"
    }
}

The status of a Task was patched. Possible statuses include:

Task authentication status updated

Example task-authentication-status-updated event

{
    "_id": "5c1821dbc6b7baf3435e1d23",
    "eventType": "task-authentication-status-updated",
    "eventTime": "2021-01-13T19:43:26.097Z",
    "product": "deposit",
    "user": {
        "_id": "5c17c632e1d8ca3b08b2586f",
        "identifier": "YOUR_UNIQUE_GUID"
    },
    "company": {
        "name": "Home Depot",
        "branding": {
            "logo": {
                "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
            }
        }
    },
    "task": "5d97e4abc90a0a0007993e9c",
    "data": {
        "authenticated": true
    }
}

The authentication status of a Task was updated. Possible authenticated statuses include:

Outputs

Sample response for verify

{
    "eventType": "task-status-updated",
    "eventTime": "2020-01-28T22:04:18.778Z",
    "product": "verify",
    "user": {
        "_id": "5d8d3fecbf637ef3b11a877a",
        "identifier": "YOUR_INTERNAL_GUID"
    },
    "task": "5e30afde097146a8fc3d5cec",
    "company": {
        "name": "Home Depot",
        "branding": {
            "logo": {
                "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
            }
        }
    },
    "data": {
        "previousStatus": "processing",
        "status": "completed",
        "outputs": {
            "income": "45000",
            "incomeType": "yearly",
            "employeeType": "fulltime",
            "employmentStatus": "active",
            "jobTitle": "Product Manager",
            "startDate": "4/19/2017",
            "weeklyHours": "40",
            "statements": [
                {
                    "date": "2020-01-01T00:00:00.000Z",
                    "grossAmount": "1266.11",
                    "netAmount": "1014.29",
                    "paymentMethod": "deposit",
                    "paystub": "https://example.url/statement1.pdf",
                    "hours": "32"
                },
                {
                    "date": "2019-12-15T00:00:00.000Z",
                    "grossAmount": "1266.11",
                    "netAmount": "1014.29",
                    "paymentMethod": "deposit",
                    "paystub": "https://example.url/statement2.pdf",
                    "hours": "32"
                }
            ],
            "accounts": [
                {
                    "accountNumber": "220000000",
                    "routingNumber": "110000000",
                    "type": "checking",
                    "distributionType": "total"
                }
            ]
        }
    }
}

Outputs for the verify product

Nested object properties

Statement

Sample statement

{
    "date": "2020-01-01T00:00:00.000Z",
    "grossAmount": "1266.11",
    "netAmount": "1014.29",
    "paymentMethod": "deposit",
    "paystub": "https://example.url/statement1.pdf",
    "hours": "32"
}

Properties

Deposit account

Sample deposit account

{
    "accountNumber": "220000000",
    "routingNumber": "110000000",
    "type": "checking",
    "distributionType": "percent",
    "distributionAmount": "75"
}

Properties

Sample response for identify

{
    "eventType": "task-status-updated",
    "eventTime": "2020-01-28T22:04:18.778Z",
    "product": "identify",
    "user": {
        "_id": "5d8d3fecbf637ef3b11a877a",
        "identifier": "YOUR_INTERNAL_GUID"
    },
    "task": "5e30afde097146a8fc3d5cec",
    "data": {
        "previousStatus": "processing",
        "status": "completed",
        "outputs": {
            "firstName": "Jane",
            "lastName": "Appleseed",
            "dateOfBirth": "6/4/98",
            "email": "jane@doe.com",
            "phone": "5558881111",
            "ssn": "111223333",
            "address": "123 Example St.",
            "city": "Salt Lake City",
            "state": "UT",
            "postalCode": "84111"
        }
    }
}

Outputs for the identify product

Fail Reasons

API Reference

Create Access Token

Code samples

# You can also use wget
curl --location --request POST "https://api.atomicfi.com/access-token" \
  --header "Content-Type: application/json" \
  --header "x-api-key: f0d0a166-96de-4898-8879-da309801968b" \
  --header "x-api-secret: afcce08f-95bd-4317-9119-ecb8debae4f2" \
  --data "{
	\"identifier\": \"YOUR_INTERNAL_GUID\",
	\"phone\": \"8016554444\",
	\"email\": \"jdoe@example.org\",
	\"names\": [
		{
			\"firstName\": \"Jane\",
			\"lastName\": \"Doe\"
		}
	],
	\"addresses\": [
		{
			\"line1\": \"123 Atomic Ave.\",
			\"line2\": \"Apt. #1\",
			\"city\": \"Salt Lake City\",
			\"state\": \"UT\",
			\"zipcode\": \"84044\",
			\"country\": \"US\"
		}
	],
	\"accounts\": [
		{
			\"accountNumber\": \"220000000\",
			\"routingNumber\": \"110000000\",
			\"type\": \"checking\",
			\"title\": \"Premier Plus Checking\"
		}
	]
}"

var https = require('https');

var options = {
  'method': 'POST',
  'hostname': 'https://api.atomicfi.com',
  'path': '/access-token',
  'headers': {
    'Content-Type': 'application/json',
    'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
    'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
  }
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData =  "{\n\t\"identifier\": \"YOUR_INTERNAL_GUID\",\n\t\"phone\": \"8016554444\",\n\t\"email\": \"jdoe@example.org\",\n\t\"names\": [\n\t\t{\n\t\t\t\"firstName\": \"Jane\",\n\t\t\t\"lastName\": \"Doe\"\n\t\t}\n\t],\n\t\"addresses\": [\n\t\t{\n\t\t\t\"line1\": \"123 Atomic Ave.\",\n\t\t\t\"line2\": \"Apt. #1\",\n\t\t\t\"city\": \"Salt Lake City\",\n\t\t\t\"state\": \"UT\",\n\t\t\t\"zipcode\": \"84044\",\n\t\t\t\"country\": \"US\"\n\t\t}\n\t],\n\t\"accounts\": [\n\t\t{\n\t\t\t\"accountNumber\": \"220000000\",\n\t\t\t\"routingNumber\": \"110000000\",\n\t\t\t\"type\": \"checking\",\n\t\t\t\"title\": \"Premier Plus Checking\"\n\t\t}\n\t]\n}";

req.write(postData);

req.end();

require "uri"
require "net/http"

url = URI("https://api.atomicfi.com/access-token")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["x-api-key"] = "f0d0a166-96de-4898-8879-da309801968b"
request["x-api-secret"] = "afcce08f-95bd-4317-9119-ecb8debae4f2"
request.body = "{\n\t\"identifier\": \"YOUR_INTERNAL_GUID\",\n\t\"phone\": \"8016554444\",\n\t\"email\": \"jdoe@example.org\",\n\t\"names\": [\n\t\t{\n\t\t\t\"firstName\": \"Jane\",\n\t\t\t\"lastName\": \"Doe\"\n\t\t}\n\t],\n\t\"addresses\": [\n\t\t{\n\t\t\t\"line1\": \"123 Atomic Ave.\",\n\t\t\t\"line2\": \"Apt. #1\",\n\t\t\t\"city\": \"Salt Lake City\",\n\t\t\t\"state\": \"UT\",\n\t\t\t\"zipcode\": \"84044\",\n\t\t\t\"country\": \"US\"\n\t\t}\n\t],\n\t\"accounts\": [\n\t\t{\n\t\t\t\"accountNumber\": \"220000000\",\n\t\t\t\"routingNumber\": \"110000000\",\n\t\t\t\"type\": \"checking\",\n\t\t\t\"title\": \"Premier Plus Checking\"\n\t\t}\n\t]\n}"

response = http.request(request)
puts response.read_body

import requests
url = 'https://api.atomicfi.com/access-token'
payload = "{\n\t\"identifier\": \"YOUR_INTERNAL_GUID\",\n\t\"phone\": \"8016554444\",\n\t\"email\": \"jdoe@example.org\",\n\t\"names\": [\n\t\t{\n\t\t\t\"firstName\": \"Jane\",\n\t\t\t\"lastName\": \"Doe\"\n\t\t}\n\t],\n\t\"addresses\": [\n\t\t{\n\t\t\t\"line1\": \"123 Atomic Ave.\",\n\t\t\t\"line2\": \"Apt. #1\",\n\t\t\t\"city\": \"Salt Lake City\",\n\t\t\t\"state\": \"UT\",\n\t\t\t\"zipcode\": \"84044\",\n\t\t\t\"country\": \"US\"\n\t\t}\n\t],\n\t\"accounts\": [\n\t\t{\n\t\t\t\"accountNumber\": \"220000000\",\n\t\t\t\"routingNumber\": \"110000000\",\n\t\t\t\"type\": \"checking\",\n\t\t\t\"title\": \"Premier Plus Checking\"\n\t\t}\n\t]\n}"
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
  'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
}
response = requests.request('POST', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)
print(response.text)

package main

import (
  "fmt"
  "strings"
  "os"
  "path/filepath"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.atomicfi.com/access-token"
  method := "POST"

  payload := strings.NewReader("{\n	\"identifier\": \"YOUR_INTERNAL_GUID\",\n	\"phone\": \"8016554444\",\n	\"email\": \"jdoe@example.org\",\n	\"names\": [\n		{\n			\"firstName\": \"Jane\",\n			\"lastName\": \"Doe\"\n		}\n	],\n	\"addresses\": [\n		{\n			\"line1\": \"123 Atomic Ave.\",\n			\"line2\": \"Apt. #1\",\n			\"city\": \"Salt Lake City\",\n			\"state\": \"UT\",\n			\"zipcode\": \"84044\",\n			\"country\": \"US\"\n		}\n	],\n	\"accounts\": [\n		{\n			\"accountNumber\": \"220000000\",\n			\"routingNumber\": \"110000000\",\n			\"type\": \"checking\",\n			\"title\": \"Premier Plus Checking\"\n		}\n	]\n}")

  client := &http.Client {
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
      return http.ErrUseLastResponse
    },
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("x-api-key", "f0d0a166-96de-4898-8879-da309801968b")
  req.Header.Add("x-api-secret", "afcce08f-95bd-4317-9119-ecb8debae4f2")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

Example request

{
    "identifier": "YOUR_INTERNAL_GUID",
    "phone": "8016554444",
    "email": "jdoe@example.org",
    "expiry": "2019-12-06T12:22:54Z",
    "names": [
        {
            "firstName": "Jane",
            "lastName": "Doe"
        }
    ],
    "addresses": [
        {
            "line1": "123 Atomic Ave.",
            "line2": "Apt. #1",
            "city": "Salt Lake City",
            "state": "UT",
            "zipcode": "84044",
            "country": "US"
        }
    ],
    "accounts": [
        {
            "accountNumber": "220000000",
            "routingNumber": "110000000",
            "type": "checking",
            "title": "Premier Plus Checking"
        }
    ]
}

An AccessToken grants access to Atomic's API resources for a specific user.

HTTP Request

POST /access-token

Authentication headers

Request properties

Nested object properties

Account

Bank account example

{
    "accountNumber": "220000000",
    "routingNumber": "110000000",
    "type": "checking",
    "title": "Premier Plus Checking"
}

Card account example

{
    "accountNumber": "4111111111111111",
    "title": "ABC Bank Platinum Card",
    "type": "card",
    "transferLimit": "50000"
}

Properties

Name

Name example

{
    "firstName": "Jane",
    "lastName": "Doe"
}

Properties

Address

Address example

{
    "line1": "123 Atomic Ave.",
    "line2": "Apt. #1",
    "city": "Salt Lake City",
    "state": "UT",
    "zipcode": "84044",
    "country": "US"
}

Properties

Response

Example response

{
    "data": {
        "publicToken": "6e93549e-3571-4f57-b0f7-77b7cb0b5e48",
        "token": "c00f869e-0fce-4d32-9277-a68658578ba2",
        "publicTokenExpiration": "2019-12-06T12:22:54Z"
    }
}

Successfully creating an Access Token will return a payload with a data object containing both a public publicToken and a private token. The publicToken may be used to initialize the Transact SDK. If you plan on making subsequent API requests for this user, we recommend saving these tokens to authenticate future requests.

Response Properties

List Linked Accounts

Code samples

curl --location --request GET "https://api.atomicfi.com/linked-account/list/{identifier}" \
  --header "x-api-key: f0d0a166-96de-4898-8879-da309801968b" \
  --header "x-api-secret: afcce08f-95bd-4317-9119-ecb8debae4f2" \

var https = require('https');

var options = {
  'method': 'GET',
  'hostname': 'https://api.atomicfi.com',
  'path': '/linked-account/list/{identifier}',
  'headers': {
    'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
    'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
  }
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

require "uri"
require "net/http"

url = URI("https://api.atomicfi.com/linked-account/list/{identifier}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["x-api-key"] = "f0d0a166-96de-4898-8879-da309801968b"
request["x-api-secret"] = "afcce08f-95bd-4317-9119-ecb8debae4f2"

response = http.request(request)
puts response.read_body

import requests
url = 'https://api.atomicfi.com/linked-account/list/{identifier}'
payload = {}
headers = {
  'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
  'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
}
response = requests.request('GET', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)
print(response.text)

package main

import (
  "fmt"
  "os"
  "path/filepath"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.atomicfi.com/linked-account/list/{identifier}"
  method := "GET"

  client := &http.Client {
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
      return http.ErrUseLastResponse
    },
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("x-api-key", "f0d0a166-96de-4898-8879-da309801968b")
  req.Header.Add("x-api-secret", "afcce08f-95bd-4317-9119-ecb8debae4f2")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

If enabled on your account, can be used to list accounts linked to a particular user.

HTTP Request

GET /linked-account/list/{identifier}

Authentication headers

Request properties

Response

Example response

{
    "data": [
        {
            "_id": "5f7212103a40e91f95ba376d",
            "valid": true,
            "connector": {
                "_id": "5d77f95207085632a58945c3",
                "name": "ADP",
                "branding": {}
            },
            "company": {
                "_id": "5d77f9e1070856f3828945c6",
                "name": "DoTerra",
                "branding": {
                    "logo": {
                        "_id": "5eb62781b4b83f0008f638cc",
                        "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
                    }
                }
            },
            "lastSuccess": "2020-09-28T16:40:48.009Z",
            "transactRequired": false
        }
    ]
}

LinkedAccount object

Use a Linked Account

Code samples

curl --location --request POST "https://api.atomicfi.com/task/create" \
  --header "Content-Type: application/json" \
  --header "x-api-key: f0d0a166-96de-4898-8879-da309801968b" \
  --header "x-api-secret: afcce08f-95bd-4317-9119-ecb8debae4f2" \
  --data "{
    \"product\": \"verify\",
    \"linkedAccount\": \"5d77f9e1070856f3828945c6\"
}"

var https = require('https');

var options = {
  'method': 'POST',
  'hostname': 'https://api.atomicfi.com',
  'path': '/task/create',
  'headers': {
    'Content-Type': 'application/json',
    'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
    'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
  }
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData =  "{\n    \"product\": \"verify\",\n    \"linkedAccount\": \"5d77f9e1070856f3828945c6\",\n    }\n}";

req.write(postData);

req.end();

require "uri"
require "net/http"

url = URI("https://api.atomicfi.com/task/create")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["x-api-key"] = "f0d0a166-96de-4898-8879-da309801968b"
request["x-api-secret"] = "afcce08f-95bd-4317-9119-ecb8debae4f2"
request.body = "{\n    \"product\": \"verify\",\n    \"linkedAccount\": \"5d77f9e1070856f3828945c6\"\n    }\n}"

response = http.request(request)
puts response.read_body

import requests
url = 'https://api.atomicfi.com/task/create'
payload = "{\n    \"product\": \"verify\",\n    \"linkedAccount\": \"5d77f9e1070856f3828945c6\"\n    }\n}"
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'f0d0a166-96de-4898-8879-da309801968b',
  'x-api-secret': 'afcce08f-95bd-4317-9119-ecb8debae4f2'
}
response = requests.request('POST', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)
print(response.text)

package main

import (
  "fmt"
  "strings"
  "os"
  "path/filepath"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.atomicfi.com/task/create"
  method := "POST"

  payload := strings.NewReader("{\n    \"product\": \"verify\",\n    \"linkedAccount\": \"5d77f9e1070856f3828945c6\"\n    }\n}")

  client := &http.Client {
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
      return http.ErrUseLastResponse
    },
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("x-api-key", "f0d0a166-96de-4898-8879-da309801968b")
  req.Header.Add("x-api-secret", "afcce08f-95bd-4317-9119-ecb8debae4f2")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

Request body example

{
    "product": "verify",
    "linkedAccount": "5d77f9e1070856f3828945c6"
}

To generate a task using a Linked Account, a Task request is created that contains the product and the _id of the LinkedAccount. A Task is then created if the request is successful.

HTTP Request

POST /task/create

Authentication headers

Request properties

Response

Example responses

{
    "data": {
        "id": "5d3b23b155f500465c895f60",
        "status": "queued"
    }
}

Successfully creating a Task will return a payload with a data object containing both a public _id_ and a private status of queued. The status will change as the task progresses towards completion. The Atomic Dashboard can be used to track task progress. If you plan on implementing webhooks, we recommend saving the task _id for reference.

Response Properties

Company Search

Code samples

curl --location --request GET "https://api.atomicfi.com/company/search?query=microsoft&product=deposit" \
  --header "x-public-token: e0d2f67e-dc98-45d8-8b22-db76cb52f732"

var https = require('https');

var options = {
  'method': 'GET',
  'hostname': 'https://api.atomicfi.com',
  'path': '/company/search?query=microsoft&product=deposit',
  'headers': {
    'x-public-token': 'e0d2f67e-dc98-45d8-8b22-db76cb52f732'
  }
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

req.end();

require "uri"
require "net/http"

url = URI("https://api.atomicfi.com/company/search?query=microsoft&product=deposit")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["x-public-token"] = "e0d2f67e-dc98-45d8-8b22-db76cb52f732"

response = http.request(request)
puts response.read_body

import requests
url = 'https://api.atomicfi.com/company/search?query=microsoft&product=deposit'
payload = {}
headers = {
  'x-public-token': 'e0d2f67e-dc98-45d8-8b22-db76cb52f732'
}
response = requests.request('GET', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)
print(response.text)

package main

import (
  "fmt"
  "os"
  "path/filepath"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.atomicfi.com/company/search?query=microsoft&product=deposit"
  method := "GET"

  client := &http.Client {
    CheckRedirect: func(req *http.Request, via []*http.Request) error {
      return http.ErrUseLastResponse
    },
  }
  req, err := http.NewRequest(method, url, nil)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("x-public-token", "e0d2f67e-dc98-45d8-8b22-db76cb52f732")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

Searches for a Company using a text query. Searches can also be narrowed by passing in a specific product. The primary use case of this endpoint is for an autocomplete search component.

HTTP Request

GET /company/search

Authentication headers

                                        |

Request properties

Response

Example response

{
    "data": [
        {
            "_id": "5d38f1e8512bbf71fb776015",
            "name": "Wells Fargo",
            "connector": {
                "_id": "5d38f182512bbf0c06776013",
                "availableProducts": ["balance"]
            },
            "branding": {
                "logo": "https://atomicfi-public.s3.amazonaws.com/1b27b5a3-db2d-4dbd-83e9-5e256a91d573.svg",
                "color": "#FFFFFF"
            }
        }
    ]
}

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

Company object

Connector Search

Searches for a Connector using a text query. Searches can also be narrowed by passing in a specific product. The primary use case of this endpoint is for an autocomplete search component.

HTTP Request

GET /connector/search

Authentication headers

                                        |

Request properties

Response

Example response

{
    "success": true,
    "data": [
        {
            "_id": "5da2a2372a5c5600081d0052",
            "options": {
                "inputs": [
                    {
                        "title": "Username",
                        "name": "username",
                        "type": "text",
                        "placeholder": "Username"
                    },
                    {
                        "title": "Password",
                        "name": "password",
                        "type": "password",
                        "placeholder": "Password"
                    }
                ],
                "loginRecoveryOptions": [
                    {
                        "_id": "5e97992de81d67000802dda7",
                        "action": "url",
                        "title": "Recover User ID/Password",
                        "url": "https://netsecure.adp.com/ilink/pub/smsess/v3/forgot/theme.jsp?returnUrl=https%3A%2F%2Fmy.adp.com%2Fstatic%2Fredbox%2Flogin.html&totalURL=https://my.adp.com/static/redbox/login.html",
                        "flow": ""
                    },
                    {
                        "_id": "5e97992de81d67000802dda8",
                        "title": "Create Account",
                        "url": "https://netsecure.adp.com/pages/sms/ess/v3/pub/ssr/theme.jsp?returnUrl=https%3A%2F%2Fmy.adp.com%2Fstatic%2Fredbox%2Flogin.html",
                        "action": "url"
                    }
                ]
            },
            "name": "ADP",
            "createdAt": "2019-10-13T04:04:07.598Z",
            "branding": {
                "color": "#E20000",
                "logo": {
                    "_id": "5ed93faa3e36220007d157f6",
                    "url": "https://atomicfi-public-production.s3.amazonaws.com/a8d7e778-b718-45e0-b639-2305e33e7f95_ADP.svg"
                }
            },
            "authenticators": [
                {
                    "_id": "5f0ded47a5892d50f7fb38bb",
                    "connector": "5f03b5d210b6e90007e536cf",
                    "buttonLabel": "Sign in with Mocky",
                    "optional": true
                }
            ],
            "isAuthenticator": false
        }
    ]
}

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

Connector object