Testing

Checkbook maintains three API environments using the following subdomains:

  • Test: (https://test.checkbook.io/)
    • Test Checkbook's API using a public set of API keys (no account required).
    • All debits and credits use fake money.
  • Sandbox: (https://sandbox.checkbook.io/)
    • Test Checkbook's API using your existing Checkbook account.
    • All debits and credits use fake money.
  • Live: (https://checkbook.io/ )
    • Make actual API transactions using your existing Checkbook account..
    • Debit or credit will be applied to your linked bank account.

Authentication

All endpoints must be signed with a private API key. We use the standard HTTP Authorization header to pass authentication information. Under the authentication scheme, the Authorization header has the following form:

Authorization: Key:Secret

You are issued an API key and an API secret immediately upon registration. These can be found on your developer settings page at: https://checkbook.io/account/settings/developer

Note

Technically speaking, the header name Authorization is not quite accurate: in our implementation it carries authentication information, not authorization.


API Endpoints

Checkbook's API accepts five endpoints:


Check

Resource Operation Description
DELETE check DELETE /v3/check/(check_id) Void the specified check.
GET check GET /v3/check/(check_id) Get the specified check.
GET checks GET /v3/check Get sent/received checks.
POST digital check POST /v3/check/digital Create a digital check.
POST physical check POST /v3/check/physical Create a physical check.
GET /v3/check

Return the sent/received checks for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/check

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'checks': [
     {'id': '65432178123456781234567812345678',
      'date': '2014-01-02 13:14:15',
      'number': '1002',
      'description': 'January rent',
      'status': 'IN_PROCESS',
      'amount': 535.00,
      'name': 'Widgets Inc.',
      'recipient': 'rent@example.com'
     },
     {'id': '12345678123456781234567812345678',
      'date': '2014-01-01 12:15:15',
      'number': '1001',
      'description': 'Cleaning services payment',
      'status': 'PAID',
      'amount': 35.45,
      'name': 'James Smith',
      'recipient': 'cleaning@example.com'
     }]
 }
Request Headers:
 
Response JSON Object:
 
  • checks (list[object]) – list of sent/received checks
  • id (string) – unique identifier for the check
  • date (string) – check creation timestamp
  • number (string) – check number
  • description (string) – check description
  • amount (number) – amount
  • name (string) – name of third party who sent/received the check
  • recipient (string|object) – email/id or physical address of the check recipient
  • status (string) – current status of the check: PAID, IN_PROCESS, UNPAID, VOID, EXPIRED, PRINTED, MAILED, FAILED, RETURNED
Status Codes:
DELETE /v3/check/(check_id)

Void the specified check for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" -X DELETE https://test.checkbook.io/v3/check/d39173de6abc40e3836f0b2c4999c514

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Query Parameters:
 
  • check_id – id of the check to void
Status Codes:
GET /v3/check/(check_id)

Get the specified check for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/check/6af5cabf03ea44ab9792bddeb8929381

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{'id': '65432178123456781234567812345678',
 'date': '2014-01-02 13:14:15',
 'number': '1002',
 'description': 'January rent',
 'status': 'IN_PROCESS',
 'amount': 535.00,
 'name': 'Widgets Inc.',
 'recipient': 'rent@example.com'
}
Request Headers:
 
Query Parameters:
 
  • check_id – id of the check to return
Response JSON Object:
 
  • id (string) – unique identifier for the check
  • date (string) – check creation timestamp
  • number (string) – check number
  • description (string) – check description
  • amount (number) – amount
  • name (string) – name of third party who sent/received the check
  • recipient (string|object) – email/id or physical address of the check recipient
  • status (string) – current status of the check: PAID, IN_PROCESS, UNPAID, VOID, EXPIRED, PRINTED, MAILED, FAILED, RETURNED
Status Codes:
POST /v3/check/digital

Create a new digital check

Example request:

curl -H "Content-Type: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" -X POST -d '{"name":"Widgets Inc.","recipient":"widgets@example.com", "amount": 5.00}' https://test.checkbook.io/v3/check/digital

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

{'id': '65432178123456781234567812345678',
 'date': '2014-01-02 13:14:15',
 'number': '1002',
 'description': 'January rent',
 'status': 'IN_PROCESS',
 'amount': 535.00,
 'name': 'Widgets Inc.',
 'recipient': 'rent@example.com'
}
Request Headers:
 
Request JSON Object:
 
  • recipient (string) – email/id of recipient
  • name (string) – name of recipient
  • amount (number) – check amount
  • [description] (string) – optional description/memo for check
  • [account] (string) – optional debit account id for funds (if sender has multiple bank accounts)
  • [attachment] (string) – optional base64 encoded PDF attachment for recipient
Response JSON Object:
 
  • id (string) – unique identifier for the check
  • date (string) – check creation timestamp
  • number (string) – check number
  • description (string) – check description
  • amount (number) – amount
  • name (string) – name of check recipient
  • recipient (string) – email/id of the check recipient
  • status (string) – current status of the check: PAID, IN_PROCESS, UNPAID, VOID, EXPIRED, PRINTED, MAILED, FAILED, RETURNED
Status Codes:
POST /v3/check/physical

Create a new physical check

Example request:

curl -H "Content-Type: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" -X POST -d '{"name":"Widgets Inc.","recipient":{"line_1": "1234 N. 1st Street","line_2": "#56","city": "San Francisco","state": "CA","zip": "12345"}, "amount": 5.00}' https://test.checkbook.io/v3/check/physical

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

{'id': '65432178123456781234567812345678',
 'date': '2014-01-02 13:14:15',
 'number': '1002',
 'description': 'January rent',
 'status': 'MAILED',
 'amount': 535.00,
 'name': 'Widgets Inc.',
 'recipient': {'line_1': '1234 N. 1st Street',
               'line_2': '#56',
               'city': 'San Francisco',
               'state': 'CA',
               'zip': '78901'}
}
Request Headers:
 
Request JSON Object:
 
  • recipient (object) – address of the recipient
  • name (string) – name of recipient
  • amount (number) – check amount
  • [description] (string) – optional description/memo for check
  • [account] (string) – optional debit account id for funds (if sender has multiple bank accounts)
Response JSON Object:
 
  • id (string) – unique identifier for the check
  • date (string) – check creation timestamp
  • number (string) – check number
  • description (string) – check description
  • amount (number) – amount
  • name (string) – name of check recipient
  • recipient (object) – physical address of the check recipient
  • status (string) – current status of the check: PAID, IN_PROCESS, UNPAID, VOID, EXPIRED, PRINTED, MAILED, FAILED, RETURNED
Status Codes:

Invoice

Resource Operation Description
DELETE invoice DELETE /v3/invoice/(invoice_id) Cancel the specified invoice.
GET invoice GET /v3/invoice/(invoice_id) Get the specified invoice.
GET invoices GET /v3/invoice Get sent/received invoices.
POST invoice POST /v3/invoice Create invoice.
GET /v3/invoice

Return the sent/received invoices for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/check

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'invoices': [
     {'id': '65432178123456781234567812345678',
      'date': '2014-01-02 13:14:15',
      'number': '1002',
      'description': 'January rent',
      'status': 'PAID',
      'amount': 535.00,
      'name': 'Widgets Inc.',
      'recipient': 'rent@example.com'
     },
     {'id': '12345678123456781234567812345678',
      'date': '2014-01-01 12:15:15',
      'number': '1001',
      'description': 'Cleaning services payment',
      'status': 'UNPAID',
      'amount': 35.45,
      'name': 'James Smith',
      'recipient': 'cleaning@example.com'
     }]
 }
Request Headers:
 
Response JSON Object:
 
  • invoices (list[object]) – list of sent/received invoices
  • id (string) – unique identifier for invoice
  • date (string) – invoice creation timestamp
  • number (string) – invoice number
  • description (string) – invoice description
  • amount (number) – amount
  • name (string) – name of third party who sent/received the invoice
  • recipient (string) – email/id of the invoice recipient
  • status (string) – current status of the invoice: PAID, IN_PROCESS, UNPAID, CANCELED, OVERDUE
Status Codes:
POST /v3/invoice

Create a new invoice

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/invoice

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

{'id': '65432178123456781234567812345678',
 'date': '2014-01-02 13:14:15',
 'number': '1002',
 'description': 'January rent',
 'status': 'UNPAID',
 'amount': 535.00,
 'name': 'Widgets Inc.',
 'recipient': 'rent@example.com'
}
Request Headers:
 
Request JSON Object:
 
  • recipient (string) – email/id of recipient
  • name (string) – name of recipient
  • amount (number) – invoice amount
  • description (string) – description/memo for invoice
  • [account] (string) – optional credit account id for funds (if sender has multiple bank accounts)
  • [attachment] (string) – optional base64 encoded PDF attachment for recipient
Response JSON Object:
 
  • id (string) – unique identifier for invoice
  • date (string) – invoice creation timestamp
  • number (string) – invoice number
  • description (string) – invoice description
  • amount (number) – amount
  • name (string) – name of invoice recipient
  • recipient (string) – email/id of the invoice recipient
  • status (string) – current status of the invoice: PAID, IN_PROCESS, UNPAID, CANCELED, OVERDUE
Status Codes:
DELETE /v3/invoice/(invoice_id)

Cancel the specified invoice for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/invoice

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Query Parameters:
 
  • invoice – id of the invoice to cancel
Status Codes:
GET /v3/invoice/(invoice_id)

Get the specified invoice for a user

Example request:

curl -i -H "Accept: application/json" -H "Authorization: d6aa2703655f4ba2af2a56202961ca86:dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8" https://test.checkbook.io/v3/invoice

Example response:

HTTP/1.1 200 OK
Content-Type: application/json


 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'number': '1002',
  'description': 'January rent',
  'status': 'PAID',
  'amount': 535.00,
  'name': 'Widgets Inc.',
  'recipient': 'rent@example.com'
 }
