Idempotency

Our APIs support idempotency for safely retrying requests without accidentally duplicating the result. This can be helpful when your API call fails and you aren't sure if Column received the request. Idempotency enables you to retry a request without worrying it will create a duplicate transaction.

In order to perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request for the endpoint that supports it. The <key> can be any string that uniquely identifies your request. Results of successful requests with Idempotency-Key will be saved and returned on every subsequent request with the same Idempotency-Key.

The Idempotency-Key header is currently supported for creating transfers and certain resources:

POST /bank-accounts
POST /bank-accounts/<bank_account_id>/account-numbers
POST /entities/business
POST /entities/person
POST /loans
POST /loans/disbursements
POST /loans/payment
POST /transfers/ach
POST /transfers/ach/<ach_transfer_id>/reverse
POST /transfers/book
POST /transfers/checks/deposit
POST /transfers/checks/issue
POST /transfers/international-wire
POST /transfers/international-wire/fx-rate
POST /transfers/wire
POST /transfers/wire/<wire_transfer_id>/reverse

Idempotency keys can be up to 255 characters long and are case sensitive. Column reserves the right to expire idempotency keys after 30 days.

Example

curl https://api.column.com/transfers/ach \
  -XPOST \
  -u :<YOUR API KEY> \
  -d counterparty_id=<counterparty_id> \
  -d bank_account_id=<bank_account_id> \
  -d type=CREDIT \
  -d amount=10000 \
  -d currency_code=USD \
  -d description="payment"

The above API call can be a part of various flows in your end-user application, for example in the Web UI to make payouts. If for some reason the call will be repeated, intentionally or not (eg. clicking submit button twice), this can result in creating two transfers and double spending.

Use of Idempotency-Key can help prevent this from happening.

By adding the Idempotency-Key header and setting it to some user generated value that will uniquely identify the API call, subsequent calls with the same Idempotency-Key will not create another transfer and instead return the one created on the first call. Below, we set the same Idempotency-Key in our application logic for a given transfer. We then make two API calls. Only the first API call actually created the transfer. Because the Idempotency-Key is the same in both calls, the second call returned the result of the first and did not create a new transfer.

curl https://api.column.com/transfers/ach
  -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
  -u :<YOUR API KEY>
  -d counterparty_id="cpty_1vX6b45fQ41k62xEXjjIHe5kiRM"
  -d bank_account_id="bacc_1vX9r5qaj6YDm7y4ohOujR0af1Q"
  -d amount=1000
  -d currency_code=USD
  -d description="idempotent payment"
  -d type=CREDIT

{
  "id": "acht_1zBxTIB8yEQdb2LyptJ1PFZIO8k",
  // <...>
}

curl https://api.column.com/transfers/ach
  -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
  -u :<YOUR API KEY>
  -d counterparty_id="cpty_1vX6b45fQ41k62xEXjjIHe5kiRM"
  -d bank_account_id="bacc_1vX9r5qaj6YDm7y4ohOujR0af1Q"
  -d amount=1000
  -d currency_code=USD
  -d description="idempotent payment"
  -d type=CREDIT

{
  "id": "acht_1zBxTIB8yEQdb2LyptJ1PFZIO8k",
  // <...>
}