List request

Sending multiple transactions in one request

Please read the Quick Start guide first to understand the basics of MRS before attempting this.

Overview

After you've made a simple GET request (see Quick Start), you can use a List request to send multiple transactions at once in a single request. This is typically used for the List view of transactions in Bank apps.

Start by constructing a JSON object containing transactions you wish to enrich. Send that JSON object in a POST request to the /api/v3/merchant/list endpoint, and MRS will return JSON containing the merchants found for those transactions.

Request Size

• List requests are recommended to contain 25 or less elements. Requests with higher amounts can be supported. Very long lists might have an impact on response times. Please contact us with any questions on this.

Transaction Ids

• Each transaction must have a unique id property, which is used to identify the transaction in the response.

• The id only has to be unique for this request, and can be any string. You could use the numeric index of the transaction in the transaction array, generate a unique UUID then and there for each transaction, etc.

• This id is required when submitting Crowdsourcing reports, as it is used to identify the transaction within the request. The other parameters for each transaction are the same as the individual /v3/merchant GET request (see Getting Started).

Type

• Typically it's recommended to use restrictive calls for List requests. See Restrictive vs Extended

Example Code

cURL

curl --request POST --url https://regional-snowdrop-domain-goes-here.com/api/v3/merchant/list --header 'Content-Type: application/json' --header 'X-Api-Key: <YOUR-API-KEY>' --data '{ "type": "restrictive", "transactions": [ { "merchant_name": "mcdonalds", "location": "london", "country": "GBR", "id": "1" }, { "merchant_name": "starbucks", "location": "Manchester", "id": "2", "country": "GBR" }, { "merchant_name": "ikea", "location": "Malmo", "id": "3", "country": "GBR" } ] }'

Python

import http.client

conn = http.client.HTTPSConnection("regional-snowdrop-domain-goes-here.com")

payload = "{"type": "restrictive","transactions": [{"merchant_name": "mcdonalds","location": "london","country": "GBR","id": "1"},{"merchant_name": "starbucks","location": "Manchester","id": "2","country": "GBR"},{"merchant_name": "ikea","location": "Malmo","id": "3","country": "GBR"}]}"

headers = { 'Content-Type': "application/json", 'x-api-key': "<YOUR-API-KEY>" }

conn.request("POST", "/api/v3/merchant/list", payload, headers)

res = conn.getresponse() data = res.read()

print(data.decode("utf-8"))

C#

var client = new RestClient("https://regional-snowdrop-domain-goes-here.com/api/v3/merchant/list");

var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json");

request.AddHeader("x-api-key", "<YOUR-API-KEY>");

request.AddParameter("application/json", "{"type": "restrictive","transactions": [{"merchant_name": "mcdonalds","location": "london","country": "GBR","id": "1"},{"merchant_name": "starbucks","location": "Manchester","id": "2","country": "GBR"},{"merchant_name": "ikea","location": "Malmo","id": "3","country": "GBR"}]}", ParameterType.RequestBody);

IRestResponse response = client.Execute(request);

Javascript

const data = JSON.stringify({ "type": "restrictive", "transactions": [ { "merchant_name": "mcdonalds", "location": "london", "country": "GBR", "id": "1" }, { "merchant_name": "starbucks", "location": "Manchester", "id": "2", "country": "GBR" }, { "merchant_name": "ikea", "location": "Malmo", "id": "3", "country": "GBR" } ] });

const xhr = new XMLHttpRequest(); xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () { if (this.readyState === this.DONE) { console.log(this.responseText); } });

xhr.open("POST", "https://regional-snowdrop-domain-goes-here.com/api/v3/merchant/list");

xhr.setRequestHeader("Content-Type", "application/json"); xhr.setRequestHeader("x-api-key", "<YOUR-API-KEY>");

xhr.send(data);

Java

HttpResponse response = Unirest.post("https://regional-snowdrop-domain-goes-here.com/api/v3/merchant/list") .header("Content-Type", "application/json") .header("x-api-key", "<YOUR-API-KEY>") .body("{"type": "restrictive","transactions": [{"merchant_name": "mcdonalds","location": "london","country": "GBR","id": "1"},{"merchant_name": "starbucks","location": "Manchester","id": "2","country": "GBR"},{"merchant_name": "ikea","location": "Malmo","id": "3","country": "GBR"}]") .asString();

The returned response contains the enriched transactions in JSON format:

{
	"1": [
		{
			"name": "McDonald's",
			"website": "https://www.mcdonalds.com",
			"address": "",
			"img": "https://storage.googleapis.com/production-mrs-tm-logos/6273ea24bb09494554c95b90_2x.png",
			"logoImg": "https://storage.googleapis.com/production-mrs-tm-logos/6273ea24bb09494554c95b90_2x.png",
			"categoryImg": "https://storage.googleapis.com/production-mrs-category-logos/6266950140122693b803c7e0/eatingout_2x.png",
			"logoScore": 1,
			"category": "Eating Out",
			"categories": [
				"restaurant"
			],
			"isClearResponse": false,
			"cachePolicy": {
				"name": "MRS",
				"website": "MRS",
				"address": "MRS",
				"img": "MRS",
				"logoImg": "MRS",
				"categoryImg": "MRS",
				"logoScore": "MRS",
				"category": "MRS",
				"categories": "MRS",
				"isClearResponse": "MRS"
			}
		}
	],
	"2": [
		{
			"name": "Starbucks",
			"website": "https://www.starbucks.com",
			"address": "",
			"img": "https://storage.googleapis.com/production-mrs-tm-logos/6273e431bb09494554c93079_2x.png",
			"logoImg": "https://storage.googleapis.com/production-mrs-tm-logos/6273e431bb09494554c93079_2x.png",
			"categoryImg": "https://storage.googleapis.com/production-mrs-category-logos/6266950140122693b803c7e0/eatingout_2x.png",
			"logoScore": 1,
			"category": "Eating Out",
			"categories": [
				"cafe"
			],
			"isClearResponse": false,
			"cachePolicy": {
				"name": "MRS",
				"website": "MRS",
				"address": "MRS",
				"img": "MRS",
				"logoImg": "MRS",
				"categoryImg": "MRS",
				"logoScore": "MRS",
				"category": "MRS",
				"categories": "MRS",
				"isClearResponse": "MRS"
			}
		}
	],
	"3": [
		{
			"name": "IKEA",
			"website": "https://www.ikea.com",
			"address": "",
			"img": "https://storage.googleapis.com/production-mrs-tm-logos/6273e4c1bb09494554c934c8_2x.png",
			"logoImg": "https://storage.googleapis.com/production-mrs-tm-logos/6273e4c1bb09494554c934c8_2x.png",
			"categoryImg": "https://storage.googleapis.com/production-mrs-category-logos/6266950140122693b803c7e0/shopping_2x.png",
			"logoScore": 1,
			"category": "Shopping",
			"categories": [
				"furniture_store"
			],
			"isClearResponse": false,
			"cachePolicy": {
				"name": "MRS",
				"website": "MRS",
				"address": "MRS",
				"img": "MRS",
				"logoImg": "MRS",
				"categoryImg": "MRS",
				"logoScore": "MRS",
				"category": "MRS",
				"categories": "MRS",
				"isClearResponse": "MRS"
			}
		}
	]
}

This is a JSON object containing one property per transaction sent.

The keys of this object are the ID that was provided, previously passed in as the id property in each transaction array element.

For more on the meaning of these fields, consult the OpenAPI Docs .

Remember, the example above is simple, but you should add as many fields as you can for the best results. See Must-Read.

Having problems? Consult Troubleshooting or FAQ.