List MID InsightsImprove this page

The List MID Insights endpoint provides programmatic clarity into the health, status, and validation details of your onboarded Merchant Identification Numbers (MIDs) across card networks. As part of our Phase 2 rollout, this endpoint enables advanced programmatic querying to proactively monitor your transaction ingestion pipelines.

Overview

The List MID Insights endpoint allows you to query and monitor the full lifecycle of your onboarded MIDs. Key capabilities include:

🔍 Health monitoring: Track the current status of every onboarded MID across card networks
📊 Network activation details: View scheme-specific identifiers (Visa, Mastercard, Amex) for each MID
🔗 Transaction linkage: Identify the first and last transactions seen on each MID for your program
📅 Date filtering: Filter MID insights by last seen transaction date ranges
🏷️ Origin tracing: Understand how each MID was discovered or sourced
📄 Paginated results: Efficiently retrieve large sets of MID insights using cursor-based pagination

Availability & Requirements

⚠️ Important Eligibility Notice: This endpoint is exclusively available to Premium Tier customers.

Activation: This feature is not enabled by default. It is only available to Premium Tier clients. To unlock access for your program, please reach out directly to your assigned Customer Success Manager (CSM).
Dashboard Support: This release represents the programmatic API phase. Full self-service visualization and dashboard functionality for MID Insights will be available in the Fidel Dashboard by August 2026.

API Endpoints

List MID Insights

Retrieve a paginated list of MID insights for a program, including health, status, and validation details across card networks.

Endpoint: GET /programs/{programId}/mid-insights | API Reference

Request Parameters

Headers

Header Name	Type	Description	Required
`Authorization`	String	Your live secret API key (Bearer SK_KEY).	Yes
`Fidel-Version`	String	The targeted API version (e.g., `2024-11-25`).	Yes

Path Parameters

Parameter	Type	Description	Required
`programId`	uuid	The id of the program.	Yes

Query Parameters

Parameter	Type	Description	Required
`brandId`	uuid	Brand unique identifier.	No
`id`	uuid	Mid insight unique identifier.	No
`limit`	string	Numerical digit from 1 up to 100.	No
`locationId`	uuid	Location unique identifier.	No
`midId`	uuid	Merchant unique identifier.	No
`lastSeenTransactionDateFrom`	date, date-time	Filter MID insights with a last seen transaction date on or after this value for your program. Accepts ISO 8601 date or date-time format.	No
`lastSeenTransactionDateTo`	date, date-time	Filter MID insights with a last seen transaction date on or before this value for your program. Accepts ISO 8601 date or date-time format.	No
`origin`	enum	Filters MID insights by how the MID was sourced or discovered for your program. Accepted values: `address-match`, `brand-provided-mid`, `customer-provided-mid`, `manual-mid-lookup`, `missing-transaction-lookup`, `processor-provided-mid`, `system-mid-lookup`, `system-provided-mid`, `third-party-provided-mid`.	No
`seNumber`	string	The Amex Service Establishment number (Merchant ID). Must be exactly 10 numeric digits.	No
`mcAcquiringMid`	string	The Mastercard Acquiring Merchant ID.	No
`mcLocationId`	string	The Mastercard Location ID.	No
`visaAcquiringMid`	string	The Visa Acquiring Merchant ID (CAID).	No
`visaBin`	string	The Visa Bank Identification Number.	No
`vmid`	string	The Visa Merchant ID. Must be 6 to 8 numeric digits.	No
`vsid`	string	The Visa Store ID.	No
`select`	enum	Select specific response mode. Use `count` to return only the total count without items.	No
`sort`	enum	Field to sort results by. Accepted values: `created`, `onboardedAt`, `offboardedAt`, `lastSeenTransactionDate`, `sourcedAt`, `eventTs`, `updated`, `origin`, `status`, `scheme`.	No
`order`	enum	Sort order direction. Accepted values: `asc`, `desc`.	No
`start`	string	Base64-encoded pagination cursor for the next page of results. Obtained from the `last` field of a previous response.	No
`status`	enum	Filter by MID insight status. Accepted values: `onboarded`, `offboarded`.	No

Response Object

The endpoint returns a JSON object containing a paginated array of MID insights. Each entry details network activation statuses and diagnostic messages to help you resolve network mismatches quickly.

The top-level response contains:

count — Total number of matching MID insights
items — Array of MID insight records (see fields below)
last — Pagination cursor for the next page of results (pass as start in your next request)

