Lithic is a modern card-issuing and program-management platform offering REST APIs for cards, accounts, transactions, authorization control, ACH/wire payments, external bank accounts, account-holder KYC/KYB, 3-D Secure, tokenization, disputes, and webhooks. OpenAPI spec is published via Stainless and powers official SDKs in Node, Python, Go, Java, Kotlin.
REST API covering cards, accounts, account holders (KYC/KYB), authorization rules and 3DS, transactions, financial accounts, external bank accounts, ACH and wire payments, book ...
This document describes a conceptual GraphQL schema for the Lithic card-issuing and program-management platform. Lithic provides a REST API; this schema represents the same doma...
opencollection: 1.0.0
info:
name: Lithic Developer API
version: 1.0.0
request:
auth:
type: apikey
key: Authorization
value: '{{Authorization}}'
placement: header
items:
- info:
name: Account Holder
type: folder
items:
- info:
name: Get a list of individual or business account holders
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/account_holders
params:
- name: external_id
value: 00000000-0000-0000-0000-000000000001
type: query
description: If applicable, represents the external_id associated with the account_holder.
- name: limit
value: '10'
type: query
description: The number of account_holders to limit the response to.
- name: first_name
value: John
type: query
description: (Individual Account Holders only) The first name of the account holder. The query is case insensitive
and supports partial matches.
- name: last_name
value: Appleseed
type: query
description: (Individual Account Holders only) The last name of the account holder. The query is case insensitive
and supports partial matches.
- name: legal_business_name
value: Busy Business, Inc.
type: query
description: (Business Account Holders only) The legal business name of the account holder. The query is case insensitive
and supports partial matches.
- name: phone_number
value: '+15555555555'
type: query
description: Phone number of the account holder. The query must be an exact match.
- name: email
value: example@domain.com
type: query
description: Email address of the account holder. The query must be an exact match, case insensitive.
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
- name: begin
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time
zone.
- name: end
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC
time zone.
docs: Get a list of individual or business account holders and their KYC or KYB evaluation status.
- info:
name: Create an individual or business account holder
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/account_holders
body:
type: json
data: '{}'
docs: 'Create an account holder and initiate the appropriate onboarding workflow. Account holders and accounts have a
1:1 relationship. When an account holder is successfully created an associated account is also created.
All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some
cases, the response may indicate the workflow is under review or further action will be needed to complete the account
creation process.
This endpoint can only be use'
- info:
name: Get an individual or business account holder
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
docs: Get an Individual or Business Account Holder and/or their KYC or KYB evaluation status.
- info:
name: Update account holder information and possibly resubmit for evaluation
type: http
http:
method: PATCH
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
body:
type: json
data: '{}'
docs: 'Update the information associated with a particular account holder (including business owners and control persons
associated to a business account).
If Lithic is performing KYB or KYC and additional verification is required we will run the individual''s or business''s
updated information again and return whether the status is accepted or pending (i.e., further action required).
All calls to this endpoint will return a synchronous response. The response time will depend on the workflow. In some
cas'
- info:
name: Get account holder document uploads
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token/documents
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
docs: 'Retrieve the status of account holder document uploads, or retrieve the upload URLs to process your image uploads.
Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully
uploaded but not be sufficient for KYC to pass).
In the event your upload URLs have expired, calling this endpoint will refresh them.
Similarly, in the event a previous account holder document upload has failed, you can use this endpoint to get a new
upload URL for'
- info:
name: Initiate account holder document upload
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token/documents
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
body:
type: json
data: '{}'
docs: 'Use this endpoint to identify which type of supported government-issued documentation you will upload for further
verification.
It will return two URLs to upload your document images to - one for the front image and one for the back image.
This endpoint is only valid for evaluations in a `PENDING_DOCUMENT` state.
Supported file types include `jpg`, `png`, and `pdf`. Each file must be less than 15 MiB. Once both required uploads
have been successfully completed, your document will be run throug'
- info:
name: Get account holder document upload status
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token/documents/:document_token
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
- name: document_token
value: ''
type: path
description: Globally unique identifier for the document.
docs: 'Check the status of an account holder document upload, or retrieve the upload URLs to process your image uploads.
Note that this is not equivalent to checking the status of the KYC evaluation overall (a document may be successfully
uploaded but not be sufficient for KYC to pass).
In the event your upload URLs have expired, calling this endpoint will refresh them.
Similarly, in the event a document upload has failed, you can use this endpoint to get a new upload URL for the failed
image upload.'
- info:
name: Create a new beneficial owner individual or replace the existing control person entity
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token/entities
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
body:
type: json
data: '{}'
docs: 'Create a new beneficial owner individual or replace the control person entity on an existing KYB account holder.
This endpoint is only applicable for account holders enrolled through a KYB workflow with the Persona KYB provider.
A new control person can only replace the existing one. A maximum of 4 beneficial owners can be associated with an account
holder.'
- info:
name: Deactivate a beneficial owner individual
type: http
http:
method: DELETE
url: https://sandbox.lithic.com/v1/account_holders/:account_holder_token/entities/:entity_token
params:
- name: account_holder_token
value: ''
type: path
description: Globally unique identifier for the account holder.
- name: entity_token
value: ''
type: path
description: Globally unique identifier for the entity.
docs: Deactivate a beneficial owner individual on an existing KYB account holder. Only beneficial owner individuals can
be deactivated.
- info:
name: Simulate an account holder's enrollment review
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/simulate/account_holders/enrollment_review
body:
type: json
data: '{}'
docs: ' Simulates an enrollment review for an account holder. This endpoint is only applicable for workflows that may
required intervention such as `KYB_BASIC`. '
- info:
name: Simulate an account holder document upload's review
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/simulate/account_holders/enrollment_document_review
body:
type: json
data: '{}'
docs: Simulates a review for an account holder document upload.
- info:
name: Account
type: folder
items:
- info:
name: List accounts
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/accounts
params:
- name: begin
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time
zone.
- name: end
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC
time zone.
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
docs: 'List account configurations.
'
- info:
name: Get account
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/accounts/:account_token
params:
- name: account_token
value: ''
type: path
description: Globally unique identifier for account.
docs: Get account configuration such as spend limits.
- info:
name: Update account
type: http
http:
method: PATCH
url: https://sandbox.lithic.com/v1/accounts/:account_token
params:
- name: account_token
value: ''
type: path
description: Globally unique identifier for account.
body:
type: json
data: '{}'
docs: 'Update account configuration such as state or spend limits. Can only be run on accounts that are part of the program
managed by this API key.
Accounts that are in the `PAUSED` state will not be able to transact or create new cards.
'
- info:
name: Get account's available spend limits
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/accounts/:account_token/spend_limits
params:
- name: account_token
value: ''
type: path
description: Globally unique identifier for account.
docs: Get an Account's available spend limits, which is based on the spend limit configured on the Account and the amount
already spent over the spend limit's duration. For example, if the Account has a daily spend limit of $1000 configured,
and has spent $600 in the last 24 hours, the available spend limit returned would be $400.
- info:
name: Fetch account signals
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/accounts/:account_token/signals
params:
- name: account_token
value: ''
type: path
description: The token of the account to fetch signals for.
docs: 'Returns behavioral feature state derived from an account''s transaction history.
These signals expose the same data used by behavioral rule attributes (e.g. `AMOUNT_Z_SCORE`
with `scope: ACCOUNT`, `IS_NEW_COUNTRY` with `scope: ACCOUNT`) and custom code
`TRANSACTION_HISTORY_SIGNALS` features, allowing clients to inspect feature values before
writing rules and debug rule behavior.
Note: 3DS fields are not available at the account scope and will be null.
'
- info:
name: Auth Rules
type: folder
items:
- info:
name: List rules
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules
params:
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
- name: card_token
value: ''
type: query
description: Only return Auth Rules that are bound to the provided card token.
- name: account_token
value: ''
type: query
description: Only return Auth Rules that are bound to the provided account token.
- name: business_account_token
value: ''
type: query
description: Only return Auth Rules that are bound to the provided business account token.
- name: scope
value: ''
type: query
description: Only return Auth Rules that are bound to the provided scope.
- name: event_stream
value: ''
type: query
description: 'Deprecated: Use event_streams instead. Only return Auth rules that are executed during the provided
event stream.'
- name: event_streams
value: ''
type: query
description: Only return Auth rules that are executed during any of the provided event streams. If event_streams and
event_stream are specified, the values will be combined.
docs: Lists V2 Auth rules
- info:
name: Create a new rule
type: http
http:
method: POST
url: https://sandbox.lithic.com/v2/auth_rules
body:
type: json
data: '{}'
docs: Creates a new V2 Auth rule in draft mode
- info:
name: Fetch a rule
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token
params:
- name: auth_rule_token
value: ''
type: path
docs: Fetches a V2 Auth rule by its token
- info:
name: Update a rule
type: http
http:
method: PATCH
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token
params:
- name: auth_rule_token
value: ''
type: path
body:
type: json
data: '{}'
docs: 'Updates a V2 Auth rule''s properties
If `account_tokens`, `card_tokens`, `program_level`, `excluded_card_tokens`, `excluded_account_tokens`, or `excluded_business_account_tokens`
is provided, this will replace existing associations with the provided list of entities.
'
- info:
name: Delete a rule
type: http
http:
method: DELETE
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token
params:
- name: auth_rule_token
value: ''
type: path
docs: Deletes a V2 Auth rule
- info:
name: Draft a new rule version
type: http
http:
method: POST
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/draft
params:
- name: auth_rule_token
value: ''
type: path
body:
type: json
data: '{}'
docs: 'Creates a new draft version of a rule that will be ran in shadow mode.
This can also be utilized to reset the draft parameters, causing a draft version to no longer be ran in shadow mode.
'
- info:
name: Calculated Feature values
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/features
params:
- name: auth_rule_token
value: ''
type: path
- name: account_token
value: ''
type: query
- name: card_token
value: ''
type: query
docs: 'Fetches the current calculated Feature values for the given Auth Rule
This only calculates the features for the active version.
- VelocityLimit Rules calculates the current Velocity Feature data. This requires a `card_token` or `account_token`
matching what the rule is Scoped to.
- ConditionalBlock Rules calculates the CARD_TRANSACTION_COUNT_* attributes on the rule. This requires a `card_token`
'
- info:
name: Promote a rule version
type: http
http:
method: POST
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/promote
params:
- name: auth_rule_token
value: ''
type: path
docs: Promotes the draft version of an Auth rule to the currently active version such that it is enforced in the respective
stream.
- info:
name: List rule versions
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/versions
params:
- name: auth_rule_token
value: ''
type: path
docs: Returns all versions of an auth rule, sorted by version number descending (newest first).
- info:
name: Retrieve a performance report
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/report
params:
- name: auth_rule_token
value: ''
type: path
- name: begin
value: ''
type: query
description: Start date for the report
- name: end
value: ''
type: query
description: End date for the report
docs: 'Retrieves a performance report for an Auth rule containing daily statistics and evaluation outcomes.
**Time Range Limitations:**
- Reports are supported for the past 3 months only
- Maximum interval length is 1 month
- Report data is available only through the previous day in UTC (current day data is not available)
The report provides daily statistics for both current and draft versions of the Auth rule, including approval, decline,
and challenge counts along with sample events.
'
- info:
name: List backtests
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/backtests
params:
- name: auth_rule_token
value: ''
type: path
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
docs: Lists backtests for an Auth Rule
- info:
name: Request a backtest
type: http
http:
method: POST
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/backtests
params:
- name: auth_rule_token
value: ''
type: path
body:
type: json
data: '{}'
docs: 'Initiates a request to asynchronously generate a backtest for an Auth rule. During backtesting, both the active
version (if one exists) and the draft version of the Auth Rule are evaluated by replaying historical transaction data
against the rule''s conditions. This process allows customers to simulate and understand the effects of proposed rule
changes before deployment.
The generated backtest report provides detailed results showing whether the draft version of the Auth Rule would have
approved'
- info:
name: Retrieve backtest results
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/:auth_rule_token/backtests/:auth_rule_backtest_token
params:
- name: auth_rule_token
value: ''
type: path
- name: auth_rule_backtest_token
value: ''
type: path
docs: 'Returns the backtest results of an Auth rule (if available).
Backtesting is an asynchronous process that requires time to complete. If a customer retrieves the backtest results
using this endpoint before the report is fully generated, the response will return null for `results.current_version`
and `results.draft_version`. Customers are advised to wait for the backtest creation process to complete (as indicated
by the webhook event auth_rules.backtest_report.created) before retrieving results fr'
- info:
name: List rule evaluation results
type: http
http:
method: GET
url: https://sandbox.lithic.com/v2/auth_rules/results
params:
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
- name: event_token
value: ''
type: query
description: Filter by event token
- name: auth_rule_token
value: ''
type: query
description: Filter by Auth Rule token
- name: begin
value: ''
type: query
description: Date string in RFC 3339 format. Only events evaluated after the specified time will be included. UTC
time zone.
- name: end
value: ''
type: query
description: Date string in RFC 3339 format. Only events evaluated before the specified time will be included. UTC
time zone.
- name: has_actions
value: ''
type: query
description: Filter by whether the rule evaluation produced any actions. When not provided, all results are returned.
docs: 'Lists Auth Rule evaluation results.
**Limitations:**
- Results are available for the past 3 months only
- At least one filter (`event_token` or `auth_rule_token`) must be provided
- When filtering by `event_token`, pagination is not supported
'
- info:
name: Card
type: folder
items:
- info:
name: Fetch card signals
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards/:card_token/signals
params:
- name: card_token
value: ''
type: path
description: The token of the card to fetch signals for.
docs: 'Returns behavioral feature state derived from a card''s transaction history.
These signals expose the same data used by behavioral rule attributes (e.g. `AMOUNT_Z_SCORE` with `scope: CARD`, `IS_NEW_COUNTRY`
with `scope: CARD`) and custom code `TRANSACTION_HISTORY_SIGNALS` features, allowing clients to inspect feature values
before writing rules and debug rule behavior.
'
- info:
name: List card programs
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/card_programs
params:
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
docs: List card programs.
- info:
name: Get card program
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/card_programs/:card_program_token
params:
- name: card_program_token
value: ''
type: path
description: Globally unique identifier for the card program.
docs: Get card program.
- info:
name: List cards
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards
params:
- name: account_token
value: ''
type: query
description: 'Returns cards associated with the specified account.
'
- name: state
value: ''
type: query
description: 'Returns cards with the specified state.
'
- name: memo
value: ''
type: query
description: 'Returns cards containing the specified partial or full memo text.
'
- name: begin
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time
zone.
- name: end
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC
time zone.
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: page_size
value: ''
type: query
description: Page size (for pagination).
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
docs: List cards.
- info:
name: Create card
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/cards
headers:
- name: Idempotency-Key
value: 65a9dad4-1b60-4686-83fd-65b25078a4b4
body:
type: json
data: '{}'
docs: 'Create a new virtual or physical card. Parameters `shipping_address` and `product_id` only apply to physical cards.
'
- info:
name: Search for card by PAN
type: http
http:
method: POST
url: https://sandbox.lithic.com/v1/cards/search_by_pan
body:
type: json
data: '{}'
docs: 'Get card configuration such as spend limit and state. Customers must be PCI compliant to use this endpoint. Please
contact [support@lithic.com](mailto:support@lithic.com) for questions.
*Note: this is a `POST` endpoint because it is more secure to send sensitive data in a request body than in a URL.*'
- info:
name: Get card
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards/:card_token
params:
- name: card_token
value: ''
type: path
docs: Get card configuration such as spend limit and state.
- info:
name: Update card
type: http
http:
method: PATCH
url: https://sandbox.lithic.com/v1/cards/:card_token
params:
- name: card_token
value: ''
type: path
body:
type: json
data: '{}'
docs: 'Update the specified properties of the card. Unsupplied properties will remain unchanged.
*Note: setting a card to a `CLOSED` state is a final action that cannot be undone.*
'
- info:
name: Get card balances
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards/:card_token/balances
params:
- name: balance_date
value: ''
type: query
description: UTC date of the balance to retrieve. Defaults to latest available balance
- name: last_transaction_event_token
value: ''
type: query
description: 'Balance after a given financial event occured.
For example, passing the event_token of a $5 CARD_CLEARING financial event will return a balance decreased by $5
'
- name: card_token
value: ''
type: path
docs: Get the balances for a given card.
- info:
name: List card financial transactions
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards/:card_token/financial_transactions
params:
- name: category
value: ''
type: query
description: Financial Transaction category to be returned.
- name: result
value: ''
type: query
description: Financial Transaction result to be returned.
- name: status
value: ''
type: query
description: Financial Transaction status to be returned.
- name: begin
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time
zone.
- name: card_token
value: ''
type: path
- name: end
value: ''
type: query
description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC
time zone.
- name: ending_before
value: ''
type: query
description: A cursor representing an item's token before which a page of results should end. Used to retrieve the
previous page of results before this item.
- name: starting_after
value: ''
type: query
description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the
next page of results after this item.
docs: List the financial transactions for a given card.
- info:
name: Get card financial transaction
type: http
http:
method: GET
url: https://sandbox.lithic.com/v1/cards/:card_token/financial_transactions/:financial_transaction_token
params:
- name: card_token
value: ''
type: path
- name: financial_transaction_token
value: ''
type: path
description: Globally unique identifier for financial transaction token.
docs: Get the card financial transaction for the provided token.
- info:
name: Provision card (Digital Wallet)
type: http
http:
method: POST
url: https://sandbox.lith
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lithic/refs/heads/main/apis.yml
