Spade

https://docs.spade.com
Admin
Spade transforms raw transaction details into clean, high-fidelity insights by enriching payment...
Tokens:137,107
Snippets:816
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Counterparty Object Examples

Source: https://docs.spade.com/api-reference/card-enrichment/get-the-results-of-a-batch-card-enrichment-job

Example values for fields within the Counterparty schema.

```yaml
704bbd58-fb12-4bdb-9aae-2786704ea92a
```

```yaml
Amazon
```

```yaml
Amazon Inc.
```

```yaml
93.5
```

```yaml
https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png
```

--------------------------------

### ResponseLocation Object Examples

Source: https://docs.spade.com/api-reference/transfer-enrichment/enrich-a-transfer-transaction

Examples of individual fields within the ResponseLocation object.

```yaml
fdf79470-3deb-4638-956a-6859e473b9d8
```

```yaml
1234 W 5th Ave Suite 100
```

```yaml
1234 W 5th Ave
```

```yaml
Suite 100
```

```yaml
New York
```

```yaml
NY
```

```yaml
USA
```

```yaml
'10001'
```

```yaml
45
```

```yaml
120
```

```yaml
'+18664862360'
```

--------------------------------

### OpenAPI Schema Examples

Source: https://docs.spade.com/api-reference/card-enrichment/enrich-a-card-transaction

Examples of authorization recommendations and trigger scopes within the API schema.

```yaml
examples:
  - type: REWARD
    rewardPercent: 5
    offerId: offer-abc123
  - type: BLOCK
    reason: Gambling merchant
    authRecommendation: BLOCK
  - type: ALLOW_ONLY
    category: approved-vendors
    authRecommendation: ALLOW
```

```yaml
example: account
examples:
  - account
```

--------------------------------

### Action Type Examples

Source: https://docs.spade.com/api-reference/merchant-action-triggers/register-merchant-triggers-at-account-scope

Examples of valid action type configurations for merchant triggers.

```yaml
- type: REWARD
  rewardPercent: 5
  offerId: offer-abc123
- type: BLOCK
  reason: Gambling merchant
- type: ALLOW_ONLY
  category: approved-vendors
```

--------------------------------

### TriggeredActionResponse Schema Examples

Source: https://docs.spade.com/api-reference/card-enrichment/enrich-a-batch-of-card-transactions

Example values for the TriggeredActionResponse object fields.

```yaml
id:
  - trigger-12345
type:
  - merchant_trigger
```

--------------------------------

### ThirdParty Object Examples

Source: https://docs.spade.com/api-reference/card-enrichment/get-the-results-of-a-batch-card-enrichment-job

Example values for fields within the ThirdParty schema.

```yaml
ac48cef2-0d7f-4159-865e-e92b152262bc
```

```yaml
Paypal
```

```yaml
payment_processor
```

```yaml
https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png
```

```yaml
https://www.paypal.com/
```

--------------------------------

### OpenAPI Action Request Examples

Source: https://docs.spade.com/api-reference/category-action-triggers/register-category-triggers-at-account-scope

Example payloads for different action types including reward and block configurations.

```yaml
examples:
            - type: REWARD
              rewardPercent: 3
              offerId: travel-3x-promo
            - type: BLOCK
              reason: Gambling not permitted
            - type: ALLOW_ONLY
```

--------------------------------

### Enrichment and Parse Request Examples

Source: https://docs.spade.com/reference/card-enrichment-guide

Example JSON payloads for the /enrich and /enrich/parse endpoints.

```json
{
  "merchantName": "WMSUPERCENTER#582",
  "acquirerId": "123456789",
  "userId": "user123",
  "cardId": "card123",
  "programId": "program123",
  "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
  "amount": "42.00",
  "currencyCode": "USD",
  "location": {
    "city": "PORT ORANGE",
    "region": "FLORIDA",
    "country": "US"
  },
  "occurredAt": "2025-06-05T1:42:00Z",
  "categoryCode": "5469",
  "categoryType": "MCC"
}
```

```json
{
  "de43": "WMSUPERCENTER#582      PORT ORANGE   FL",
  "userId": "user_id_123456789",
  "programId": "program_id_123",
  "amount": "25.23",
  "currencyCode": "USD",
  "occurredAt": "2025-06-15 18:27:51Z",
  "categoryType": "MCC",
  "categoryCode": "5812",
  "cardId": "card_id_123456789",
  "cardFirstSix": "123456",
  "cardLastFour": "7890",
  "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
  "acquirerId": "123456789",
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  }
}
```

