# Data Enrichment API source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/api/index.md This section explains how to use [Data Enrichment](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/index.md) via API. We also have a [Batch Processing](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-enrichment/batch/index.md) solution. ## How It Works - API {#how-it-works---api} For most use cases we recommend using Transaction Data Enrichment via the API. The API can handle up to 5,000 calls per hour. Each call can contain up to 1000 transactions, so up to 5 million transactions per hour can be handled by the API. Note: When testing in Sandbox, you can perform up to 50 calls a day, with a maximum of 10 transactions to be enriched per call. Contact your Customer Success Manager (CSM) to be moved to Test Drive Premium for testing with higher volumes against our production environment. Test Drive Premium requires a contract to be signed and will be available for 30 days. 1. **Generate the required credentials to call the API** See the [API Basics](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) section for details of how to create a project and obtain the required credentials (partner ID, partner secret, and app key). 2. **Create an Access Token** All requests sent to Mastercard Open Finance must include a `Finicity-App-Token` HTTP header. Use the following endpoint to generate a new access token: API Reference: `POST /aggregation/v2/partners/authentication` * Command: ```sh curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Accept: application/json' \ --data-raw '{ "partnerId": "{{partnerId}}", "partnerSecret": "{{partnerSecret}}" }' ``` * Expected response: ```json { "token": "YBh22Sb9Es6e66Q7lWdt" } ``` See [Partner Authentication](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#authentication) for more details. 3. **Call the Transaction Data Enrichment endpoint** Use the following endpoint to send the transaction data you want to enrich. API Reference: `POST /data-enrichment/transactions` You will need to include your `Finicity-App-Token` created in the last step in the request header, along with the `Finicity-App-Key` created when you set up your Open Finance US project on Mastercard Developers. You can include up to 1000 transactions in the request payload. * Command: ```sh curl --location --request POST 'https://api.finicity.com/data-enrichment/transactions' \ --header 'Content-Type: application/json' \ --header 'Finicity-App-Key: {{appKey}}' \ --header 'Finicity-App-Token: {{appToken}}' \ --header 'Accept: application/json' \ --data-raw '{ "transactions": [ ... ] }' ``` Note that the `externalCustomerId` and `externalAccountId` fields enable you to map the transactions back to your data. **Do not send Mastercard plaintext representations of customer or account IDs**. The representative IDs must be obfuscated through cryptographically strong hashing (we recommend using SHA-2 or SHA-3 methods). The response payload will consist of the same list of transactions, enhanced with additional details such as transaction category, merchant name, logo, website, and address. It will also provide information about any platform or payment processor involved in the transaction. ## Sequence Diagram {#sequence-diagram} Diagram data-enrichment-api ## API example {#api-example} The following example shows how the transaction data provided in the API request is enhanced with additional information about the merchant, payment processor, platform or intermediary, and other information which Data Enrichment has been able to provide about each transaction. **Request** Provide the transaction data you have in the request body with the details you have of the transactions. You should include as much data as you can about the transactions (many of the request fields are optional for this reason---populate the optional fields where you can, omit them where you don't have the data). Warning: The `externalCustomerId` and `externalAccountId` fields are to allow you to map the transactions back to your data. **Do not send Mastercard plaintext representations of customer or account IDs**. The representative IDs must be obfuscated through cryptographically strong hashing (we recommend using SHA-2 or SHA-3 methods). For example, the following shows a single transaction as it might be presented in the request body (normally you would pass more transactions in the array): * Json ```json { "transactions": [ { "externalCustomerId": "1005061234", "externalAccountId": "1005061234", "accountType": "checking", "externalTransactionId": "MAC1005061233", "postedTimestamp": "2024-07-26T11:00:00Z", "transactionTimestamp": "2024-07-26T11:00:00Z", "description": "STARBUCKS STORE 06565 LITTLETON CO 07/26", "memo": "debit", "amount": -13.26, "transactionFee": 0, "type": "DEBIT", "directionIndicator": "Debit", "additionalDetails": { "key1": "value1" } }, { // further transaction data } ] } ``` **Response** The response will consist of the same array of transaction data, appended with additional information such as the transaction category, an `entities` array, and also potentially an `address` object. The `entities` data contains the additional information about the merchant, and potentially other entities involved in an individual transaction, such as a payment processor or other platform. Each entity is shown as belonging to a certain `category` in the response. Some categories (such as "Coffee Shops" or "Fast Food") are obvious and relate to the business which the merchant is involved with. Other categories relate to the role that an intermediary plays in the transaction, such as a Payment Processor or Platform. Some illustrative examples are shown in the table below. | Entity Category | Meaning | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | BNPL Provider | A financing service that allows consumers to purchase goods or services immediately and pay for them over time, often in interest-free installments. Examples include: Affirm, Afterpay, Klarna, Sezzle, Sunbit, Zip. | | Delivery Service | A platform that coordinates the purchase and delivery of goods from third-party merchants to consumers, such as DoorDash, Grubhub, Instacart, Postmates, Shipt, or Uber Eats. | | Digital Wallet | A financial application that allows users to store funds, send and receive money, make transactions, and track payment history on mobile or online applications. Examples include: Apple Cash, Apple Pay, Cash App, Venmo, Zelle. | | Financial Institution | The financial institution associated with the transaction. | | Marketplace | A platform that facilitates transactions between consumers and independent third-party sellers or service providers, such as Etsy, Airbnb, or Symphony Commerce. | | Payment Network | A system that facilitates the transfer of funds between issuing banks, acquiring banks, merchants, and consumers by routing payment transactions, such as Mastercard. | | Payment Processor | A payment processor manages the transaction process for an entity. Examples include: Adyen, PayPal, Square, Stripe, Toast. | | Platform | Financial, payment, and business enablement solutions, such as ADP, Shopify, or Wix. | For example, in the response below, the Starbucks transaction provided has been enhanced with business details for Starbucks, as well as the address of the outlet concerned. The transactions are also categorized, and for each transaction and entity a confidence score between 0 and 100 is provided, with 100 being a high degree of confidence. * Json ```json { "transactions": [ { "externalCustomerId": "1005061234", "externalAccountId": "1005061234", "accountType": "checking", "externalTransactionId": "MAC1005061233", "postedTimestamp": "2024-07-26T11:00:00Z", "transactionTimestamp": "2024-07-26T11:00:00Z", "description": "STARBUCKS STORE 06565 LITTLETON CO 07/26", "memo": "debit", "amount": -13.26, "transactionFee": 0, "transactionCategory": "Coffee Shops", "transactionCategoryScore": 45, "transactionCategoryGroup": "Groceries & Dining", "type": "DEBIT", "directionIndicator": "Debit", "entities": [ { "id": "MTc1ODA5NDU0MTYwNjM1OTA0MA== ", "name": "Starbucks", "category": "Coffee Shops", "group": "Cafe", "website": "https://starbucks.com", "logoUrl": "https://institution-branding-assets-cf.openbanking.mastercard.com/MTc1ODA5NDU0MTYwNjM1OTA0MA==/logo.svg", "entityStandardizationConfidenceScore": 91 } ], "address": { "line1": "10278 W", "line2": "Centennial Rd", "city": "Littleton", "state": "CO", "postalCode": "80127", "country": "US", "latitude": 39.567229, "longitude": -105.11126, "phoneNumber": "8017339340" }, "additionalDetails": { "key1": "value1" } }, { // further enhanced transaction data } ] } ```