NAV Navbar
cURL

Introduction

Check Lockbox offers a simple API to managing check depositing.

For more information, or to sign up, follow the links below:

Home Page

Sign Up

Questions? Do not hesitate to reach out: hello@checklockbox.com

Authentication

The Check Lockbox API is organized around REST. You will need your API key to access all routes.

You authenticate to the Check Lockbox API by supplying your API keys in the request. Your API key gives you full access to the API, so be sure to keep it secret!

We use HTTP Basic Auth for the Check Lockbox API. Provide your API key as the basic auth username. Do not need to provide a password.

You must authenticate for all requests and may only make requests over HTTPS. Calls made over plain HTTP will fail.

$ curl https://api.checklockbox.com/v0/account \
   -u sk_test_1234567890:

Errors

HTTP Status Code Summary

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
403 Forbidden (Rate Limit Exceeded) - You have exceeded the request limit.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Check Lockbox's end.

Check Lockbox API uses regular HTTP response codes. Not all errors map cleanly to an HTTP response code. In general, 2xx codes indicate success. 4xx codes indicate an error with supplied parameters. 5xx codes indicate an error with Check Lockbox's servers.

Attributes

Parameter Description
type Type of the error returned. Can be invalid_request_error or api_error.
message A human-readable message letting you know exactly what went wrong.
param (optional)
The parameter the error relates to.

Pagination

All major objects in Check Lockbox support list API methods. All list responses share a common structure.

Check Lockbox supports cursor-based pagination, using the parameter starting_after to change where each page starts. See a full list of pagination parameters below. Note that all pagination parameters must be passed in the pagination hash.

Arguments

Argument Description
pagination[limit] optional default is 25
pagination[starting_after] optional
An object ID to use in pagination. For example, you receive a list of objects in a request ending with obj_foo, include pagination[starting_after]=obj_foo to get the next page.
pagination[ending_before] optional
An object ID to use in pagination. For example, you receive a list of objects in a request starting with obj_foo, include pagination[ending_before]=obj_foo to get the previous page.

Times

Check Lockbox uses UTC unix timestamps for all dates and times. Times are usually attributes ending in _at.

Filter by created_at

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v0/transactions?created_at[gt]=1437924748 \
--globoff \
-u sk_test_1234567890:

{
  "object": "check",
  "id": "chk_83ASDfhje83jdncle1284",
  "amount": 19900,
  "number": 10012,
  "account": "acct_ksdfj3409DKf93jhdk",
  "deposit": "dep_s8dFJsd83jdj939384",
  "scan_url": "https://files.checklockbox.com/asdflasdflkjasdflkjasfd/scan.png",
  "created_at": 1536231667,
  "updated_at": 1536231667,
  "created_at": "1437924749"
}

Sample Arguments

Argument Description
created_at optional
A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp:
  • gt for greater than
  • gte for greater than or equal to
  • lt for less than
  • lte for less thank or equal to

Throttling

The default throttling limit for Check Lockbox's APIs is 100 requests per minute. If you exceed this limit, you will receive a 403 Forbidden (Rate Limit Exceeded) error and should try again once the limit has reset.

---

Account

The account object

Retrieve your account to see properties on the account.

Attributes

Parameter Description
id string
object string value is "account" 
{
  "object": "account",
  "id": "acct_ksdfj3409DKf93jhdk",
  "business": "bus_klsjdfDKFJsdkf2345",
  "created_at": 1536232308,
  "updated_at": 1536232308
}

Retrieve account details

DEFINITION
GET https://api.checklockbox.com/v0/account

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v0/account \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "account",
  "id": "acct_ksdfj3409DKf93jhdk",
  "business": "bus_klsjdfDKFJsdkf2345",
  "created_at": 1536232308,
  "updated_at": 1536232308
}

Retrieves the account details based on the API key used to authenticate the request.

Arguments

No Arguments

RETURNS

An account object for the API key used to authenticate the request.

Checks

The check object

{
  "object": "check",
  "id": "chk_83ASDfhje83jdncle1284",
  "amount": 19900,
  "number": 10012,
  "account": "acct_ksdfj3409DKf93jhdk",
  "deposit": "dep_s8dFJsd83jdj939384",
  "scan_url": "https://files.checklockbox.com/asdflasdflkjasdflkjasfd/scan.png",
  "created_at": 1536231667,
  "updated_at": 1536231667
}

Attributes

Parameter Description
id string
object string value is "check"
amount integer
Amount in cents
number string
scan_url string
The url of the check scan image. This could be empty if a check was manually entered with no image attached.

Retrieve an existing check

