--- title: "Enrich a batch of transfers" method: POST path: "/batches/transactions/transfers/enrich" tags: ["Transfer Enrichment"] --- # Enrich a batch of transfers `POST /batches/transactions/transfers/enrich` ## Request - Base URL: `https://east.sandbox.spade.com` - URL: `https://east.sandbox.spade.com/batches/transactions/transfers/enrich` - Auth: API key in header `X-Api-Key` Submit a batch of transfers for enrichment. This endpoint will return a `batchId` which can be used in the `/batches/{batchId}` and `/batches/{batchId}/results` endpoints to check the status of the batch job and retrieve the results. You can pass `?synchronous=true` to enrich smaller sets of transactions synchronously. See the [Microbatch enrichment guide](https://docs.spade.com/reference/microbatch-enrichment-guide) for details. Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to sales@spade.com with any questions. ## Query parameters - `synchronous` boolean ## Request body - object - `transactions` BatchTransferEnrichmentRequestItem[], required: An array of transactions to enrich. Each transaction must have a unique transactionId. Maximum 50,000 transactions. - `organizationId` string: An ID representing the organization associated with this transaction. Use this field if you are enriching transactions on behalf of other organizations. Used for billing purposes and for scoping products such as action triggers and category personalizations at the organization-level. For more information, see [Supporting multiple data sources and clients](https://docs.spade.com/reference/integrate-with-spades-api#supporting-multiple-data-sources-and-clients) - `userId` string, required: Anonymous ID representing your user. This will be used for summary features, and recurrence flagging purposes. - `accountId` string: Anonymous ID representing the account of the user (NOT the account number). - `transactionId` string, required: Your ID representing this transaction. Required for batch requests. - `transactionType` string, required: The type of this transaction. By default, the accepted types include `ACH_DEPOSIT`, `ACH_RETURN`, `ACH_WITHDRAWAL`, `ATM`, `CHECK_DEPOSIT`, `CHECK_PAYMENT`, `INTERNATIONAL_WIRE_INCOMING`, `INTERNATIONAL_WIRE_OUTGOING`, `RTP_DEPOSIT`, `RTP_WITHDRAWAL`, `US_WIRE_INCOMING`, `US_WIRE_OUTGOING`, `OTHER_INCOMING`, and `OTHER_OUTGOING`; however, this endpoint also supports a variety of other transfer types, depending on your use case and the data you have available. Please contact your Spade representative if you would like further information about supported transaction types. - `transactionTypeDescription` string: A description of the `transactionType`. This field is intended for systems in which the `transactionType` is a numeric code. In these cases, `transactionTypeDescription` should be the human-readable description of the `transactionType`. - `description` string, required: The full transaction description. Typically, this will be a string containing the name of the merchant or institution involved in the transaction plus information related to the type of transaction such as "ACCT VERIFY", "WEB PMT", "ETRANSFER", etc... - `alternateDescription` string: An alternate transaction description, if available. This will often be a string containing the name of the merchant or institution involved in the transaction. Note that this field is optional and may or may not be available in your system. Please contact your Spade representative if you have any questions about field mappings. - `memo` string: The transaction memo, if your system contains an additional field beyond the `description` and `alternateDescription` fields. Note that this field is optional and may or may not be available in your system. Please contact your Spade representative if you have any questions about field mappings. - `amount` union, required: Value of the transaction in the given currency. Negative values indicate incoming money. - number - string - `currencyCode` string, required - `occurredAt` string, date-time, required: The time the transaction occurred. Formatted as an ISO 8601 date time. - `direction` 'CREDIT' | 'DEBIT': The direction of the transaction. Will take precedence over the direction inferred from the `amount` field. - `billingProfile` 'standard' | 'resell': An optional billing profile for this transaction. When set to "resell", the `organizationId` field is required. For more information, see [Supporting multiple data sources and clients](https://docs.spade.com/reference/integrate-with-spades-api#supporting-multiple-data-sources-and-clients) - `customAttributes` CustomAttributesRequestField: A dictionary containing custom attributes that you would like to be returned in the response. Please ensure this object does not contain any PII. Restrictions include: `customAttributes` must be an object, up 30 custom attributes are allowed, each key must be a string <= 40 characters in length, and each value must be a string <= 250 characters in length. - `callbackUrl` string, url: The URL to call when the batch job is complete. ## Response `200` Successful operation - union - BatchSubmissionResponse - `batchId` string, uuid, required: Unique identifier for the batch job - `status` 'pending' | 'running' | 'completed' | 'failed', required: Current status of the batch job - `batchSize` integer, required: Number of transactions in the batch - `submittedAt` string, date-time, required: Timestamp of when the batch was submitted - object - `results` BatchTransferEnrichmentResponse[] - `transactionInfo` object - `type` 'account_verification' | 'atm' | 'debt' | 'fee' | 'income' | 'other_money_movement' | 'reimbursement' | 'spending': The main type of the transaction. For card transactions, the type is always "spending". - `subType` 'alimony_or_child_support' | 'atm' | 'bnpl' | 'business' | 'cash_advance' | 'deposit' | 'disbursements' | 'earned_income' | 'government_benefits' | 'insurance' | 'investment' | 'nsf' | 'other' | 'overdraft' | 'payment' | 'payout' | 'rental' | 'retirement' | 'tax_refund' | 'transfer' | 'withdrawal', nullable: The more specific type of the transaction, if applicable. For card transactions, the `subType` is always `null`. - `spendingInfo` object, nullable: Additional information about transactions whose `type` is "spending". This field is `null` for other types of transactions. - `channel` object - `value` 'digital' | 'physical' | 'null', nullable: Spending channel value of digital or physical, null if we are unable to determine. - `thirdParties` object[]: An array of third parties involved in the transaction, when applicable. Entities such as Toast, Square, Uber Eats, Doordash, etc. will appear here. - `id` string, uuid - `name` string - `type` 'bnpl' | 'delivery_service' | 'marketplace' | 'payment_processor' | 'platform' - `logo` string, url, nullable: Third party logo. - `website` string, url, nullable: Third party website. - `recurrenceInfo` object, nullable: A recurring transaction is a repeated payment pattern to a counterparty, based on periodicty and amount. Premium Spade Signal available depending on your product package. - `intervalType` 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'annually', nullable: Recurrence cadence. - `intervalDays` integer, nullable: Number of days between recurrences. - `nextPaymentExpected` string, date, nullable: Next expected payment date. - `recentRecurrences` array[], nullable: Array of recent recurrence objects, null if no recurrence exists. - unknown[] - … - `display` object, nullable: An object containing display information for the transaction. The fields in this object are pulled from other parts of the enrichment and surfaced here for convenience. - `name` string: The best name for display. - `categoryName` string, nullable: The best category name for display. - `graphic` string, url, nullable: The best graphic for display. Depending on the data available, this will be either a) the counterparty logo, b) the third party logo, or c) the category icon. - `graphicSource` 'counterparty' | 'third_party' | 'category', nullable: The field from which the `graphic` was sourced. This will be either `counterparty`, `third_party`, or `category`. - `transferInfo` object, nullable: Additional information about transfers. This field is `null` for card transactions. - `direction` 'outgoing' | 'incoming': The transfer direction. - `transferMethod` 'ach' | 'cash' | 'check' | 'intrabank' | 'rtp' | 'unknown' | 'wire': The transfer method. - `transferType` 'external' | 'internal' | 'unknown': The transfer type. "external" indicates that money is being sent to an external counterparty. "internal" indicates that money is being moved between accounts owned by the same entity. - `isAdjustmentOrRefund` boolean: Whether the transfer is an adjustment or refund. - `atmInfo` object, nullable: Additional information about ATM transactions. This field is `null` for other types of transactions. - `sponsorName` string: The name of the sponsor of the ATM involved in the transaction. - `ownerName` string: The name of the owner of the ATM involved in the transaction. - `isAccountVerification` boolean, nullable: Whether the transfer is an account verification. Currently only available for transfers. - `isPeerToPeer` boolean, nullable: Whether the transaction is a peer-to-peer transaction. Currently only available for transfers. - `isDigitalWallet` boolean, nullable: Whether the transaction involves a digital wallet. Currently only available for transfers. - `transactionId` string: Your ID representing this transaction. This ID exactly matches the transactionId you provided in your enrichment request. - `riskInsights` object, nullable: Risk insights provide visibility into the potential risk of a transaction and the merchants involved. Premium Spade Signal available depending on your product package. - `irregularWebPresenceDetected` boolean, nullable: Has engaged in deceptive online practices or has irregular website structure or content. - `negativeOnlineSentiment` boolean, nullable: Negative online consumer feedback associated with the counterparty. - `highRiskEntity` boolean, nullable: The counterparty is known to engage in fraudulent practices. - `riskyIndustry` boolean, nullable: Industry is correlated with increased disputes (based on Spade industries). - `cardAcceptanceHistory` 'extensive' | 'established' | 'stable' | 'limited' | 'very_limited' | 'null', nullable: Counterparties with lower levels of card acceptance history have a higher likelihood of chargebacks or fraudulent activity. - `counterparty` object[]: An array of counterparties matched to the transaction, ordered by descending match score. - `location` object[]: An array of locations matched to the transaction (and associated with this counterparty). Can currently contain only one location. This is a premium Spade field available depending on your product package. - `id` string, uuid, nullable: A unique identifier for this location. - `address` string, nullable: Street number, name, and any secondary address information. - `addressLine1` string, nullable: Street number and name. - `addressLine2` string, nullable: Secondary address information. - `city` string, nullable - `region` string, nullable: Region code. Typically a two-letter code for US states, but may vary for international regions. - `country` string, nullable: Three letter country code. - `postalCode` string, nullable: Location postal code or zip code. - `latitude` number, nullable: Location latitude. - `longitude` number, nullable: Location longitude. - `phoneNumber` string, nullable: Location phone number. This is a premium Spade field available depending on your product package. - `matchScore` number, nullable: The matchScore predicts how well a transaction matches a Location in our records. If no Location was found, the matchScore is set to null. Scores range between 0.00 and 100.0. Generally, a higher matchScore indicates a better match between a transaction and a Location. This is a premium Spade field available depending on your product package. - `possibleCounterpartyAlternate` object, nullable: The possible alternate counterparty object represents a counterparty that may be matched to this transaction in other enrichment requests. Premium Spade Field available depending on your product package. - `id` string, uuid: The ID of the alternate counterparty. - `similarity` number: The similarity score indicates how closely this alternate counterparty matches the main counterparty. The score is a value between 0.0 and 100.0, where 100.0 is an exact match. - `id` string, uuid, nullable: A unique identifier for this counterparty, regardless of specific location. - `name` string, nullable: Counterparty name. - `legalName` string, nullable: Counterparty legal name. This is a premium Spade field available depending on your product package. - `industry` IndustryCategoryLevel[]: Array with increasingly specific category information. - `id` string - `name` string - `icon` string, url, nullable: Category icon. - `matchScore` number, nullable: The matchScore predicts how well a transaction matches a Counterparty in our records. If no Counterparty was found, the matchScore is set to null. Otherwise, scores range between 50.00 and 100.00. We filter out results below this range to make sure that only high quality matches are returned. Generally, the higher the matchScore is the better the match between a transaction and a Counterparty. When multiple Counterparties match a transaction, matches are returned in decreasing order of matchScore. This is a premium Spade field available depending on your product package. - `logo` string, url, nullable: Counterparty logo. This is a premium Spade field available depending on your product package. - `phoneNumber` string, nullable: Counterparty phone number. This is a premium Spade field available depending on your product package. - `website` string, url, nullable: Counterparty website. This is a premium Spade field available depending on your product package. - `enrichmentId` string, uuid: Our ID representing the enrichment, not to be confused with your provided `transactionId`. - `mobileAppInfo` MobileAppInfo, nullable: The mobile app information for the transaction. This object is only non-null if the transaction was matched to a mobile app. This is a premium Spade field available depending on your product package. - `id` string, uuid: A unique identifier for this mobile app. - `name` string: The name of the mobile app. - `url` string, url, nullable: The URL of the mobile app in the app store. - `logo` string, url, nullable: The URL of the mobile app's logo. - `developerName` string: The name of the developer of the mobile app. - `developerId` string, uuid: The ID of the developer of the mobile app. - `category` 'Auto and Transportation' | 'Creative and Design' | 'Education and Parenting' | 'Entertainment and Media' | 'Finance and Business' | 'Games' | 'Health and Lifestyle' | 'Shopping and Marketplaces' | 'Social and Communication' | 'Travel and Events' | 'Utility and Tools': The category of the mobile app. - `hasGamblingOrRewards` boolean: Whether the mobile app has gambling or cash rewards. - `hasSimulatedGambling` boolean: Whether the mobile app has simulated gambling. - `ageRating` 'Children' | 'Teen' | 'Adult' | 'Unknown': The age rating of the mobile app. - `customAttributes` CustomAttributesResponseField: A dictionary containing the custom attributes that were included in the enrichment request (if any). - `actions` TriggeredActionResponse[], nullable: An array of triggered actions, or `null` if no triggers matched. This field is only present if your integration has the actions feature enabled. When a transaction matches one or more registered triggers, this array contains the action details including your custom `action` data. Multiple matches are possible when triggers are registered at different scopes (account, program, user, card). - `id` string: Your unique identifier for the matched trigger (as provided during registration). - `type` 'merchant_trigger' | 'category_trigger': The type of trigger that matched — `merchant_trigger` for merchant-based triggers, `category_trigger` for category-based triggers. - `action` object: The custom action data you provided during registration for this trigger. For `BLOCK` and `ALLOW_ONLY` action types, an `authRecommendation` field is automatically added: - `BLOCK` triggers: `authRecommendation` is set to `"BLOCK"`. - `ALLOW_ONLY` triggers that match: `authRecommendation` is set to `"ALLOW"`. - `ALLOW_ONLY` triggers that do not match (inverse semantics): `authRecommendation` is set to `"BLOCK"`. - `authRecommendation` 'ALLOW' | 'BLOCK': Authorization recommendation injected for `BLOCK` and `ALLOW_ONLY` action types. Not present for other action types. - `scope` 'account' | 'program' | 'user' | 'card': The scope at which this trigger was registered (account, program, user, or card). - `source` 'counterparty' | 'third_party' | 'null', nullable: Indicates whether the action was triggered by the matched counterparty or third party. This field will be set to `null` when an `ALLOW_ONLY` action trigger was set up whose condition the current transaction did not meet. The `authRecommendation` in this case will be `BLOCK`. - `categoryId` string: The Spade category ID that matched this trigger. Only present when `type` is `category_trigger`. - `categoryName` string: The name of the Spade category that matched this trigger. Only present when `type` is `category_trigger`. - `statusCode` integer: The HTTP status code for this element of the response array. - `errors` object: This field is only present if the status code is not 200. An object containing error descriptions for this element of the response array. ## Other responses - `400`: Invalid input - `403`: Unauthorized - `500`: Unexpected Error --- [API](https://skmtc.dev/spade/apis/spade-api.md) - [All operations](https://skmtc.dev/spade/apis/spade-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spade/apis/spade-api/revisions/a37c626f84de?raw)