# External ID support to simplify transaction tracking

Beta
This feature is in BETA. Please reach out if you would like to use it.

## Why

Wallet-as-a-Service (Palisade) Transfers API makes it easy to specify an intent to move an asset and have the platform translate and securely execute a transaction in order to fulfil that intent. This API reduces errors and risks related to executing raw transactions by abstracting the underlying blockchain transaction away.

However, every call to the Transfers API creates a new intent. There is no way for the platform to differentiate between an existing request and a new request as there is no relatability between the two.

The final product of a Transfer call is a Transaction that is registered on Wallet-as-a-Service (Palisade) and is executed in accordance with controls and execution instructions. While every transaction is uniquely identifiable with a transaction ID, it is up to the caller to map it to their internal ID for tracking purposes.

Similarly, when creating vaults and wallets through their respective APIs, customers need to manually map the system-generated IDs to their internal systems for tracking and reconciliation purposes, creating unnecessary overhead and potential for errors.

## Feature

Today, we are releasing support for `externalId` across Transfers, Vaults and Wallets.

### Transfers

It is an optional field and 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):


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

Note the `externalId` in the response.

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

### Vaults

It is an optional field and 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):


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

Note the `externalId` in the response.

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

### Wallets

It is an optional field and 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):


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

Note the `externalId` in the response.

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

## Properties of `externalId` field

* `externalId` field is optional and nullable. Empty string value is treated as a null value.
* `externalId` field if specified must be minimum of 1 character and a maximum of 64 characters in length.
* `externalId` must be unique org-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.