Retrieves task details and status, generates presigned file URLs, runs task prescreen confidence checks, and starts task workflows from an existing linked account. Tasks are the unit of work behind deposit, verify, and tax operations.
openapi: 3.0.3
info:
title: Atomic API
description: >-
Representative OpenAPI description of Atomic's payroll and financial
connectivity API (UserLink and PayLink). Atomic lets applications
switch direct deposit, verify income and employment, retrieve payroll
data, and update payment methods on file through user-permissioned
access. The Transact SDK is an embedded, hosted front-end launched with
a publicToken that drives deposit, verify, and tax task workflows on top
of these endpoints. This is a faithful, non-exhaustive representation
authored by API Evangelist from public documentation, not an official
Atomic artifact.
termsOfService: https://atomicfi.com/legal
contact:
name: Atomic Support
url: https://docs.atomicfi.com
version: '1.0'
servers:
- url: https://api.atomicfi.com
description: Production
- url: https://sandbox-api.atomicfi.com
description: Sandbox
- url: https://pci.atomicfi.com
description: Production PCI host (PayLink card data)
- url: https://sandbox-pci.atomicfi.com
description: Sandbox PCI host (PayLink card data)
security:
- ApiKeyAuth: []
tags:
- name: Access Tokens
- name: Transact
- name: Company
- name: Tasks
- name: Data
- name: Linked Accounts
- name: PayLink
- name: Users
- name: Webhooks
- name: Secrets
paths:
/access-token:
post:
operationId: createAccessToken
tags:
- Access Tokens
summary: Create an access token
description: >-
Exchanges your API Key and Secret for a publicToken used to
initialize the Transact SDK on the client. Called from your backend.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAccessTokenRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokenResponse'
/access-token/{publicToken}/revoke:
put:
operationId: revokeAccessToken
tags:
- Access Tokens
summary: Revoke an access token
description: Invalidates an existing publicToken so it can no longer access API resources.
parameters:
- $ref: '#/components/parameters/PublicTokenPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResult'
/company/search:
post:
operationId: searchCompanies
tags:
- Company
summary: Search companies
description: Find employers or merchants supported for a given product.
security:
- ApiKeyAuth: []
- PublicTokenAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanySearchRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Company'
/company/list:
get:
operationId: listCompanies
tags:
- Company
summary: List companies
parameters:
- name: product
in: query
schema:
type: string
enum: [deposit, verify, tax, manage]
- name: scope
in: query
schema:
type: string
example: user-link
- name: limit
in: query
schema:
type: integer
default: 100
- name: skip
in: query
schema:
type: integer
default: 0
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Company'
/company/{companyId}/details:
get:
operationId: getCompanyDetails
tags:
- Company
summary: Get company details
parameters:
- name: companyId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
/task/{taskId}/details:
get:
operationId: getTaskDetails
tags:
- Tasks
summary: Get task details
parameters:
- $ref: '#/components/parameters/TaskIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
/task/{taskId}/status:
get:
operationId: getTaskStatus
tags:
- Tasks
summary: Get task status
parameters:
- $ref: '#/components/parameters/TaskIdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatusResponse'
/task/{taskId}/file/{fileId}/generate-url:
get:
operationId: generateTaskFileUrl
tags:
- Tasks
summary: Generate a presigned file URL
parameters:
- $ref: '#/components/parameters/TaskIdPath'
- name: fileId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
/task/prescreen:
post:
operationId: prescreenTask
tags:
- Tasks
summary: Prescreen a task (beta)
description: Returns a confidence signal on whether a company can be connected for a product.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PrescreenRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
confidence:
type: string
enum: [HIGH, LOW]
/task-workflow/from-linked-account:
post:
operationId: createTaskWorkflowFromLinkedAccount
tags:
- Tasks
- Linked Accounts
summary: Start a task workflow from a linked account
description: >-
Runs deposit, verify, or tax tasks against an already-connected
linked account without re-authenticating the user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskWorkflowFromLinkedAccountRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TaskWorkflowResponse'
/deposit-accounts/{identifier}:
get:
operationId: getDepositAccounts
tags:
- Data
summary: Get deposit accounts
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/employment/{identifier}:
get:
operationId: getEmployment
tags:
- Data
summary: Get employment data
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/identity/{identifier}:
get:
operationId: getIdentity
tags:
- Data
summary: Get identity data
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/income/{identifier}:
get:
operationId: getIncome
tags:
- Data
summary: Get income data
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/statements/{identifier}:
get:
operationId: getStatements
tags:
- Data
summary: Get statements (paystubs)
parameters:
- $ref: '#/components/parameters/IdentifierPath'
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/timesheets/{identifier}:
get:
operationId: getTimesheets
tags:
- Data
summary: Get timesheets
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/taxes/{identifier}:
get:
operationId: getTaxes
tags:
- Data
summary: Get taxes (W-2 / 1099)
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/linked-account/list/{identifier}:
get:
operationId: listLinkedAccounts
tags:
- Linked Accounts
summary: List linked accounts
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LinkedAccount'
/pay-link/actions-for-company/{companyId}:
get:
operationId: getPayLinkActionsForCompany
tags:
- PayLink
summary: List available PayLink actions for a company
parameters:
- name: companyId
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/pay-link/accounts:
get:
operationId: getPayLinkAccounts
tags:
- PayLink
summary: Retrieve a user's connected PayLink accounts
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
/user:
put:
operationId: updateUser
tags:
- Users
summary: Update a user
description: Stores destination bank accounts or cards to present during a task workflow.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResult'
/user/{identifier}/tasks:
get:
operationId: getUserTasks
tags:
- Users
summary: Get a user's tasks
parameters:
- $ref: '#/components/parameters/IdentifierPath'
- name: status
in: query
schema:
type: string
- name: payrollDataAvailable
in: query
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
/user/{identifier}/end-monitoring:
put:
operationId: endUserMonitoring
tags:
- Users
summary: End monitoring for a user
parameters:
- $ref: '#/components/parameters/IdentifierPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResult'
/webhooks/endpoints:
get:
operationId: listWebhookEndpoints
tags:
- Webhooks
summary: List webhook endpoints
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebhookEndpoint'
post:
operationId: createWebhookEndpoint
tags:
- Webhooks
summary: Create a webhook endpoint
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
/webhooks/endpoints/{id}:
put:
operationId: updateWebhookEndpoint
tags:
- Webhooks
summary: Update a webhook endpoint
parameters:
- $ref: '#/components/parameters/IdPath'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpointRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookEndpoint'
delete:
operationId: deleteWebhookEndpoint
tags:
- Webhooks
summary: Delete a webhook endpoint
parameters:
- $ref: '#/components/parameters/IdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResult'
/secrets:
get:
operationId: listSecrets
tags:
- Secrets
summary: List signing secrets
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Secret'
post:
operationId: createSecret
tags:
- Secrets
summary: Create a signing secret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
/secrets/{id}:
delete:
operationId: deleteSecret
tags:
- Secrets
summary: Delete a signing secret
parameters:
- $ref: '#/components/parameters/IdPath'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResult'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API Key sent in the x-api-key header, paired with the x-api-secret
header. Used for backend-to-backend calls.
PublicTokenAuth:
type: apiKey
in: header
name: x-public-token
description: Public token for permitted client-side requests.
parameters:
IdentifierPath:
name: identifier
in: path
required: true
description: Your unique identifier for the end user.
schema:
type: string
TaskIdPath:
name: taskId
in: path
required: true
schema:
type: string
PublicTokenPath:
name: publicToken
in: path
required: true
schema:
type: string
IdPath:
name: id
in: path
required: true
schema:
type: string
schemas:
CreateAccessTokenRequest:
type: object
required:
- identifier
properties:
identifier:
type: string
description: Your unique identifier for the end user.
tokenLifetime:
type: integer
description: Lifetime of the returned publicToken in seconds.
example: 86400
AccessTokenResponse:
type: object
properties:
data:
type: object
properties:
publicToken:
type: string
CompanySearchRequest:
type: object
properties:
query:
type: string
product:
type: string
enum: [deposit, verify, tax, manage]
scopes:
type: array
items:
type: string
Company:
type: object
properties:
_id:
type: string
name:
type: string
status:
type: string
branding:
type: object
tags:
type: array
items:
type: string
PrescreenRequest:
type: object
properties:
company:
type: object
properties:
name:
type: string
id:
type: string
product:
type: string
enum: [deposit, verify, tax]
Task:
type: object
properties:
_id:
type: string
status:
type: string
enum: [queued, processing, completed, failed]
product:
type: string
authentication:
type: string
company:
$ref: '#/components/schemas/Company'
payrollDataAvailable:
type: boolean
createdAt:
type: string
format: date-time
TaskStatusResponse:
type: object
properties:
data:
type: object
properties:
task:
type: object
properties:
createdAt:
type: string
format: date-time
status:
type: string
enum: [queued, processing, completed, failed]
payrollDataAvailable:
type: boolean
failReason:
type: string
TaskWorkflowFromLinkedAccountRequest:
type: object
required:
- linkedAccount
- tasks
properties:
linkedAccount:
type: string
tasks:
type: array
items:
$ref: '#/components/schemas/TaskDefinition'
TaskDefinition:
type: object
properties:
operation:
type: string
enum: [deposit, verify, tax]
onComplete:
type: string
enum: [continue, finish]
onFail:
type: string
enum: [continue, finish]
distribution:
type: object
properties:
type:
type: string
enum: [total, fixed, percent]
amount:
type: number
TaskWorkflowResponse:
type: object
properties:
task:
$ref: '#/components/schemas/Task'
taskWorkflow:
type: string
LinkedAccount:
type: object
properties:
_id:
type: string
valid:
type: boolean
company:
$ref: '#/components/schemas/Company'
lastSuccess:
type: string
format: date-time
lastFailure:
type: string
format: date-time
UpdateUserRequest:
type: object
required:
- identifier
properties:
identifier:
type: string
data:
type: object
properties:
bankAccounts:
type: array
items:
type: object
cards:
type: array
items:
type: object
WebhookEndpointRequest:
type: object
required:
- url
- eventTypes
properties:
url:
type: string
format: uri
secretId:
type: string
eventTypes:
type: array
items:
type: string
example:
- task-status-updated
WebhookEndpoint:
type: object
properties:
_id:
type: string
url:
type: string
format: uri
eventTypes:
type: array
items:
type: string
Secret:
type: object
properties:
_id:
type: string
name:
type: string
token:
type: string
createdAt:
type: string
format: date-time
SuccessResult:
type: object
properties:
result:
type: object
properties:
success:
type: boolean
success:
type: boolean