Request Headers:
 
Query Parameters:
 
  • invoice_id – id of the invoice to return
Response JSON Object:
 
  • id (string) – unique identifier for invoice
  • date (string) – invoice creation timestamp
  • number (string) – invoice number
  • description (string) – invoice description
  • amount (number) – amount
  • name (string) – name of third party who sent/received the invoice
  • recipient (string) – email/id of the invoice recipient
  • status (string) – current status of the invoice: PAID, IN_PROCESS, UNPAID, CANCELED, OVERDUE
Status Codes:

Subscription

Resource Operation Description
DELETE subscription DELETE /v3/subscription/(subscription_id) Remove specified subscription.
GET subscription GET /v3/subscription/(subscription_id) Get specified subscription.
GET subscriptions GET /v3/subscription Get subscriptions.
POST check subscription POST /v3/subscription/check Create check subscription.
POST invoice subscription POST /v3/subscription/invoice Create invoice subscription.
PUT subscription PUT /v3/subscription/(subscription_id) Update subscription.
GET /v3/subscription

Return the subscriptions for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'subscriptions': [
     {'id': '65432178123456781234567812345678',
      'date': '2014-01-02 13:14:15',
      'start_date': '2014-01-02',
      'type': 'CHECK',
      'interval': 'MONTHLY',
      'amount': 535.00,
      'description': 'Monthly Rent',
      'name': 'Landlord Inc.'
      'recipient': 'rent@example.com',
      'duration': 5,
      'skipped': [],
      'account': '11132178123456781234567812345678'
     },
     {'id': '12345678123456781234567812345678',
      'date': '2014-01-01 12:15:15',
      'start_date': '2014-01-02','
      'type': 'CHECK',
      'interval': 'WEEKLY',
      'amount': 535.00,
      'description': 'Cleaning services',
      'name': 'Cleaning Services LLC'
      'recipient': 'cleaning@example.com',
      'duration': null,
      'skipped': [4, 7],
      'account': '11132178123456781234567812345678'
     }]
 }