Field	Type	Required	Description
`brandId`	string	Required	The brand (merchant) this MID insight belongs to.
`cardNetworkMerchantName`	string	Optional	Merchant name as registered with the card network.
`created`	string	Required	Timestamp when the MID insight record was created.
`id`	string	Required	Unique identifier of this MID insight record.
`locationId`	string	Required	The location this MID is associated with.
`mcAcquiringMid`	string	Optional	Mastercard acquiring MID.
`mcLocationId`	string	Optional	Mastercard location identifier.
`midId`	string	Required	The MID record this insight is linked to.
`midRequestId`	string	Optional	The MID request that originated this MID, if applicable.
`offboardedAt`	string	Optional	Timestamp when the MID was offboarded from the card network.
`onboardedAt`	string	Optional	Timestamp when the MID was onboarded to the card network.
`origin`	string	Optional	How the MID was sourced (e.g. manual, automatic). See MID Origin Types.
`programId`	string	Required	The program this MID insight belongs to.
`seNumber`	string	Optional	Service Establishment number (Amex merchant identifier).
`sourcedAt`	string	Optional	Timestamp when the MID was initially sourced or discovered.
`scheme`	string	Required	Card network scheme (e.g. `visa`, `mastercard`, `amex`).
`status`	string	Required	Current status of the MID insight (e.g. `onboarded`, `offboarded`, `sourced`).
`visaAcquiringMid`	string	Optional	Visa acquiring MID.
`visaBin`	string	Optional	Visa Bank Identification Number.
`vmid`	string	Optional	Visa Merchant ID (assigned by Visa).
`vsid`	string	Optional	Visa Store ID.
`lastSeenTransactionDate`	string	Optional	Date of the most recent transaction seen on this MID for your program.
`lastSeenTransactionId`	string	Optional	ID of the most recent transaction seen on this MID for your program.
`firstTransactionClearingId`	string	Optional	ID of the first clearing transaction on this MID.
`firstTransactionAuthId`	string	Optional	ID of the first authorisation transaction on this MID for your program.

MID Origin Types

The origin field describes how each MID was discovered or sourced for a location.

Origin	Response Field Value	Description
Address match	`address-match`	MID was identified as part of searching the address automatically on the card network and matching MIDs based on brand name and address details provided by the client on location level.
Brand provided	`brand-provided-mid`	The MID was provided directly by the brand or merchant.
Customer provided	`customer-provided-mid`	The client added the MID to the location or to a MID request for onboarding.
Manual lookup	`manual-mid-lookup`	Fidel support manually looked up the card network MID for an onboarded location through the card networks.
Missing transaction lookup	`missing-transaction-lookup`	A transaction was made at an onboarded location and the MID was identified from the transaction data (most accurate).
Processor provided	`processor-provided-mid`	The MID was provided by the payment processor or acquirer (e.g., Stripe, Adyen).
System MID lookup	`system-mid-lookup`	A Mastercard CAID (Card Acceptor ID) triggered the system to look up the Visa MIDs/CAIDs through the Mastercard CAID.
System provided	`system-provided-mid`	The MID was automatically identified and provided by the Fidel system.
Third-party provided	`third-party-provided-mid`	A third-party service (e.g., Incubit) sourced the MID for the location.

Scheme-Specific Fields

Depending on the card network (scheme) of a MID insight, different identifier fields will be populated in the response.

Field	Scheme	Description
`seNumber`	Amex	Amex MID number (Service Establishment number).
`mcAcquiringMid`	Mastercard	Mastercard Acquiring Merchant ID.
`mcLocationId`	Mastercard	Mastercard Location ID.
`visaAcquiringMid`	Visa	Visa Acquiring Merchant ID (CAID).
`visaBin`	Visa	Visa Bank Identification Number.
`vmid`	Visa	Visa Merchant ID (assigned by Visa).
`vsid`	Visa	Visa Store ID.
`cardNetworkMerchantName`	All schemes	Merchant name as registered with the card network at the scheme for this MID.
`lastSeenTransactionDate`	All schemes	Date of the last transaction tracked by Fidel for your program on this MID.
`lastSeenTransactionId`	All schemes	Last tracked Fidel transaction ID on this MID for your program (confirms whether the MID is still active).
`firstTransactionClearingId`	All schemes	First Fidel clearing transaction ID tracked on this MID.
`firstTransactionAuthId`	All schemes	First Fidel authorisation transaction ID tracked on this MID for your program.

Implementation Example

123456
curl --request GET \
  --url 'https://api.fidel.uk/v1/programs/programId/mid-insights?sort=created&order=desc' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer clsk_live_...' \
  --header 'Fidel-Version: 2024-11-25'

Error Codes

HTTP Status	Error Code	Description
`401`	`unauthorized`	The API key provided is invalid or expired.
`403`	`tier_restricted`	Feature locked. Your account is not configured for Premium tier access.
`404`	`resource_not_found`	The requested `programId` could not be found.
`429`	`rate_limit_exceeded`	Request volume limits exceeded. Implement request back-off mechanisms.

Documentation