--------------------------------

### Third Party Schema Example

Source: https://docs.spade.com/api-reference/card-enrichment/enrich-a-batch-of-card-transactions

Example of the third-party object structure including ID and name.

```yaml
id: ac48cef2-0d7f-4159-865e-e92b152262bc
name: Paypal
```

--------------------------------

### Merchant Location and Attribute Examples

Source: https://docs.spade.com/api-reference/merchant-action-triggers/register-merchant-triggers-at-account-scope

Example values for merchant location fields and custom attributes.

```yaml
website: https://www.starbucks.com
address: 123 Main St
city: Seattle
region: WA
country: USA
postalCode: '98101'
latitude: 47.6062
longitude: -122.3321
level: corporation
customAttributes: 
  storeId: store-789
```

--------------------------------

### Error Response Examples

Source: https://docs.spade.com/api-reference/merchant-action-triggers/register-merchant-triggers-at-account-scope

Example error messages returned by the API.

```yaml
invalidField: 
  - This field is required.
details: Incorrect authentication credentials.
details: Internal server error.
```

--------------------------------

### OpenAPI Property and Example Definitions

Source: https://docs.spade.com/api-reference/category-action-triggers/incremental-category-trigger-operations-at-program-scope

Defines the structure for action types and provides example payloads for different trigger scenarios.

```yaml
properties:
            type:
              type: string
              description: >
                Optional action type. Reserved values `BLOCK` and `ALLOW_ONLY`
                have special authorization semantics (see above). All other
                values are passed through without modification.
              examples:
                - REWARD
                - BLOCK
                - ALLOW_ONLY
          additionalProperties: true
          examples:
            - type: REWARD
              rewardPercent: 3
              offerId: travel-3x-promo
            - type: BLOCK
              reason: Gambling not permitted
            - type: ALLOW_ONLY
```

--------------------------------

### Action Type Request Examples

Source: https://docs.spade.com/api-reference/category-action-triggers/incremental-category-trigger-operations-at-card-scope

Example payloads for different action types including reward and restriction configurations.

```yaml
examples:
  - type: REWARD
    rewardPercent: 3
    offerId: travel-3x-promo
  - type: BLOCK
    reason: Gambling not permitted
  - type: ALLOW_ONLY
```

--------------------------------

### Industry Category Level Schema Examples

Source: https://docs.spade.com/api-reference/transfer-enrichment/enrich-a-transfer-transaction

Examples for individual properties within the IndustryCategoryLevel object.

```yaml
011-000-000-000
```

```yaml
Retail
```

```yaml
https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
```

--------------------------------

### Search merchant database

Source: https://docs.spade.com/reference/merchant-locked-cards

Example response from the GET /corporations endpoint used to power merchant autocomplete widgets.

```json
{
  "corporations": [
    {
      "name": "OpenAI",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "openai.com"
    },
    {
      "name": "OpenTable",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "opentable.com"
    },
    ...
  ]
}
```

--------------------------------

### Triggered Action Response Example

Source: https://docs.spade.com/api-reference/card-enrichment/get-the-results-of-a-batch-card-enrichment-job

Example structure for a triggered action response within the API.

```yaml
- - id: trigger-12345
    type: merchant_trigger
    action:
      type: REWARD
      rewardPercent: 5
    scope: account
    source: counterparty
```

--------------------------------

### MobileAppInfo Schema Examples

Source: https://docs.spade.com/api-reference/card-enrichment/enrich-a-batch-of-card-transactions

Example values for fields within the MobileAppInfo object, including identifiers, URLs, and categorical metadata.

```yaml
id:
  - 704bbd58-fb12-4bdb-9aae-2786704ea92a
name:
  - Roblox
url:
  - https://play.google.com/store/apps/details?id=com.roblox.client
logo:
  - https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png
developerName:
  - Roblox Corporation
developerId:
  - 704bbd58-fb12-4bdb-9aae-2786704ea92a
category:
  - Auto and Transportation
hasGamblingOrRewards:
  - false
hasSimulatedGambling:
  - false
ageRating:
  - Teen
```

--------------------------------

### Transaction display examples

Source: https://docs.spade.com/reference/improved-ux

These JSON examples demonstrate how the 'display.name' field changes based on the third-party payment processor or delivery service involved in the transaction.

```json
{
    "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"
                }
            ]
        }
    ]
}
```

```json
{
    "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"
                }
            ]
        }
    ]
}
```

--------------------------------