Request Headers:
 
Response JSON Object:
 
  • subscriptions (list[object]) – list of subscriptions
  • id (string) – unique identifier for subscription
  • date (string) – subscription creation timestamp
  • start_date (string) – subscription start date
  • type (string) – type of the subscription: CHECK, INVOICE
  • interval (string) – how often the subscription will recur: WEEKLY, MONTHLY
  • description (string) – subscription description
  • amount (number) – amount
  • name (string) – name of third party who is receiving the check/invoice
  • recipient (string) – email/id of the check/invoice recipient
  • account (string) – debit/credit account id for funds
  • duration (number) – number of times the subscription will recur (null indicates indefinite)
  • skipped (list) – list of skipped subscription indexes (e.g. [1] indicates the first subscription will be skipped)

Note

Even though a subscription is skipped, it will still still count towards the duration limit. For example, if the duration is 5, and the first subscription is skipped, only 4 subscriptions will be sent.

Status Codes:
DELETE /v3/subscription/(subscription_id)

Remove the specified subscription for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Query Parameters:
 
  • subscription_id – id of the subscription to void
Status Codes:
GET /v3/subscription/(subscription_id)

Get the specified subscription for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'start_date': '2014-01-02',
  'type': 'CHECK',
  'interval': 'MONTHLY',
  'amount': 535.00,
  'description': 'Monthly Rent',
  'name': 'Landlord Inc.'
  'recipient': 'rent@example.com',
  'duration': 5,
  'skipped': [],
  'account': '11132178123456781234567812345678'
 }