DEFINITION
GET https://api.checklockbox.com/v1/checks/{check_ID}

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/checks/tr_3fj38099dalkxie \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "check",
  "id": "chk_83ASDfhje83jdncle1284",
  "amount": 19900,
  "number": 10012,
  "account": "acct_ksdfj3409DKf93jhdk",
  "deposit": "dep_s8dFJsd83jdj939384",
  "scan_url": "https://files.checklockbox.com/asdflasdflkjasdflkjasfd/scan.png",
  "created_at": 1536231667,
  "updated_at": 1536231667
}

Retrieves the details of a check that has previously been created. Supply a unique check ID that was returned in a previous request.

Arguments

Argument Description
id required
The identifier of the check to be retrieved.

Returns

Returns a check object if a valid identifier was provided, and returns an error otherwise.

List all checks

DEFINITION
GET https://api.checklockbox.com/v1/checks

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/checks \
-u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "check",
      "id": "chk_83ASDfhje83jdncle1284",
      "amount": 19900,
      "number": 10012,
      "account": "acct_ksdfj3409DKf93jhdk",
      "deposit": "dep_s8dFJsd83jdj939384",
      "scan_url": "https://files.checklockbox.com/asdflasdflkjasdflkjasfd/scan.png",
      "created_at": 1536231667,
      "updated_at": 1536231667
    }
  ]
}

Returns a list of checks you've previously created. The checks are returned in sorted order, with the most recent checks appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

Argument Description
created_at optional
A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp:
  • gt for greater than
  • gte for greater than or equal to
  • lt for less than
  • lte for less thank or equal to

    • See datetime filter examples here.

See Pagination section for supported pagination arguments.

Deposits

The deposit object

{
  "object": "deposit",
  "id": "dep_s8dFJsd83jdj939384",
  "amount": 197610,
  "account": "acct_ksdfj3409DKf93jhdk",
  "created_at": 1536801667,
  "updated_at": 1536801667
}

Attributes

Parameter Description
id string
object string value is "deposit"
amount integer
Amount in cents

Retrieve an existing deposit

DEFINITION
GET https://api.checklockbox.com/v1/deposits/{deposit_ID}

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/deposits/tr_3fj38099dalkxie \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "deposit",
  "id": "dep_s8dFJsd83jdj939384",
  "amount": 197610,
  "account": "acct_ksdfj3409DKf93jhdk",
  "created_at": 1536801667,
  "updated_at": 1536801667
}

Retrieves the details of a deposit that has previously been created. Supply a unique deposit ID that was returned in a previous request.

Arguments

Argument Description
id required
The identifier of the deposit to be retrieved.

Returns

Returns a deposit object if a valid identifier was provided, and returns an error otherwise.

List all deposits

DEFINITION
GET https://api.checklockbox.com/v1/deposits

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/deposits \
-u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "deposit",
      "id": "dep_s8dFJsd83jdj939384",
      "amount": 197610,
      "account": "acct_ksdfj3409DKf93jhdk",
      "created_at": 1536801667,
      "updated_at": 1536801667
    }
  ]
}

Returns a list of deposits you've previously created. The deposits are returned in sorted order, with the most recent deposits appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

Argument Description
created_at optional
A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp:
  • gt for greater than
  • gte for greater than or equal to
  • lt for less than
  • lte for less thank or equal to

    • See datetime filter examples here.

See Pagination section for supported pagination arguments.

Mailboxes

The mailbox object

{
  "object": "mailbox",
  "id": "mlbox_djkdf983jsls8xn",
  "account": "acct_ksdfj3409DKf93jhdk",
  "line1": "2261 Market Street",
  "line2": "Suite 20000",
  "city": "San Francisco",
  "state": "California",
  "zip": "94114",
  "suite_number": "20000",
  "created_at": 1536801667,
  "updated_at": 1536801667
}

Attributes

Parameter Description
id string
object string value is "mailbox"
amount integer
Amount in cents

Retrieve an existing mailbox

DEFINITION
GET https://api.checklockbox.com/v1/mailboxes/{mailbox_ID}

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/mailboxes/mlbox_djkdf983jsls8xn \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "mailbox",
  "id": "mlbox_djkdf983jsls8xn",
  "account": "acct_ksdfj3409DKf93jhdk",
  "line1": "2261 Market Street",
  "line2": "Suite 20000",
  "city": "San Francisco",
  "state": "California",
  "zip": "94114",
  "suite_number": "20000",
  "created_at": 1536801667,
  "updated_at": 1536801667
}

Retrieves the details of a mailbox that has previously been created. Supply a unique mailbox ID that was returned in a previous request.