### OpenAPI schema examples for card enrichment

Source: https://docs.spade.com/api-reference/card-enrichment/get-the-results-of-a-batch-card-enrichment-job

Examples of JSON structures for enrichment results, including reward types, block reasons, and authorization recommendations.

```json
{
  "type": "REWARD",
  "rewardPercent": 5,
  "offerId": "offer-abc123"
}
```

```json
{
  "type": "BLOCK",
  "reason": "Gambling merchant",
  "authRecommendation": "BLOCK"
}
```

```json
{
  "type": "ALLOW_ONLY",
  "category": "approved-vendors",
  "authRecommendation": "ALLOW"
}
```

--------------------------------

### Category Action Trigger PATCH Request Examples

Source: https://docs.spade.com/api-reference/category-action-triggers/incremental-category-trigger-operations-at-account-scope

Examples of JSON request bodies for adding or removing category action triggers.

```json
operation: add
categoryTriggers:
  - id: groceries-reward
    categoryId: 005-001-000-000
    action:
      type: REWARD
      rewardPercent: 2
      offerId: groceries-2x
```

```json
operation: remove
triggerIds:
  - block-gambling
```

--------------------------------

### Receive auth recommendations

Source: https://docs.spade.com/reference/merchant-locked-cards

Examples of authRecommendation responses for matched and unmatched merchants.

```json
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "ALLOW_ONLY",
      "action": {
        "type": "ALLOW_ONLY",
        "authRecommendation": "ALLOW"
      },
      "scope": "card"
    }
  ]
}
```

```json
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "ALLOW_ONLY",
      "action": {
        "type": "ALLOW_ONLY",
        "authRecommendation": "BLOCK"
      },
      "scope": "card"
    }
  ]
}
```

--------------------------------

### Industry Category Level Example

Source: https://docs.spade.com/api-reference/transfer-enrichment/get-the-results-of-a-batch-transfer-enrichment-job

Example of an industry category node within the hierarchical category system.

```yaml
id:
  type: string
  maxLength: 15
  examples:
    - 011-000-000-000
name:
  type: string
  maxLength: 64
  examples:
    - Retail
icon:
  type:
    - string
    - 'null'
  maxLength: 128
  format: url
  examples:
    - >-
      https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
```

--------------------------------

### Custom Attributes Request Field Example

Source: https://docs.spade.com/api-reference/card-enrichment/enrich-a-batch-of-card-transactions

Example of the dictionary structure for passing custom attributes in a request.

```yaml
custom_attribute_1: value_1
custom_attribute_2: value_2
```

--------------------------------

### GET /merchant-action-triggers

Source: https://docs.spade.com/api-reference/merchant-action-triggers/get-account-level-trigger-status

Get the status and version of the latest merchant action trigger registration at the account scope.

```APIDOC
## GET /merchant-action-triggers

### Description
Get the status and version of the latest merchant action trigger registration at the account scope. Account-level triggers apply to all transactions for all users in your account.

### Method
GET

### Endpoint
/merchant-action-triggers

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration (pending, running, or succeeded).

#### Error Response (404)
- **detail** (string) - No action triggers exist for this scope
```

--------------------------------

### GET /category-action-triggers

Source: https://docs.spade.com/api-reference/category-action-triggers/get-account-level-category-trigger-status

Get the status and version of the latest category action trigger registration at the account scope.

```APIDOC
## GET /category-action-triggers

### Description
Get the status and version of the latest category action trigger registration at the account scope. Account-level triggers apply to all transactions for all users in your account.

### Method
GET

### Endpoint
/category-action-triggers

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration. Possible value: `succeeded` (Registration complete, triggers are now active).

#### Error Response (404)
- **detail** (string) - No action triggers exist for this scope
```

--------------------------------

### Display Multi-line Address

Source: https://docs.spade.com/reference/improved-ux

Example of a location object containing both addressLine1 and addressLine2 fields.

```bash
{
    "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
        }
    ]
}
```

--------------------------------

### Example Enrichment Response

Source: https://docs.spade.com/reference/mobile-app-data

A sample JSON response showing the structure of mobile app data, including transaction details, counterparty information, and the mobileAppInfo object.