Request Headers:
 
Response JSON Object:
 
  • id (string) – unique identifier for subscription
  • date (string) – subscription creation timestamp
  • start_date (string) – subscription start date
  • type (string) – type of the subscription: CHECK, INVOICE
  • interval (string) – how often the subscription will recur: WEEKLY, MONTHLY
  • description (string) – subscription description
  • amount (number) – amount
  • name (string) – name of third party who is receiving the check/invoice
  • recipient (string) – email/id of the check/invoice recipient
  • account (string) – debit/credit account id for funds
  • duration (number) – number of times the subscription will recur (null indicates indefinite)
  • skipped (list) – list of skipped subscription indexes (e.g. [1] indicates the first subscription will be skipped)

Note

Even though a subscription is skipped, it will still still count towards the duration limit. For example, if the duration is 5, and the first subscription is skipped, only 4 subscriptions will be sent.

Status Codes:
PUT /v3/subscription/(subscription_id)

Update the specified subscription for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Request JSON Object:
 
  • skipped (list[number]) – list of skipped subscription indexes (e.g. [1] indicates the first subscription will be skipped)

Note

Even though a subscription is skipped, it will still still count towards the duration limit. For example, if the duration is 5, and the first subscription is skipped, only 4 subscriptions will be sent.

Status Codes:
POST /v3/subscription/check

Create a new check subscription

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'start_date': '2014-01-02',
  'type': 'CHECK',
  'interval': 'MONTHLY',
  'amount': 535.00,
  'description': 'Monthly Rent',
  'name': 'Landlord Inc.'
  'recipient': 'rent@example.com',
  'duration': 5,
  'skipped': [],
  'account': '11132178123456781234567812345678'
 }
Request Headers:
 
Request JSON Object:
 
  • recipient (string) – email/id of recipient
  • name (string) – name of recipient
  • amount (number) – check amount
  • interval (number) – how often the subscription will recur: WEEKLY, MONTHLY
  • [start_date] (string) – yyyy-mm-dd formatted start date for subscription (this is the first date the subscription will be sent out and defaults to the current timestamp)
  • [description] (string) – optional description/memo for check
  • [duration] (number) – optional number of times the subscription should recur (defaults to indefinite)
  • [account] (string) – optional debit account id for funds (if sender has multiple bank accounts)
