# External IDs

When creating vaults, wallets and transfers via the API, customers may create and assign an `externalId` to the request. The benefit of assigning a unique identifier to an API request is that it ensures the request is idempotent. An idempotent call or operation is one that produces the same result even if repeated many times.

In practice, this means that if a customer accidentally submits a Create Vault/Wallet/Transfer API request containing a particular `externalID` multiple times, Wallet-as-a-Service (Palisade) will recognise that the duplicate requests contain the same `externalID` and only process the first one.

Therefore, using an `externalID` provides protection against human error and unintended consequences. If an `externalID` is not used, there is no way for Wallet-as-a-Service (Palisade) to differentiate between deliberate and accidental requests and all the requests will be executed.

### Example - Vaults

`ExternalID` may be used in the Create Vault request body as follows (see the [Wallet-as-a-Service (Palisade) API](/products/wallet/api-docs/palisade-api/palisade-api) for details):


```json
{
    "name": "Treasury",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}
```

This will result in a response similar to the following (containing the same `externalId` field):


```
{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "name": "Treasury",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...
```

Subsequent calls to the Create Vault API using the same `externalId` value will return the same Vault object.

### Example - Wallets

`ExternalID` may be used in the Create Wallet request body as follows (see the [Wallet-as-a-Service (Palisade) API](/products/wallet/api-docs/palisade-api/palisade-api) for details):


```json
{
    "name": "USD Issuance",
 		"blockchain": "AVALANCHE",
  	"keystore": "HSM",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}
```

This will result in a response similar to the following (containing the same `externalId` field):


```
{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "name": "USD Issuance",
 		"blockchain": "AVALANCHE",
  	"keystore": "HSM",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...
```

Subsequent calls to the Create Wallet API using the same `externalId` value will return the same Wallet object.

### Example - Transactions

`ExternalID` may be used in the Create Transfer request body as follows (see the [Wallet-as-a-Service (Palisade) API](/products/wallet/api-docs/palisade-api/palisade-api) for details):


```json
{
    "destinationAddress": "rMhieePimPBNQZByxQxX1HXY6VyxEep2JE",
    "qty": "0.000003",
    "symbol": "XRP",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}
```

This will result in a response similar to the following (containing the same `externalId` field):


```
{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "status": "REQUESTED",
    "action": "PALISADE_TRANSFER",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...
```

Subsequent calls to the Create Transfer API using the same `externalId` value will return the same Transaction object.

## Properties of `externalId` field

* It is optional and nullable. Empty string value is treated as a null value.
* It must be a minimum of 1 character and a maximum of 64 characters in length.
* It must be unique and organization wide. This means that two wallets cannot have transactions containing the same `externalId`.
* The API will create a new object for every request that has `externalId` set to null.