# 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 /interests/configs`
- `POST /interests/pivot-rates`
- `POST /loans`
- `POST /loans/disbursements`
- `POST /loans/payments`
- `POST /loans/<loan_id>/sales`
- `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`

### Valid Characters Permitted

Idempotency keys can be up to 255 characters long and are case sensitive. Column reserves the right to expire idempotency keys after 30 days. Only ASCII printable characters (code `32` - `126`) are allowed for idempotency keys.

- A-Z, a-z, 0-9 and spaces (alphanumeric)
- ! (exclamation mark)
- " (double quote)
- \# (hash)
- $ (dollar sign)
- % (percent)
- & (ampersand)
- ' (single quote)
- ( (left parenthesis)
- ) (right parenthesis)
- \* (asterisk)
- \+ (plus)
- , (comma)
- \- (hyphen)
- . (period)
- / (forward slash)
- : (colon)
- ; (semicolon)
- `<` (less than)
- \= (equals)
- `>` (greater than)
- ? (question mark)
- @ (at sign)
- \[ (left bracket)
- `\` (backslash)
- ] (right bracket)
- ^ (caret)
- \_ (underscore)
- \` (backtick)
- `{` (left brace)
- `|` (vertical bar)
- `}` (right brace)
- \~ (tilde)

### Example

```shell
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 amount=10000 \
  -d currency_code=USD \
  -d description="payment" \
  -d type=CREDIT \
  -d entry_class_code="CCD"
```

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 the call is repeated, intentionally or not (e.g. clicking the 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.

```shell
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 \
  -d entry_class_code="CCD"

{
  "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 \
  -d entry_class_code="CCD"

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