Response JSON Object:
 
  • id (string) – unique identifier for subscription
  • date (string) – subscription creation timestamp
  • start_date (string) – subscription start date
  • type (string) – type of the subscription: CHECK
  • interval (string) – how often the subscription will recur: WEEKLY, MONTHLY
  • description (string) – subscription description
  • amount (number) – amount
  • name (string) – name of third party who is receiving the check/invoice
  • recipient (string) – email/id of the check/invoice recipient
  • account (string) – debit/credit account id for funds
  • duration (number) – number of times the subscription will recur (null indicates indefinite)
  • skipped (list) – list of skipped subscription indexes (e.g. [1] indicates the first subscription will be skipped)

Note

Even though a subscription is skipped, it will still still count towards the duration limit. For example, if the duration is 5, and the first subscription is skipped, only 4 subscriptions will be sent.

Status Codes:
POST /v3/subscription/invoice

Create a new invoice subscription

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'start_date': '2014-01-02',
  'type': 'INVOICE',
  'interval': 'MONTHLY',
  'amount': 535.00,
  'description': 'Monthly Rent',
  'name': 'Jason Smith'
  'recipient': 'jsmith@example.com',
  'duration': null,
  'skipped': [],
  'account': '11132178123456781234567812345678'
 }
Request Headers:
 
Request JSON Object:
 
  • recipient (string) – email/id of recipient
  • name (string) – name of recipient
  • amount (number) – invoice amount
  • description (string) – description for the invoice
  • interval (number) – how often the subscription will recur: WEEKLY, MONTHLY
  • [start_date] (string) – yyy-mm-dd formatted start date for subscription (this is the first date the subscription will be sent out and defaults to the current timestamp)
  • [duration] (number) – optional number of times the subscription should recur (defaults to indefinite)
  • [account] (string) – optional debit account id for funds (if sender has multiple bank accounts)
Response JSON Object:
 
  • id (string) – unique identifier for subscription
  • date (string) – subscription creation timestamp
  • start_date (string) – subscription start date
  • type (string) – type of the subscription: INVOICE
  • interval (string) – how often the subscription will recur: WEEKLY, MONTHLY
  • description (string) – subscription description
  • amount (number) – amount
  • name (string) – name of third party who is receiving the check/invoice
  • recipient (string) – email/id of the check/invoice recipient
  • account (string) – debit/credit account id for funds
  • duration (number) – number of times the subscription will recur (null indicates indefinite)
  • skipped (list) – list of skipped subscription indexes (e.g. [1] indicates the first subscription will be skipped)

Note

Even though a subscription is skipped, it will still still count towards the duration limit. For example, if the duration is 5, and the first subscription is skipped, only 4 subscriptions will be sent.

Status Codes:

User

Resource Operation Description
POST user POST /v3/user Create user.
PUT user PUT /v3/user Update user.
POST /v3/user

Create a new user

Example response:

HTTP/1.1 201 OK
Content-Type: application/json

{'user_id': 'jsmith@example.com',
 'key': 'd6aa2703655f4ba2af2a56202961ca86',
 'secret': 'dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8'
}
Request Headers:
 
Request JSON Object:
 
  • user_id (string) – unique identifier for new user
  • name (string) – name of user
Response JSON Object:
 
  • user_id (string) – unique identifier for user
  • key (string) – API key for new user
  • secret (string) – API secret for new user
Status Codes:
PUT /v3/user

Update an existing user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Request JSON Object:
 
  • [user] (object) – embedded user attributes to be updated: first_name, last_name, phone, business_name, check_number, invoice_number, dob, ssn
  • [merchant] (object) – embedded merchant attributes to be updated: website, address_line_1, address_line_2, city, state, zip, tax_id
  • [bank] (object) – bank attributes to be updated: default, billing
Status Codes:

Bank

Resource Operation Description
DELETE bank DELETE /v3/bank/(bank_id) Remove the specified bank.
GET banks GET /v3/bank Get banks.
GET institutions GET /v3/bank/institutions Get institutions.
POST bank POST /v3/bank Add bank account.
  POST /v3/bank/iav  
