> ## 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.

# Attribution agent guide

## **Overview**

Spade's attribution agent helps you accurately attribute transactions on a merchant and location level. It will attribution rates, reduce customer complaints due to missed rewards, and reduce the complexity of managing internal merchant matching tools.

## Providing merchant details

To attribute transactions to specific merchants, you will need to provide a list of merchants and a unique unique identifier for each that will be returned with attributed transactions.

Below we've outlined the fields we require:

| Field               | Notes                                                                          |
| ------------------- | ------------------------------------------------------------------------------ |
| merchant\_id        | Your unique identifier for the merchant                                        |
| merchant\_name      | The name of the merchant (e.g. 'Wal-Mart')                                     |
| merchant\_address   | The street address of the location of the merchant (e.g. '1590 Dunlawton Ave') |
| merchant\_city      | The city of the location of the merchant (e.g. 'Port Orange')                  |
| merchant\_state     | The state of the location of the merchant (e.g. 'FL')                          |
| merchant\_zip\_code | The zip code of the location of the merchant (e.g. '32127')                    |
| merchant\_country   | The country of the location of the merchant (e.g. 'USA')                       |

**Example merchant list:**

| merchant\_id | merchant\_name | merchant\_address    | merchant\_city | merchant\_state | merchant\_zip\_code | merchant\_country |
| ------------ | -------------- | -------------------- | -------------- | --------------- | ------------------- | ----------------- |
| m-1234       | Wal-Mart       | 590 Dunlawton Ave    | Port Orange    | FL              | 32127               | USA               |
| m-5678       | Starbucks      | 2285 W Northwest Hwy | Dallas         | TX              | 75220               | USA               |

### Receiving attributed transactions

We will return a CSV file via SFTP of attributed transactions which includes the `enrichmentId` as well as the unique  `merchant_id` associated with that transaction.

**Example returned attribution file:**

| enrichment\_id                       | merchant\_id |
| ------------------------------------ | ------------ |
| d1f7490c-719e-4c75-8bfa-535c8a32b936 | m-1234       |
| d8ef0ac5-48a9-43b8-a234-675931d3b5ec | m-5678       |
| 9a796a90-fd37-44ae-8528-c655a6368c5b | m-1234       |

We can also support returning additional metadata. If you need this for your implementation please work with your Spade account team.

<Info>
  We generally return daily files but can also return weekly or monthly files depending on your needs. We have planned work to support returning attribution information in the real time enrichment response.
</Info>

## Exchanging data with Spade

We currently support data sharing via SFTP to:

* Provide and update your list of merchants
* Receive attribution data for your transactions

<Note>
  Please work with your Spade account team for details on connecting to our SFTP server as well to provide us access to your SFTP server.
</Note>

## Optimizing the attribution agent

We can modify our attribution agent to:

* increase accuracy with a trade off of potentially lower attribution rates
* increase attribution rates with a trade off of potential false positives

<Note>
  Please work with your Spade account team for any modifications.
</Note>