```json
{
  "transactionInfo": {
    "type": "spending",
    "subType": null,
    "display": {
      "name": "Artificial Life - Google Play",
      "categoryName": "Mobile App: Education and Parenting",
      "graphic": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
      "graphicSource": "third_party"
    },
    "thirdParties": [
      {
        "id": "58c03a73-629c-46b8-aa4c-1e15cb4f0d0b",
        "name": "Google Play",
        "type": "marketplace",
        "logo": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
        "website": "https://play.google.com/"
      }
    ],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "transferInfo": null,
    "atmInfo": null,
    "isAccountVerification": null,
    "isPeerToPeer": null,
    "isDigitalWallet": null,
    "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2"
  },
  "counterparty": [
    {
      "id": "0d1ef10f-2652-39bd-98f1-af34ae03a4a7",
      "name": "Artificial Life",
      "legalName": null,
      "industry": [],
      "location": [
        {
          "id": null,
          "address": null,
          "addressLine1": null,
          "addressLine2": null,
          "city": "Tampa",
          "region": "FL",
          "postalCode": null,
          "country": "USA",
          "phoneNumber": null,
          "latitude": null,
          "longitude": null,
          "matchScore": null
        }
      ],
      "matchScore": 90.13,
      "logo": null,
      "medianSpendPerTransaction": null,
      "phoneNumber": null,
      "website": "https://play.google.com/store/apps/details?id=com.mooncoder.alife"
    }
  ],
  "enrichmentId": "2c7dab64-8f37-44b3-b482-cc1c8f71ab0d",
  "mobileAppInfo": {
    "id": "0d1ef10f-2652-39bd-98f1-af34ae03a4a7",
    "name": "Artificial Life",
    "url": "https://play.google.com/store/apps/details?id=com.mooncoder.alife",
    "logo": null,
    "developerName": "Mooncoder",
    "developerId": "f6fdc9b1-f0ea-3dda-8e15-ead6fe5755fe",
    "category": "Education and Parenting",
    "hasGamblingOrRewards": false,
    "hasSimulatedGambling": false,
    "ageRating": "Children"
  }
}
```

--------------------------------

### Industry Classification Tree Example

Source: https://docs.spade.com/reference/concepts

Displays the hierarchical structure of industry categories for a merchant, moving from general to specific classifications.

```bash
[
  {
    "id": "011-000-000-000",
    "name": "Retail",
    "icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
  },
  {
    "id": "011-018-000-000",
    "name": "General Goods",
    "icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
  },
  {
    "id": "011-018-002-000",
    "name": "Department Stores",
    "icon": "/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
  }
]
```

--------------------------------

### OpenAPI Specification for Get User-Level Trigger Status

Source: https://docs.spade.com/api-reference/merchant-action-triggers/get-user-level-trigger-status

The OpenAPI definition for the GET /users/{userId}/merchant-action-triggers endpoint.

```yaml
openapi: 3.1.0
info:
  title: Spade API
  description: >-
    Documentation for Spade's card transaction enrichment API and related
    endpoints. We offer sandbox and production environments on both the east
    coast and west coast to enable ultra low latency enrichment for realtime
    applications. Each environment requires different API keys. To inquire about
    API keys, please contact your Spade representative or reach out to
    <hello@spade.com>.
  version: 2.7.3
servers:
  - url: https://east.sandbox.spade.com
    description: East coast sandbox environment
  - url: https://east.api.spade.com
    description: East coast production environment
  - url: https://west.sandbox.spade.com
    description: West coast sandbox environment
  - url: https://west.api.spade.com
    description: West coast production environment
  - url: https://sandbox.v2.spadeapi.com
    description: East coast sandbox environment (deprecated)
  - url: https://v2.spadeapi.com
    description: East coast production environment (deprecated)
  - url: https://sandbox.west.v2.spadeapi.com
    description: West coast sandbox environment (deprecated)
  - url: https://west.v2.spadeapi.com
    description: West coast production environment (deprecated)
security:
  - ApiKeyAuth: []
tags:
  - name: Card Enrichment
    description: Enrich card transactions
  - name: Transfer Enrichment
    description: Enrich transfers
  - name: Category Personalization
    description: Create custom categories and personalize enrichments
  - name: Feedback and Reporting
    description: Provide feedback on card events or report enrichment errors
  - name: Merchant Search
    description: Search for Spade merchants
  - name: Merchant Action Triggers
    description: >-
      Register merchant action triggers and receive triggered actions in
      enrichment responses
  - name: Category Action Triggers
    description: >-
      Register category action triggers and receive triggered actions in
      enrichment responses
paths:
  /users/{userId}/merchant-action-triggers:
    parameters:
      - in: path
        name: userId
        schema:
          type: string
          maxLength: 512
        description: Your unique identifier for the user
        required: true
    get:
      tags:
        - Merchant Action Triggers
      summary: Get user-level trigger status
      description: >-
        Get the status and version of the latest merchant action trigger
        registration at the user scope.


        User-level triggers apply to all transactions for all cards belonging to
        the specified user.


        **Important:** Triggers are only applied to enrichment responses when
        the status is `succeeded`.


        To learn more about action triggers, please read the [Merchant Action
        Triggers
        Guide](https://docs.spade.com/reference/merchant-action-triggers-guide).
      operationId: userMerchantActionTriggersGet
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionTriggerStatusResponse'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No action triggers exist for this scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    examples:
                      - No action triggers exist for this scope
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ActionTriggerStatusResponse:
      type: object
      description: Response containing the status of an action trigger registration.
      properties:
        status:
          type: string
          description: >
            The current status of the action trigger registration.

            - `pending`: Registration received, processing not yet started

            - `running`: Registration is being processed (for batch
            registrations with >100 triggers)

            - `succeeded`: Registration complete, triggers are now active
```