POST bank verify POST /v3/bank/verify Verify microdeposits.
POST /v3/bank

Add a new bank account for user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'routing': '021000021',
  'account': '0000',
  'status': 'VERIFIED',
  'billing': true,
  'default': true,
 }
Request Headers:
 
Request JSON Object:
 
  • routing (string) – routing number
  • account (string) – account number
  • type (string) – CHECKING, BUSINESS
Response JSON Object:
 
  • id (string) – unique identifier for account
  • date (string) – account creation timestamp
  • routing (string) – routing number
  • account (string) – last 4 digits of account number
  • status (string) – current status of account: PENDING, VERIFIED
  • billing (boolean) – indicates the billing account for the user
  • default (boolean) – indicates the default debit/credit account for the user
Status Codes:
GET /v3/bank

Return the bank accounts for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'banks': [
     {'id': '65432178123456781234567812345678',
      'date': '2014-01-02 13:14:15',
      'routing': '021000021',
      'account': '0000',
      'status': 'VERIFIED',
      'billing': true,
      'default': true,
     },
     {'id': '12345678123456781234567812345678',
      'date': '2014-01-02 13:14:15',
      'routing': '021000021',
      'account': '1111',
      'status': 'PENDING',
      'billing': false,
      'default': false,
     }]
 }
Request Headers:
 
Response JSON Object:
 
  • banks (list[object]) – list of bank accounts for user
  • id (string) – unique identifier for bank account
  • date (string) – bank account creation timestamp
  • routing (string) – routing number
  • account (string) – last 4 digits of bank account number
  • status (string) – current status of bank account: PENDING, VERIFIED
  • billing (boolean) – indicates the billing account for the user
  • default (boolean) – indicates the default debit/credit account for the user
Status Codes:
DELETE /v3/bank/(bank_id)

Remove the specified bank account for a user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Query Parameters:
 
  • bank – id of the bank account to remove
Status Codes:
POST /v3/bank/iav

Add a new bank account for user

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'id': '65432178123456781234567812345678',
  'date': '2014-01-02 13:14:15',
  'routing': '021000021',
  'account': '0000',
  'status': 'VERIFIED',
  'billing': true,
  'default': true,
 }
Request Headers:
 
Request JSON Object:
 
  • institution_id (string) – institution_id returned from the institutions endpoint
  • account (string) – account number
  • type (string) – CHECKING, BUSINESS
Response JSON Object:
 
  • id (string) – unique identifier for bank account
  • date (string) – bank account creation timestamp
  • routing (string) – routing number
  • account (string) – last 4 digits of bank account number
  • status (string) – current status of bank account: PENDING, VERIFIED
  • billing (boolean) – indicates the billing account for the user
  • default (boolean) – indicates the default debit/credit account for the user
Status Codes:
GET /v3/bank/institutions

Get a list of our supported institutions for IAV (Instant Account Verification)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

 {'institutions': [
     {'id': '65432178123456781234567812345678',
      'name': 'Bank of America',
      'login_form': [
         {'description': 'Username',
          'name': 'username',
          'type': 'TEXT',
         },
         {'description': 'Password',
          'name': 'password',
          'type': 'PASSWORD'}]
     },
     {'id': '12345678123456781234567812345678',
      'name': 'Wells Fargo',
      'login_form': [
         {'description': 'User ID',
          'name': 'user',
          'type': 'text',
         },
         {'description': 'Password',
          'name': 'TEXT',
          'type': 'PASSWORD'}]
     }]
 }
Request Headers:
 
Response JSON Object:
 
  • institutions (list[object]) – list of supported institutions for IAV
  • id (string) – unique identifier for institution
  • name (string) – name of institution
  • login_form (list[object]) – login form for institution, including a description of the field, the name of the field and the field type: TEXT, PASSWORD
Status Codes:
POST /v3/bank/verify

Verify the microdeposits for a bank account

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Request Headers:
 
