Account holders and (card) accounts currently have a 1:1 relationship. When an account holder is successfully created, a account is also created.

Account Schema

{
  "token": String,
  "state": String,
  "spend_limit": {
      "daily": Integer,
      "monthly": Integer,
      "lifetime": Integer
  },
  "auth_rule_tokens": List,
  "verification_address": Object,
  "account_holder": {
      "token": String,
      "phone_number": String,
      "email": String,
      "business_account_token": String
  }  
}


token	Globally unique identifier for the account.
state	`ACTIVE`, `PAUSED`, or `CLOSED`.
spend_limit	Spend limit information for the user containing the daily, monthly, and lifetime spend limit of the account. Any charges to a card owned by this account will be declined once their transaction volume has surpassed the value in the applicable time limit (rolling). By default, the daily spend limit is set to $1,250.00 and the monthly spend limit is set to $5,000. A lifetime limit of 0 indicates that the lifetime limit feature is disabled. Account level spend limits are only enabled for non-ASA customers. Note that while spend limits are enforced based on authorized and settled volume on an account, they are not recommended to be used for balance or reconciliation-level accuracy. Spend limits also cannot block force posted charges (i.e., when a merchant sends a clearing message without a prior authorization - see here for more detail).
auth_rule_tokens	List of tokens identifying any Auth Rules that apply to the account. Any Auth Rules that apply either at the account or program level will appear.
verification_address	Object containing the address associated with the account. At initial account creation, this address is based on the individual's address (for individual account holders) or business entity's address (for business account holders) passed in during the Create Account Holder call.
account_holder	Account Holder Object mapped to the account, depending on if the account is an Individual or Business account holder. Individual accountholders using the KYC-exempt workflow of type `AUTHORIZED_USER` should also have a `business_account_token` in their Account Holder object.

List Account Configurations

API Reference: List accounts

Get details for all accounts. This endpoint can only be used for accounts that are managed by the program associated with the calling API key.

GET https://api.lithic.com/v1/accounts

{
  "data": [
    {
      "spend_limit": {
        "daily": 125000,
        "monthly": 500000,
        "lifetime": 0
      },
      "state": "ACTIVE",
      "token": "e87db14a-4abf-4901-adad-5d5c9f46aff2",
      "auth_rule_tokens": [
        "564b2a5d-bc7f-43ed-a21e-ec64a4f8e4d6"
      ],
      "verification_address": null,
      "account_holder": {
        "token": "95e5f1b7-cfd5-4520-aa3c-2451bab8608d",
        "phone_number": "12124007676",
        "email": "[email protected]",
        "business_account_token": null
      }
    },
  ],
  "total_entries": 1,
  "total_pages": 1,
  "page": 1
}


page_size (optional, query parameter)	For pagination - specifies the number of entries to be included on each page in the response. Default value is 50. Integer. Permitted values: 1-1000.
page (optional, query parameter)	For pagination - specifies the desired page to be included in the response. For example, if there are 3 total entries, and `page_size` is 2 (i.e., 2 entries per page), then entering the value `2` for `page` would return the second page and only the third entry. The default is one. Integer. Permitted values: 1 or greater.

Get Account Configuration

API Reference: Get account

To get a default account's configuration, pass in default instead of an account_token.

GET https://api.lithic.com/v1/accounts/{account_token}

Sample Request

curl https://api.lithic.com/v1/accounts/b68b7424-aa69-4cbc-a946-30d90181b621 \
    -H "Content-Type: application/json" \
    -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "spend_limit": {
    "daily": 125000,
    "monthly": 500000,
    "lifetime": 0
  },
  "state": "ACTIVE",
  "token": "e87db14a-4abf-4901-adad-5d5c9f46aff2",
  "auth_rule_tokens": [
    "564b2a5d-bc7f-43ed-a21e-ec64a4f8e4d6"
  ],
  "verification_address": null,
  "account_holder": {
    "token": "95e5f1b7-cfd5-4520-aa3c-2451bab8608d",
    "phone_number": "12124007676",
    "email": "[email protected]",
    "business_account_token": null
  }
}


