> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/reference/reporting-boarding/boarding-api/list-merchants/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# List merchants

GET https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants

Retrieve a list of merchants accessible to the authenticated user. Returns merchants where the current user is associated as a sales officer, sales partner, or distributor client.

Reference: https://docs.runpayments.io/reference/reporting-boarding/boarding-api/list-merchants

## Authentication

- `Authorization` header (bearer token, required) — This API uses OAuth 2.0 for authentication.

## Request

### Query parameters

- `limit` (integer, optional) — Maximum number of merchants to return
- `offset` (integer, optional, default: 0) — Number of merchants to skip for pagination (default 0)

## Response

### 200

Merchants retrieved successfully

- `items` (list of MerchantSummary, required) — Array of merchant records
- `hasMore` (boolean, required) — Whether there are more merchants available
- `limit` (integer, required) — The limit parameter used for this request
- `offset` (integer, required) — The offset parameter used for this request
- `count` (integer, required) — Number of merchants returned in this response
- `links` (list of Link, required) — HATEOAS links for pagination and related resources

## Errors

### 400 Bad Request Error

Bad request

- `error` (string, optional) — Error code.
- `error_description` (string, optional) — Detailed error description.

### 401 Unauthorized Error

Unauthorized

- `error` (string, optional) — Error code.
- `error_description` (string, optional) — Detailed error description.

## Types

### MerchantSummary

Summary information for a merchant based on the v_merchant_api view

- `merchant_id` (integer, required) — Unique identifier for the merchant
- `platform` (string, required) — Processing platform (payroc or fiserv)
- `rep_code` (string, required) — Representative code associated with the merchant
- `customer_id` (integer, required) — Customer ID associated with the merchant
- `mid` (string, required) — Merchant ID from the processing platform
- `dba_name` (string, required) — Doing Business As (DBA) name
- `legal_name` (string, required) — Legal business name
- `merchant_status` (string, required) — Current status of the merchant (e.g., new, sent_for_signature, signed, in_underwriting, boarded, live, cancelled, declined, unknown)
- `pended` (integer, required) — Pended status indicator (0 = not pended, 1 = pended)
- `merchant_type_id` (integer, required) — Type identifier for the merchant
- `external_crm_id` (string, optional, nullable) — External CRM system identifier
- `custom_01` (string, optional, nullable) — Custom field for additional merchant data

### Link

HATEOAS link for pagination and resource navigation

- `rel` (string, required) — Relationship type (self, edit, describedby, first, next, prev, last)
- `href` (string, required) — URL for the linked resource

## Examples

**Response**

```json
{
  "items": [
    {
      "merchant_id": 1,
      "platform": "string",
      "rep_code": "string",
      "customer_id": 1,
      "mid": "string",
      "dba_name": "string",
      "legal_name": "string",
      "merchant_status": "string",
      "pended": 1,
      "merchant_type_id": 1,
      "external_crm_id": "string",
      "custom_01": "string"
    }
  ],
  "hasMore": true,
  "limit": 1,
  "offset": 1,
  "count": 1,
  "links": [
    {
      "rel": "string",
      "href": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```