Request JSON Object:
 
  • amount_1 (number) – amount of first micro deposit
  • amount_2 (number) – amount of second micro deposit

Note

The ordering of amount_1 and amount_2 does not matter

Status Codes:

Error Codes

The Checkbook API uses the following error codes:

  • 400 Bad Request – Your request is invalid
  • 401 Unauthorized – Your API key is wrong
  • 403 Forbidden – You do not have permission to access the requested endpoint
  • 404 Not Found – The specified endpoint could not be found
  • 405 Method Not Allowed – You tried to access an endpoint with an invalid method
  • 429 Too Many Requests – You’re sending too many requests! Slow down!
  • 500 Internal Server Error – We had a problem with our server. Try again later.
  • 503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

OAuth

If you wish to send requests on behalf of another user, this user will use OAuth in order to generate a key that may be used on their behalf. More information on OAuth can be found at:

https://oauth.net/2/

To start this authentication process, your user will access our OAuth authorization endpoint, which can be found at:

https://checkbook.io/oauth/authorize

This url requires 4 query parameters which are:

client_id: CLIENT_ID
response_type: code
scope: check
redirect_uri: REDIRECT_URI

You will need to replace CLIENT_ID with your client id and REDIRECT_URI with your callback url, which can be found/updated at:

https://checkbook.io/account/api_keys

Once the user confirms they wish to allow a third party to send checks on their behalf, their browser will be redirect to the callback URI that has been specified, along with an AUTHORIZATION_CODE:

http://REDIRECT_URI?code=AUTHORIZATION_CODE

The AUTHORIZATION_CODE can exchanged for bearer tokens using the token endpoint:

https://checkbook.io/oauth/token

This url accepts a POST request with the parameters:

client_id: CLIENT_ID
grant_type: authorization_code
scope: check
code: AUTHORIZATION_CODE
redirect_uri: REDIRECT_URI
client_secret: SECRET_KEY

You will need to replace CLIENT_ID with your client id, REDIRECT_URI with your callback uri, SECRET_KEY with your secret key found at https://checkbook.io/account/api_keys and CODE with the access_token returned in the previous step. A successful request will return an access_token along with some other information:

{"access_token": BEARER_TOKEN,
 "token_type": "Bearer",
 "refresh_token": REFRESH_TOKEN,
 "scope": "check"}

The BEARER_TOKEN is then sent to api requests in place of the secret key: Authorization: bearer BEARER_TOKEN


Idempotency

When sending data across the Internet, there are many times when unexpected issues occur. For example, a check could get created in our system, but the API confirmation response may never get back to the originator due to a network outage.

Our API supports idempotency, so you can safely retry your requests without having to worry about a duplicate operation. User, bank account, check and invoice creation all support the ‘Idempotency-Key’ header as part of the POST request. This should be a unique key (it can be a counter, timestamp, UUID, etc) no longer than 255 characters that will not be re-used with that particular POST endpoint.

If you make the same request with the same idempotent key, no new resource will be created on our end, but you will receive the same response as the first time. However, if you reuse an idempotent key with different parameters, the idempotent key will be ignored.

For example, assume you make three API calls and pass the same Idempotency-Key header each time:

Idempotency-Key: 1
  1. You call the API to create a new user with the email address foo@example.com.
    • Result: A new user is created and you will receive a response containing the keys for the new user.
  2. You repeat the same request to create a user with the email address foo@example.com).
    • Result: The API recognizes the Idempotency-Key and passes the same API keys as in the first call. No new user is created.
  3. You call the API to create a new user with a different email address bar@example.com.
    • Result: The API ignores the Idempotency-Key because the call was not identical. A new user is created and a new set of API keys is returned.

Webhooks

If you would like to receive notifications when the status of a check has been updated, you can specify a webhook url in your developer profile: https://checkbook.io/account/settings/developer When the status of a check is updated, you will receive a POST request to the specified url containing the id of the check that has been updated and its new status:

{‘id’: <check id>, ‘status’: <check status>}