### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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. ``` -------------------------------- ### 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 ``` -------------------------------- ### 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" } ] } ``` -------------------------------- ### 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" } ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 } ] } ``` -------------------------------- ### 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 ``` -------------------------------- ### 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/..." } ] ``` -------------------------------- ### 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 ``` -------------------------------- ### Retrieve batch status Source: https://docs.spade.com/reference/batch-enrichment-guide Example response from the status endpoint indicating a completed batch. ```json { "batchId": "8590f0f5-2a4b-431e-baa8-cd3bfff22020", "status": "completed" } ``` -------------------------------- ### GET /categories Source: https://docs.spade.com/api-reference/category-personalization/get-all-default-and-custom-integration-level-categories Fetch a list of all default and custom integration-level categories. ```APIDOC ## GET /categories ### Description Fetch categories from Spade's database. This endpoint returns a list containing Spade's default categories, plus any custom integration-level categories you've created. ### Method GET ### Endpoint /categories ``` -------------------------------- ### Parsed Merchant Data Example Source: https://docs.spade.com/reference/card-enrichment-guide Format for sending pre-parsed merchant data to the /transactions/cards/enrich endpoint. ```text MerchantName: WMSUPERCENTER#582 City: PORT ORANGE Region: FL Country: US ``` -------------------------------- ### Retrieve enriched batch results Source: https://docs.spade.com/reference/batch-enrichment-guide Example of the enriched data returned by the results endpoint. ```json { "batchId": "8590f0f5-2a4b-431e-baa8-cd3bfff22020", "results": [ { "statusCode": 200, "transactionInfo": { "type": "spending", "subType": null, "display": { "name": "Walmart", "categoryName": "Department Stores", "graphic": "https://static.v2.spadeapi.com/logos/d730906bf1a849f19939f27390170a6d/light.png", "graphicSource": "counterparty" }, "thirdParties": [], "spendingInfo": { "channel": { "value": "physical" } }, "transferInfo": null, "atmInfo": null, "isAccountVerification": null, "isPeerToPeer": null, ``` -------------------------------- ### Report Transaction Metadata Source: https://docs.spade.com/api-reference/feedback-and-reporting/report-a-card-enrichment-as-incorrect Example structure for reporting transaction identifiers and timestamps. ```yaml examples: - c1d4064b-9364-43d3-8ee3-500898cda1aa occurredAt: type: string format: date-time description: >- Date and time the transaction occurred. Formatted as an ISO 8601 date time. examples: - '2024-06-06T14:25:11+00:00' transactionId: type: string description: Customer-provided identifier for the transaction. examples: - d6c4dc4e-e0da-4782-b581-95916523d87a ``` -------------------------------- ### Display Single-line Address Source: https://docs.spade.com/reference/improved-ux Example of a location object where addressLine2 is null, indicating a single-line address. ```bash { "location": [ { "id": "fdf79470-3gd38-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 } ] } ``` -------------------------------- ### GET /categories Source: https://docs.spade.com/reference/integration-category-personalization-guide Fetches the list of all default categories available for your integration. ```APIDOC ## GET /categories ### Description Retrieves a list of all categories provided by Spade, including any custom categories added at the integration level. ### Method GET ### Endpoint https://east.sandbox.spade.com/categories ### Response #### Success Response (200) - **id** (string) - Unique identifier for the category. - **name** (string) - Name of the category. - **icon** (string) - URL to the category icon. - **fullCategoryHierarchy** (array) - List of objects representing the category's hierarchy. #### Response Example [ { "id": "001-000-000-000", "name": "Banking and Finance", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png", "fullCategoryHierarchy": [ { "id": "001-000-000-000", "name": "Banking and Finance", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png" } ] } ] ``` -------------------------------- ### OpenAPI Specification for Categories Source: https://docs.spade.com/api-reference/category-personalization/get-all-default-and-custom-integration-level-categories The OpenAPI definition for the GET /categories 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 . 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: /categories: get: tags: - Category Personalization summary: Get all default and custom integration-level categories description: >- Fetch categories from Spade's database. This endpoint returns a list containing Spade's default categories, plus any custom integration-level categories you've created. ``` -------------------------------- ### Universal Data Enrichment Request Source: https://docs.spade.com/reference/universal-data-enrichment Example payload for the /transactions/universal/enrich endpoint. ```json { "description": "SQ* BLACK SEED BAGELS BROOKLYN NY", "amount": "14.25", "currencyCode": "USD", "occurredAt": "2025-09-15", "userId": "u-1234", "transactionId": "48FA5E16-6870-42D2-AECE-AF393714EB1C" } ``` -------------------------------- ### Registration Status Response Source: https://docs.spade.com/reference/category-action-triggers-guide Example JSON response indicating a successful registration with active category triggers. ```json { "status": "succeeded", "version": 1, "categoryTriggers": [ { "id": "travel-reward", "action": { "type": "REWARD", "rewardPercent": 3, "offerId": "travel-3x-promo" } }, { "id": "block-gambling", "action": { "type": "BLOCK", "reason": "Gambling transactions not permitted" } } ], "totalCount": 2 } ``` -------------------------------- ### Category response structure Source: https://docs.spade.com/reference/integration-category-personalization-guide Example of the JSON response returned when fetching categories, showing the hierarchical structure. ```json [ { "id": "001-000-000-000", "name": "Banking and Finance", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png", "fullCategoryHierarchy": [ { "id": "001-000-000-000", "name": "Banking and Finance", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png" } ] }, { "id": "001-001-000-000", "name": "Accounting and Bookkeeping", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png", "fullCategoryHierarchy": [ { "id": "001-000-000-000", "name": "Banking and Finance", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png" }, { "id": "001-001-000-000", "name": "Accounting and Bookkeeping", "icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png" } ] }, ... ] ``` -------------------------------- ### Error Handling Response Source: https://docs.spade.com/reference/universal-data-enrichment Example of a 400 error response indicating missing required fields. ```json { "currencyCode": [ "This field is required." ] } ``` -------------------------------- ### Merchant search response structure Source: https://docs.spade.com/reference/merchant-search-guide Example JSON response returned by the /corporations endpoint. ```json { "corporations": [ { "name": "Starbucks", "logo": "https://static.v2.spadeapi.com/logos/.../light.png", "website": "starbucks.com" }, { "name": "Starlink", "logo": "https://static.v2.spadeapi.com/logos/.../light.png", "website": "starlink.com" } ] } ``` -------------------------------- ### Handle error report responses Source: https://docs.spade.com/reference/error-reporting-guide Examples of successful and failed API responses for error reporting. ```json { "details": "Enrichment successfully reported." } ``` ```json { "enrichmentId": [ "Must be a valid UUID." ] } ``` -------------------------------- ### Enrichment Response Action Source Source: https://docs.spade.com/changelog/changelog Example of the actions array in an enrichment response, now including the source field. ```json "actions": [ { "id": "trigger-123", "type": "merchant_trigger", "action": { "type": "REWARD", "points": 100 }, "scope": "account", "source": "counterparty" } ] ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 . 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 ``` -------------------------------- ### Submit a synchronous microbatch request via cURL Source: https://docs.spade.com/reference/microbatch-enrichment-guide Use this command to send a small batch of transactions for immediate enrichment. Ensure the synchronous parameter is set to true and include your API key in the headers. ```bash curl https://east.sandbox.spade.com/batches/transactions/universal/enrich?synchronous=true \ -H "Content-Type: application/json" \ -H "X-Api-Key: " \ -d '{ "transactions": [ { "transactionId": "48FA5E16-6870-42D2-AECE-AF393714EB1C", "description": "SQ* BLACK SEED BAGELS BROOKLYN NY", "amount": "14.25", "currencyCode": "USD", "occurredAt": "2025-09-15", "userId": "u-1234" } ] }' ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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}") ``` -------------------------------- ### 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": ""} ) 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//results \ -H "X-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 ``` -------------------------------- ### 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. ``` -------------------------------- ### 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 ``` -------------------------------- ### 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", ... } ] ``` -------------------------------- ### Receive batch notifications via webhook Source: https://docs.spade.com/reference/batch-enrichment-guide Flask endpoint example for receiving batch status updates, including token validation. ```python from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/batch-notifications', methods=['POST']) def batch_notification(): 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: raise InvalidTokenError() data = request.json batch_id = data["batchId"] status = data["status"] if status == "completed": fetch_batch_results(batch_id) elif status == "failed": log_batch_failure(batch_id) ``` -------------------------------- ### Display Object Structure Source: https://docs.spade.com/reference/improved-ux The display object aggregates counterparty and third-party information for UI rendering. ```bash { "display": { "name": "DoorDash - Spade Pizza", "categoryName": "Restaurants", "graphic": "https://static.v2.spadeapi.com/logos/...png", "graphicSource": "counterparty" } } ```