--------------------------------

### Raw DE43 String Example

Source: https://docs.spade.com/reference/card-enrichment-guide

Format for sending raw DE43 merchant data strings to the /transactions/cards/enrich/parse endpoint.

```json
DE43: WMSUPERCENTER#582      PORT ORANGE   FL
```

--------------------------------

### GET /programs/{programId}/merchant-action-triggers

Source: https://docs.spade.com/api-reference/merchant-action-triggers/get-program-level-trigger-status

Get the status and version of the latest merchant action trigger registration at the program scope.

```APIDOC
## GET /programs/{programId}/merchant-action-triggers

### Description
Get the status and version of the latest merchant action trigger registration at the program scope. Program-level triggers apply to all enrichment requests where the `programId` field matches this program.

### Method
GET

### Endpoint
/programs/{programId}/merchant-action-triggers

### Parameters
#### Path Parameters
- **programId** (string) - Required - Your unique identifier for the program
```

--------------------------------

### Handle Returned Enrichment Callbacks

Source: https://docs.spade.com/reference/error-reporting-guide

Examples for testing the callback endpoint with curl and implementing a secure handler in Python using Flask.

```shell
# Example of what the callback request from Spade looks like:
# POST https://your-domain.com/spade/corrections
# Headers:
#   Content-Type: application/json
#   X-Webhook-Token: your-callback-token-from-spade
# Body: returned card enrichment response JSON

# You can test your callback endpoint with curl:
curl --request POST \
--url https://your-domain.com/spade/corrections \
--header 'content-type: application/json' \
--header 'X-Webhook-Token: your-callback-token-from-spade' \
--data '{
  "transactionInfo": {
    "type": "spending",
    "display": {
      "name": "Walmart Neighborhood Market",
      "categoryName": "Grocery Stores"
    }
  },
  "enrichmentId": "050d3a73-c212-4f89-b9c0-0e75da0efeea"
}'
```

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/spade/corrections', methods=['POST'])
def handle_returned_enrichment():
    # Validate the webhook token
    webhook_token = request.headers.get('X-Webhook-Token')
    expected_token = "your-callback-token-from-spade"  # Store this securely

    if not webhook_token or webhook_token != expected_token:
        return jsonify({"error": "Invalid token"}), 403

    # Process the returned enrichment
    returned_enrichment = request.json
    enrichment_id = returned_enrichment["enrichmentId"]

    # Update your records with the returned data
    update_enrichment_in_database(enrichment_id, returned_enrichment)

    return jsonify({"status": "received"}), 200

def update_enrichment_in_database(enrichment_id, returned_enrichment):
    # Save the changes to your systems as necessary
    print(f"Saving Enrichment {enrichment_id}: {returned_enrichment}")
```

--------------------------------

### GET /users/{userId}/merchant-action-triggers

Source: https://docs.spade.com/api-reference/merchant-action-triggers/get-user-level-trigger-status

Get the status and version of the latest merchant action trigger registration at the user scope.

```APIDOC
## GET /users/{userId}/merchant-action-triggers

### Description
Get the status and version of the latest merchant action trigger registration at the user scope. User-level triggers apply to all transactions for all cards belonging to the specified user.

### Method
GET

### Endpoint
/users/{userId}/merchant-action-triggers

### Parameters
#### Path Parameters
- **userId** (string) - Required - Your unique identifier for the user

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration (pending, running, or succeeded).

