Saved Contacts

Saved Contacts store reusable destination or source instructions for transfers and Auto Convert Routes. Create them from the field metadata returned for the selected route instead of hardcoding fields per currency.

For fiat accounts, owner type and required fields can vary by currency and payment rail. Always render the form from route metadata.

Create or update a saved contact

POST /saved-contacts/v1 UpsertSavedContactCommandV1

Crypto wallet example

{
  "isSavedByUser": true,
  "alias": "Treasury USDC wallet",
  "instruction": {
    "kind": "External",
    "currency": "Usdc",
    "paymentRail": "Base",
    "primaryIdentifier": "0x123456789abcdef0123456789abcdef01234567"
  }
}

SEPA individual account example

{
  "isSavedByUser": true,
  "alias": "Alex EUR account",
  "instruction": {
    "kind": "External",
    "currency": "Eur",
    "paymentRail": "Sepa",
    "primaryIdentifier": "ES79 2100 0813 6101 2345 6789",
    "accountOwnerType": "Individual",
    "accountOwnerFirstName": "Alex",
    "accountOwnerLastName": "Rivera"
  }
}

SEPA business account example

{
  "isSavedByUser": true,
  "alias": "Example Ltd EUR account",
  "instruction": {
    "kind": "External",
    "currency": "Eur",
    "paymentRail": "Sepa",
    "primaryIdentifier": "ES79 2100 0813 6101 2345 6789",
    "accountOwnerType": "Business",
    "accountOwnerBusinessName": "Example Ltd"
  }
}

Expected result:

{
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "isSavedByUser": true,
    "alias": "Treasury USDC wallet",
    "createdAt": "2026-06-11T10:00:00Z",
    "updatedAt": "2026-06-11T10:00:00Z",
    "lastUsedAt": null,
    "instruction": {
      "kind": "External",
      "currency": "Usdc",
      "paymentRail": "Base",
      "primaryIdentifier": "0x123456789abcdef0123456789abcdef01234567"
    }
  }
}

List saved contacts

QUERY /saved-contacts/v1 GetSavedContactListQueryV1

curl https://api-preview.kunga.eu/saved-contacts/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "currency": "Usdc",
    "paymentRail": "Base",
    "isSavedByUser": true
  }'

Expected result:

{
  "contacts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isSavedByUser": true,
      "alias": "Treasury USDC wallet",
      "createdAt": "2026-06-11T10:00:00Z",
      "updatedAt": "2026-06-11T10:00:00Z",
      "lastUsedAt": null,
      "instruction": {
        "kind": "External",
        "currency": "Usdc",
        "paymentRail": "Base",
        "primaryIdentifier": "0x123456789abcdef0123456789abcdef01234567"
      }
    }
  ]
}

Field handling

Use metadata labels and field types for user-facing forms.
Keep IBAN, CLABE, wallet address, routing number, and account number fields distinct.
Treat BIC/SWIFT and reference fields according to the returned required flag.
Do not display internal provider ids or routing metadata to the user.

Common validation failures

Failure	Handling
Invalid IBAN, CLABE, routing number, or wallet address	Keep the form open and highlight the specific field.
Missing owner fields	Re-render the owner fields from metadata and require the missing values.
Unsupported route	Refresh transfer route discovery and rebuild the contact form from the selected route.
Duplicate contact data	Prefer updating alias/user settings on the existing contact instead of creating another visible duplicate.