# Use Cases
source: https://developer.mastercard.com/match/documentation/use-cases/index.md

## Termination Inquiry Request Scenario {#termination-inquiry-request-scenario}

An Authorized User wants to evaluate the risk of onboarding a new merchant. The acquirer collects the following information from the merchant to be onboarded.   

1) Merchant's business name, address and contact details  

2) Merchant's principal owner's name, address, contact details  

3) Merchant website details like URL

The Authorized User submits a Termination Inquiry API request to MATCH Pro to find out if the merchant has been terminated by another Authorized User in the past five years. MATCH Pro compares the data provided by the Authorized User with MATCH Merchant records in the database and sends a response back. The response includes an Inquiry Reference number for future reference.

Diagram seq-TerminationInquiry
API Reference: `POST /termination-inquiries`

## Termination Inquiry History Request Scenario {#termination-inquiry-history-request-scenario}

The Authorized User wants to view the inquiry results of inquiries made in the past 365 days. In this situation, the Authorized User can use the Termination Inquiry History API to fetch their past inquiry data using the Inquiry Reference Number. MATCH Pro persists all termination inquiry results in its database. Match Service uses the Inquiry reference number sent in the Termination Inquiry History API to retrieve the Inquiry results saved in its Database. There is no limit to the number of times, acquirers can retrieve historical search results using this API.


Diagram seq-TerminationInquiryHistory


API Reference: `GET /termination-inquiries/{inquiry_ref_num}`

<br />

## Add Terminated Merchant Scenario {#add-terminated-merchant-scenario}

An Authorized User terminates a merchant agreement with a merchant in accordance with the standards listed in the Security Rules and Procedures. The Authorized User can use this request to add the MATCH merchant to the MATCH Pro database using the Add Terminated Merchant request. Authorized Users must add the merchant in MATCH using the Member ID/ICA number under which the merchant's activity was conducted. Acquirers must provide two digits numeric [reason code](https://developer.mastercard.com/match/documentation/index.md#overview) indicating why the relationship was terminated.


Diagram seq-AddTerminatedMerchant


API Reference: `POST /merchants/add-merchants`

<br />

## Acquirer Contact Request Scenario {#acquirer-contact-request-scenario}

While onboarding a new merchant, an Authorized User A, finds out that a MATCH merchant was added to MATCH Pro by Authorized User B. Authorized User A wants to investigate further before onboarding the MATCH Merchant and uses the Acquirer Contact API to get contact details of Authorized User B.


Diagram seq-AcquirerContacts


API Reference: `POST /contact-details`

<br />

## Retroactive Inquiry Request Scenario {#retroactive-inquiry-request-scenario}

Authorized User A performs an inquiry for a merchant "X Inc" and doesn't find a match. MATCH Pro will keep searching for merchant "X Inc" in the database for the next 360 days. Suppose within the next 360 days, another Authorized User B adds a terminated merchant "X Inc", who matches the search parameters used by Authorized User A. MATCH Pro will send an email notification to Authorized User A indicating that there is a possible retroactive inquiry match. Authorized Users submit the retroactive inquiry list request to retrieve a list of retroactive inquiry matches from the past 30 days. This list of retroactive inquiry matches includes an Inquiry Reference Number, which the Authorized User can submit in the Retroactive Details Request to get more details of the possible merchant match.  


Note: Each day, MATCH Pro automatically conducts a retroactive inquiry search on every merchant to which the acquirer has submitted an inquiry. MATCH Pro automatically deletes retroactive inquiry matches after thirty days. Therefore, Authorized Users should view retroactive inquiries every day to be sure that they do not miss a possible match.   

<br />


Diagram seq-RetroactiveInquiry


API Reference: `POST /retros/retro-lists`

<br />

## Retroactive Inquiry Details Request Scenario {#retroactive-inquiry-details-request-scenario}

The Authorized User uses the Retroactive Inquiry API to retrieve a list of Retroactive Inquiry Reference Numbers which matched the acquirer's previous termination inquiries. The Authorized User then uses Retroactive Inquiry Details API to fetch details of the possible retroactive inquiry matches.

Diagram seq-RetroactiveInquiryDetails
API Reference: `GET /retros/retro-inquiry-details/{inquiry_ref_num}`

## Countries Request Scenario {#countries-request-scenario}

While adding or performing an inquiry on a MATCH merchant, the 3-letter ISO country code is required. The Authorized User uses the Countries API to retrieve a list of ISO countries codes that can be submitted in the Country field of the MATCH merchant address or Principal Owner(s) address in the Termination Inquiry Request or the Add Terminated Merchant Request.

Diagram seq-Countries
API Reference: `GET /countries`

## States Request Scenario {#states-request-scenario}

While adding or performing an inquiry on a MATCH Merchant, the 2-letter state or province is required for US and Canada merchants. The Authorized User uses the Countries API to retrieve list of ISO countries codes. The Authorized User then uses States API to fetch the list of states details for specific country that can be submitted in the State/Province field of the MATCH merchant address or Principal Owner(s) address in the Termination Inquiry Request or the Add Terminated Merchant Request.

Diagram seq-States
API Reference: `GET /countries/{country_code}/states`

## Cities Request Scenario {#cities-request-scenario}

While adding or performing an inquiry on a MATCH Merchant, the city is required. The Authorized User submits the Cities API request for the relevant country to fetch the list of cities names for the relevant country or for the relevant country and one of its states. If the relevant city is not returned in the City API for the specified country, users must submit "IsOtherCity: Y" and the relevant city in the City field of the MATCH Merchant address or the Principal Owner address in the Termination Inquiry Request or the Add Merchant Request.

Diagram seq-Cities
API Reference: `GET /countries/{country_code}/cities`