account_token (required, path parameter)	Globally unique identifier for the account. If using this parameter, do not include pagination parameters `page` and `page_size`. String. Permitted values: 36-digit version 4 UUID (including hyphens).

Update Account Configuration

API Reference: Update account

Update account configurations that impact transaction authorizations such as spend limits and a verification address checked in real-time during authorizations. Only fields included in the request will be updated.

This endpoint can only be used for accounts that are managed by the program associated with the calling API key. Accounts that are in the PAUSED state will not be able to transact or create new cards.

PATCH https://api.lithic.com/v1/accounts/{account_token}

Sample Request

curl https://api.lithic.com/v1/accounts/{account_token} \
  -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
      "daily_spend_limit": 100000,
      "verification_address": {
         "address1": "124 Main Street",
         "city": "New York",
         "state": "NY",
         "postal_code": "10128",
         "country": "USA"
     }
}
'

Sample Response

{
  "spend_limit": {
    "daily": 25000,
    "monthly": 100000,
    "lifetime": 0
  },
  "state": "ACTIVE",
  "token": "e87db14a-4abf-4901-adad-5d5c9f46aff2",
  "auth_rule_tokens": [
    "564b2a5d-bc7f-43ed-a21e-ec64a4f8e4d6"
  ],
  "verification_address": {
    "address1": "124 Main Street",
    "address2": "",
    "city": "New York",
    "state": "NY",
    "postal_code": "10128",
    "country": "USA"
  },
  "account_holder": {
    "token": "95e5f1b7-cfd5-4520-aa3c-2451bab8608d",
    "phone_number": "12124007676",
    "email": "[email protected]",
    "business_account_token": null
  }
}


account_token (required, path parameter)	Globally unique identifier for the account. String. Permitted values: 36-digit version 4 UUID (including hyphens).
daily_spend_limit (optional)	Amount (in cents) for the account's daily spend limit. By default the daily spend limit is set to $1,250. Integer. Permitted values: 0 or greater.
monthly_spend_limit (optional)	Amount (in cents) for the account's monthly spend limit. By default the monthly spend limit is set to $5,000. Integer. Permitted values: 0 or greater.
lifetime_spend_limit (optional)	Amount (in cents) for the account's lifetime spend limit. Once this limit is reached, no transactions will be accepted on any card created for this account until the limit is updated. Note that a spend limit of 0 is effectively no limit, and should only be used to reset or remove a prior limit. Only a limit of 1 or above will result in declined transactions due to checks against the account limit. This behavior differs from the daily spend limit and the monthly spend limit. Integer. Permitted values: 0 or greater.
state (optional)	Indicates whether or not the account is in an active state (i.e., transactions can be accepted on cards belonging to this account). String. Permitted values: `ACTIVE`, `PAUSED`.
auth_rule_token (optional)	Globally unique identifier for the Auth Rule to be applied to all transactions under the account. String. Permitted values: 36-digit version 4 UUID (including hyphens).
verification_address (optional)	Object containing the address associated with the account. The default address contained in this object is based on the address passed in during the Create Account Holder call (individual's address for individual account holders and the control individual's address for business account holders). Object. Permitted values: Valid `address` object.

Verification Address Schema


address1 (required)	Valid deliverable address (no PO boxes). String.
address2 (optional)	Unit or apartment number (if applicable). String.
city (required)	City name. String.
state (required)	Valid state code. Only USA state codes are currently supported. String. Permitted values: Uppercase ISO 3166-2 two-character abbreviation for USA addresses. For example, "CA" for California.
postal_code (required)	Valid postal code. Only USA ZIP codes are currently supported. String. Permitted values: 5 or 10 characters. For US addresses, either five-digit zipcode or nine-digit "ZIP+4".
country (required)	Country name. Only USA is currently supported. String. Permitted values: Uppercase ISO 3166-1 alpha-3 three-character abbreviation. For example, `USA`.

Account States


ACTIVE	Account is able to transact and create new cards.
PAUSED	Account will not be able to transact or create new cards. It can be set back to `ACTIVE`.
CLOSED	Account will permanently not be able to transact or create new cards. Only Lithic can close accounts. This state normally occurs if an account enrollment fails KYC/KYB checks.