> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Improving user experience with Spade

***

Spade’s enriched data—including clean names, logos, and merchant contact details—can be used to power user experiences that can provide clarity, increase engagement, and reduce disputes. There are two ways to integrate Spade's data in your UI:

* Build custom display logic using Spade's counterparty, third party and industry names and graphics
* Leverage Spade's recommended display information with the `display` object

# Examples

To illustrate how this works we've provided two examples of transactions with the same counterparty but different third parties and how this can impact the recommended `display.name`.

| Description     | Counterparty | Third Party | Display Name           | Display Logo |
| --------------- | ------------ | ----------- | ---------------------- | ------------ |
| SQ\*SPADE PIZZA | Spade Pizza  | Square      | Spade Pizza            | Spade Pizza  |
| DD\*SPADEPIZZA  | Spade Pizza  | DoorDash    | DoorDash - Spade Pizza | Spade Pizza  |

<CodeGroup>
  ```bash SQ*SPADE PIZZA expandable theme={null}
  {
      "transactionInfo": {
          "display": {
              "name": "Spade Pizza",
              "categoryName": "Restaurant",
              "graphic": "https://static.v2.spadeapi.com/logos/....png",
              "graphicSource": "counterparty"
          },
          "thirdParties": [
              {
                  "id": "ab345...",
                  "name": "Square",
                  "type": "payment_processor",
                  "logo": "https://v1.spadeapi.com/logos/....png"
              }
          ]
      },
      "counterparty": [
          {
              "name": "Spade Pizza",
              "logo": "https://static.v2.spadeapi.com/logos/....png",
              "industry": [
                  {
                      "id": "005-006-000-000",
                      "name": "Restaurants",
                      "icon": "https://static.v2.spadeapi.com/categories/....png"
                  }
              ]
          }
      ]
  }
  ```

  ```bash DD*SPADEPIZZA expandable theme={null}
  {
      "transactionInfo": {
          "display": {
              "name": "DoorDash - Spade Pizza",
              "categoryName": "Restaurant",
              "graphic": "https://static.v2.spadeapi.com/logos/....png",
              "graphicSource": "counterparty"
          },
          "thirdParties": [
              {
                  "id": "ac48cef2...",
                  "name": "DoorDash",
                  "type": "delivery_service",
                  "logo": "https://v1.spadeapi.com/logos/....png"
              }
          ]
      },
      "counterparty": [
          {
              "name": "Spade Pizza",
              "logo": "https://static.v2.spadeapi.com/logos/....png",
              "industry": [
                  {
                      "id": "005-006-000-000",
                      "name": "Restaurants",
                      "icon": "https://static.v2.spadeapi.com/categories/....png"
                  }
              ]
          }
      ]
  }
  ```
</CodeGroup>

In these examples, the user knows they made a purchase from Spade Pizza, but may not recognize the payment processor used at the restaurant’s POS system (e.g., Square). In contrast, a user ordering through DoorDash may be more likely to recognize the delivery service when reviewing their past purchases.

# How to use the display object

Spade has created the `display` object to easily surface the information most recognizable to a user for you to plug into your UI. The `display` object consists of a combination of information from the counterparty and third party sections of the response. Provided below is the `display` object returned from the previous example of a user ordering Spade Pizza via DoorDash.

<CodeGroup>
  ```bash bash theme={null}
  {
    "display": {
      "name": "DoorDash - Spade Pizza",
      "categoryName": "Restaurants",
      "graphic": "https://static.v2.spadeapi.com/logos/...png",
      "graphicSource": "counterparty"
    }
  }
  ```
</CodeGroup>

The `display` object can be found in the `transactionInfo` of both card and transfer enrichments.

* **`name`** - The recommended display name
* **`categoryName`** - The best description of the category, usually this is the counterparty industry, but it may also reflect some third parties, MCC, etc.
* **`graphic`** - The recommended logo or icon to display
* **`graphicSource`** - Indicates whether the graphic was sourced from either a`counterparty`, `third_party`, or `category`. This is helpful if for example you use your own category iconography

<Info>
  For more information on displaying logos and icons, see [Spade graphics](/reference/spade-graphics).
</Info>

# Additional display details

## Location data

When Spade matches the transaction to a location we will provide both address details as well as latitude and longitude information which allows you to display a detailed map of where the transaction took place.

<Note>
  Note: We recommend only displaying location data when `spendingChannel `= physical to avoid confusion for online purchases that will show corporate locations that end users may not be familiar with.
</Note>

### Displaying addresses

Spade will return the full street address in `location.address`. The street address will be parsed and will always return a value in `addressLine1` but will only return a value in `addressLine2` if the address has multiple lines.

In the first example below the address should be shown as:

> 1234 W 5th Ave Suite 100 New York, NY 10001

<CodeGroup>
  ```bash Address theme={null}
  {
      "location": [
          {
              "id": "fdf79470-3deb-4638-956a-6859e473b9d8",
              "address": "1234 W 5th Ave Suite 100",
              "addressLine1": "1234 W 5th Ave",
              "addressLine2": "Suite 100",
              "city": "New York",
              "region": "NY",
              "country": "USA",
              "postalCode": "10001",
              "latitude": 45,
              "longitude": 120,
              "phoneNumber": "+18664862360",
              "matchScore": 93.5
          }
      ]
  }
  ```
</CodeGroup>

For addresses with a single line you would simply use the `address` field:

> 1234 W 5th Ave New York, NY 10001

<CodeGroup>
  ```bash Address theme={null}
  {
      "location": [
          {
              "id": "fdf79470-3deb-4638-956a-6859e473b9d8",
              "address": "1234 W 5th Ave",
              "addressLine1": "1234 W 5th Ave",
              "addressLine2": null,
              "city": "New York",
              "region": "NY",
              "country": "USA",
              "postalCode": "10001",
              "latitude": 45,
              "longitude": 120,
              "phoneNumber": "+18664862360",
              "matchScore": 93.5
          }
      ]
  }
  ```
</CodeGroup>

### Displaying geolocation

By showing a transaction’s location on a map, users can more easily confirm purchases and identify potentially fraudulent activity. When available we will provide the`location.latitude` and `location.longitude` for you to use to generate a map in your UI.

## Phone numbers

We recommend using the `counterparty.phoneNumber` when it is present and falling back to `counterparty.location.phoneNumber` . When the counterparty is a corporation, such as WalMart, the counterparty phone number represents the corporate phone number and the location phone number is the phone number for the specific store location.

## Original description

In addition to the enriched transaction description, we recommend displaying a field with the original descriptor (e.g., APPEARS ON STATEMENT: SBX1234) to ensure parity with statements.