Accounts

Learn how to configure accounts in your card program to manage spend.

Account holders and accounts have a 1:1 relationship. When an account holder is successfully created, an 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
  }  
}
tokenGlobally unique identifier for the account.
stateACTIVE, PAUSED, or CLOSED.
spend_limitSpend 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). A lifetime limit of 0 indicates that the lifetime limit feature is disabled.

Note that spend limits are enforced on the settled volume under an account and are therefore not recommended to be used for balance or reconciliation-level accuracy. Spend limits 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_tokensList 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_addressObject 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. If an AVS check is applied via an Auth Rule on transactions belonging to this account, this is the address that will be referenced. See Verification Address Schema here.
account_holderAccount 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. To update a default account's configuration, pass in default instead of an account_token. 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 new daily spend limit. 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.
Integer. Permitted values: 0 or greater.
monthly_spend_limit (optional)Amount (in cents) for the account's new monthly spend limit. 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.
Integer. Permitted values: 0 or greater.
lifetime_spend_limit (optional)Amount (in cents) for the account's new lifetime 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.
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. If AVS checks are enabled (see Authorization Rules [Beta] for more detail), this is the address that will be checked during authorization. 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

ACTIVEAccount is able to transact and create new cards.
PAUSEDAccount will not be able to transact or create new cards. It can be set back to ACTIVE.
CLOSEDAccount 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.