Arguments

Argument Description
id required
The identifier of the mailbox to be retrieved.

Returns

Returns a mailbox object if a valid identifier was provided, and returns an error otherwise.

List all mailboxes

DEFINITION
GET https://api.checklockbox.com/v1/mailboxes

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/mailboxes \
-u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "mailbox",
      "id": "mlbox_djkdf983jsls8xn",
      "account": "acct_ksdfj3409DKf93jhdk",
      "line1": "2261 Market Street",
      "line2": "Suite 20000",
      "city": "San Francisco",
      "state": "California",
      "zip": "94114",
      "suite_number": "20000",
      "created_at": 1536801667,
      "updated_at": 1536801667
    }
  ]
}

Returns a list of mailboxes. If no results are found given the arguments, an empty list should be returned.

Banks

The bank object

{
  "object": "bank",
  "id": "bank_2983y47sdfj8348d",
  "name": "Sample Bank",
  "created_at": 1473847543,
  "updated_at": 1473847543
}

Attributes

Parameter Description
id string
object string value is "bank"
name string

Retrieve an existing bank

DEFINITION
GET https://api.checklockbox.com/v1/banks/BANK_ID

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/banks/ \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "bank",
  "id": "bank_2983y47sdfj8348d",
  "name": "Sample Bank",
  "created_at": 1473847543,
  "updated_at": 1473847543
}

Retrieves an existing bank.

Arguments

Argument Description
id required
The identifier of the bank to be retrieved.

Returns

Returns a bank object if a valid identifier was provided, and returns an error otherwise.

List all banks

DEFINITION
GET https://api.checklockbox.com/v1/banks

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/v1/banks \
-u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "bank",
      "id": "bank_2983y47sdfj8348d",
      "name": "Sample Bank",
      "created_at": 1473847543,
      "updated_at": 1473847543
    }
  ]
}

Returns a list of banks.

---

Partners

Check Lockbox offers an API for our partners, giving them a way to create and manage accounts. If you're interested in becoming a partner or reseller, please contact us at hello@checklockbox.com.

Accounts

The account object

You will need to use the v1 API. See Account.

Retrieve account details

You will need to use the v1 API. See Account.

Create an account

DEFINITION
POST https://api.checklockbox.com/reseller/accounts

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/reseller/accounts \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "account",
  "id": "acct_ksdfj3409DKf93jhdk",
  "business": "bus_klsjdfDKFJsdkf2345",
  "created_at": 1536232308,
  "updated_at": 1536232308
}

Create an account by making a single call to the API.

Arguments

Argument Description
address_city
string		 required
address_line1
string		 required
address_line2
string		 optional
address_state
string		 required
address_zip
string		 required
bank_account_account_number
integer		 required
bank_account_bank
string		 required
The ID of the bank to which this bank account belongs. You can see a list of supported banks here.
bank_account_routing_number
integer		 required
bank_account_verify
boolean		 optional
If set to true, you are acknowledging that the bank account information you provided is correct, you have followed all KYC regulations, and you have the right to share this information on behalf of the account owner.
business_doing_business_as
string		 optional
business_legal_name
string		 required
business_phone_number
string		 required

Returns

Returns an account object or returns an error.

Retrieve account credentials

DEFINITION
POST https://api.checklockbox.com/reseller/accounts/ACCOUNT_ID/credentials

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/reseller/accounts/ACCOUNT_ID/credentials \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "credentials",
  "data": {
    "object": "account",
    "id": "acct_ksdfj3409DKf93jhdk",
    "secret_key": "sk_1234567890"
  }
}

Retrieve the credentials for an existing account.

Arguments

Argument Description
id
string		 required
ID of the account

Returns

Returns a credentials object or returns an error.

Retrieve account status

DEFINITION
POST https://api.checklockbox.com/reseller/accounts/ACCOUNT_ID/status

EXAMPLE REQUEST
$ curl https://api.checklockbox.com/reseller/accounts/ACCOUNT_ID/status \
    -u sk_test_1234567890:

EXAMPLE RESPONSE
{
  "object": "status",
  "code": "incomplete",
  "message": "Missing bank account number",
  "attribute": "bank_account.account_number",
  "data": {
    "object": "account",
    "id": "acct_ksdfj3409DKf93jhdk",
    "business": "bus_klsjdfDKFJsdkf2345",
    "created_at": 1536232308,
    "updated_at": 1536232308
  }
}

To help when creating an account, we provide a status object that will help you determine what information is missing.

Arguments

Argument Description
id
string		 required
ID of the account

Returns

Returns a status object or returns an error.

cURL