#### Error Response (404)
- **detail** (string) - No action triggers exist for this scope
```

--------------------------------

### Retrieve Batch Results

Source: https://docs.spade.com/reference/batch-merchant-enrichment-guide

Use these examples to fetch the results of a completed batch process. Note that the endpoint returns a 202 status if the batch is still processing, requiring a polling strategy until a 200 status is received.

```python
response = requests.get(
    f"https://east.sandbox.spade.com/batches/{batch_id}/results",
    headers={"X-Api-Key": "<YOUR_SANDBOX_API_KEY>"}
)

data = response.json()
for result in data["results"]:
print(f"ID: {result['id']}")
print(f"Predicted MCC: {result['predictedMcc']}")
print(f"Industry: {result['industry']}")
```

```bash
curl https://east.sandbox.spade.com/batches/<BATCH_ID>/results \
  -H "X-Api-Key: <YOUR_SANDBOX_API_KEY>"
```

--------------------------------

### GET /users/{userId}/category-action-triggers

Source: https://docs.spade.com/api-reference/category-action-triggers/get-user-level-category-trigger-status

Get the status and version of the latest category action trigger registration at the user scope.

```APIDOC
## GET /users/{userId}/category-action-triggers

### Description
Get the status and version of the latest category action trigger registration at the user scope. User-level triggers apply to all transactions for all cards belonging to the specified user.

### Method
GET

### Endpoint
/users/{userId}/category-action-triggers

### Parameters
#### Path Parameters
- **userId** (string) - Required - Your unique identifier for the user

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration (e.g., 'succeeded')

#### Error Response (404)
- **detail** (string) - No action triggers exist for this scope
```

--------------------------------

### Category Response Format

Source: https://docs.spade.com/reference/category-action-triggers-guide

Example JSON response containing category identifiers and metadata.

```json
[
  {
    "id": "020-001-000-000",
    "name": "Travel",
    "icon": "https://static.v2.spadeapi.com/categories/..."
  },
  {
    "id": "019-001-000-000",
    "name": "Gambling",
    "icon": "https://static.v2.spadeapi.com/categories/..."
  }
]
```

--------------------------------

### GET /programs/{programId}/category-action-triggers

Source: https://docs.spade.com/api-reference/category-action-triggers/get-program-level-category-trigger-status

Get the status and version of the latest category action trigger registration at the program scope.

```APIDOC
## GET /programs/{programId}/category-action-triggers

### Description
Get the status and version of the latest category action trigger registration at the program scope. Program-level triggers apply to all enrichment requests where the programId field matches this program.

### Method
GET

### Endpoint
/programs/{programId}/category-action-triggers

### Parameters
#### Path Parameters
- **programId** (string) - Required - Your unique identifier for the program

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration.
```

--------------------------------

### Location Data Structure Update

Source: https://docs.spade.com/changelog/changelog

Example showing the inclusion of addressLine1 and addressLine2 fields within the location object.

```json
"location": [
    {
      ...
      "address": "1234 W 5th Ave Suite 100",
      "addressLine1": "1234 W 5th Ave",
      "addressLine2": "Suite 100",
      ...
    }
  ]
```

--------------------------------

### GET /users/{userId}/cards/{cardId}/merchant-action-triggers

Source: https://docs.spade.com/api-reference/merchant-action-triggers/get-card-level-trigger-status

Get the status and version of the latest merchant action trigger registration at the card scope.

```APIDOC
## GET /users/{userId}/cards/{cardId}/merchant-action-triggers

### Description
Get the status and version of the latest merchant action trigger registration at the card scope. Card-level triggers apply only to transactions for the specified card. Triggers are only applied to enrichment responses when the status is `succeeded`.

### Method
GET

### Endpoint
/users/{userId}/cards/{cardId}/merchant-action-triggers

### Parameters
#### Path Parameters
- **userId** (string) - Required - Your unique identifier for the user
- **cardId** (string) - Required - Your unique identifier for the card

### Response
#### Success Response (200)
- **status** (string) - The current status of the action trigger registration (e.g., `pending`, `succeeded`)

#### Error Response (404)
- **detail** (string) - No action triggers exist for this scope
```

--------------------------------

### Triggered Actions Response

Source: https://docs.spade.com/api-reference/feedback-and-reporting/report-a-card-enrichment-as-incorrect

Example of the actions array returned when transaction triggers are matched.

```yaml
examples:
  - - id: trigger-12345
      type: merchant_trigger
      action:
        type: REWARD
        rewardPercent: 5
      scope: account
      source: counterparty
```
Tokens:
Raw