> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/partner-management.md).

# Partner Management

Use Partner Management APIs to create and update partner records. Partner records sit above merchants in the Bead entity model and are used to organize merchant ownership, reporting, permissions, and hierarchy.

Most integrations do not need to create partner hierarchy records directly. Use these APIs only when Bead has confirmed that your integration should manage partner records programmatically.

#### Where Partner Management fits

For most integrations, the entity model is:

```
Partner → Merchant → Location → Terminal → Payment
```

For advanced ISO, reseller, or boarding-platform configurations, the partner level may include an expanded hierarchy:

```
ISO → Agent → Corporate Entity → Master Merchant → Merchant
```

For ISO, Agent, Corporate Entity, and Master Merchant behavior, see [Advanced Partner Hierarchy](/reference-guide/core-concepts/advanced-partner-hierarchy.md).

#### Authentication

All Partner Management endpoints use API key authentication.

| Header      | Value              |
| ----------- | ------------------ |
| `X-Api-Key` | `{adminApiKey}`    |
| `Accept`    | `application/json` |

For write operations, also include:

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

#### List partners

Returns a paginated list of partner records. Use this endpoint to browse the partner hierarchy or locate a specific partner before creating or updating records.

```http
GET /Partners/all
```

**Query parameters**

| Parameter       | Type    | Required | Description                                                                 |
| --------------- | ------- | -------- | --------------------------------------------------------------------------- |
| `PartnerIds`    | array   | No       | Filter by specific partner IDs                                              |
| `IsEnabled`     | boolean | No       | Filter by enabled status                                                    |
| `Type`          | string  | No       | Filter by partner type: `iso`, `agent`, `corporateEntity`, `masterMerchant` |
| `Search`        | string  | No       | Search by name, email, or phone number                                      |
| `SortBy`        | string  | No       | One of: `Created`, `Updated`, `IsEnabled`, `PartnerType`, `Name`            |
| `SortDirection` | string  | No       | `asc` or `desc`                                                             |
| `Page`          | integer | No       | Page number, zero-indexed                                                   |
| `PageSize`      | integer | No       | Results per page, max `100`                                                 |

**Example request**

```bash
curl -X GET "https://api.test.devs.beadpay.io/Partners/all?Page=0&PageSize=50" \
     -H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                      |
| ---- | ------------------------------ |
| 200  | Partners returned successfully |
| 401  | Missing or invalid API key     |
| 403  | Not permitted to list partners |

#### Get a partner

Retrieves a specific partner record.

```http
GET /Partners/{id}
```

`id` is the ID of the partner to retrieve.

**Example request**

```bash
curl -X GET "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                            |
| ---- | ------------------------------------ |
| 200  | Partner returned successfully        |
| 401  | Missing or invalid API key           |
| 403  | Not permitted to access this partner |
| 404  | Partner not found                    |

#### Add a partner

Creates a child partner under an existing parent partner.

```http
POST /Partners/{parentId}/partners
```

`parentId` is the ID of the partner that should own the new partner record.

**Automatic downstream creation**

When a partner is added at the ISO, Agent, or Corporate Entity level, Bead automatically creates the downstream records required to reach a Master Merchant.

| Partner type added | Records Bead automatically creates       |
| ------------------ | ---------------------------------------- |
| `iso`              | Agent, Corporate Entity, Master Merchant |
| `agent`            | Corporate Entity, Master Merchant        |
| `corporateEntity`  | Master Merchant                          |
| `masterMerchant`   | None                                     |

Create the highest-level partner record Bead instructed you to create, then use the created hierarchy to identify the downstream Master Merchant record. Do not manually recreate the downstream hierarchy unless Bead has specifically instructed you to do so.

**Request body**

```json
{
  "partnerType": "iso",
  "name": "Acme Payments",
  "email": "operations@example.com",
  "phoneNumber": "+15555550100",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}
```

In this example, adding `Acme Payments` as an ISO creates the required downstream Agent, Corporate Entity, and Master Merchant records automatically.

**Request fields**

| Field                  | Type   | Required | Description                                                            |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `partnerType`          | string | Yes      | Type to create: `iso`, `agent`, `corporateEntity`, or `masterMerchant` |
| `name`                 | string | Yes      | Partner display name. Max 256 characters                               |
| `feeInfo`              | object | Yes      | Partner fee configuration                                              |
| `tenderTypes`          | array  | Yes      | Tender types enabled for the partner                                   |
| `email`                | string | No       | Partner contact email                                                  |
| `phoneNumber`          | string | No       | Partner contact phone number                                           |
| `maxTransactionAmount` | number | No       | Maximum transaction amount for this partner                            |

Note: `root` may appear as a `partnerType` value in read responses. It cannot be used when creating a partner.

**Example request**

```bash
curl -X POST "https://api.test.devs.beadpay.io/Partners/{parentId}/partners" \
     -H "X-Api-Key: {adminApiKey}" \
     -H "Content-Type: application/json" \
     -d '{
       "partnerType": "iso",
       "name": "Acme Payments",
       "email": "operations@example.com",
       "phoneNumber": "+15555550100",
       "feeInfo": {
         "crypto": { "feeFactor": 0, "fixedFee": 0 },
         "card": null
       },
       "tenderTypes": ["usdcBase", "bitcoin"],
       "maxTransactionAmount": 10000
     }'
```

**Response codes**

| Code | Condition                                           |
| ---- | --------------------------------------------------- |
| 200  | Partner created successfully                        |
| 201  | Partner created successfully                        |
| 202  | Creation accepted for processing                    |
| 400  | Invalid fields or validation error                  |
| 401  | Missing or invalid API key                          |
| 403  | Not permitted to create a partner under this parent |
| 409  | Conflict — duplicate or constraint violation        |

#### Add another Agent branch

If Bead has instructed you to create an additional Agent under an existing ISO, create the Agent as a child partner of the ISO. Bead automatically creates the Corporate Entity and Master Merchant records under that Agent branch.

```json
{
  "partnerType": "agent",
  "name": "Acme Payments Agent Office 1",
  "email": "operations@example.com",
  "phoneNumber": "+15555550100",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}
```

#### Edit a partner

Updates an existing partner record.

```http
PUT /Partners/{id}
```

`id` is the ID of the partner to update.

**Request body**

```json
{
  "name": "Acme Payments Agent Office 1",
  "email": "operations@example.com",
  "phoneNumber": "+15555550100",
  "feeInfo": {
    "crypto": {
      "feeFactor": 0,
      "fixedFee": 0
    },
    "card": null
  },
  "tenderTypes": ["usdcBase", "bitcoin"],
  "maxTransactionAmount": 10000
}
```

**Request fields**

| Field                  | Type   | Required | Description                                 |
| ---------------------- | ------ | -------- | ------------------------------------------- |
| `name`                 | string | Yes      | Partner display name. Max 256 characters    |
| `feeInfo`              | object | Yes      | Partner fee configuration                   |
| `tenderTypes`          | array  | Yes      | Tender types enabled for the partner        |
| `email`                | string | No       | Partner contact email                       |
| `phoneNumber`          | string | No       | Partner contact phone number                |
| `maxTransactionAmount` | number | No       | Maximum transaction amount for this partner |

**Example request**

```bash
curl -X PUT "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Acme Payments Agent Office 1",
       "email": "operations@example.com",
       "phoneNumber": "+15555550100",
       "feeInfo": {
         "crypto": { "feeFactor": 0, "fixedFee": 0 },
         "card": null
       },
       "tenderTypes": ["usdcBase", "bitcoin"],
       "maxTransactionAmount": 10000
     }'
```

**Response codes**

| Code | Condition                                    |
| ---- | -------------------------------------------- |
| 200  | Partner updated successfully                 |
| 202  | Update accepted for processing               |
| 204  | Update completed, no response body           |
| 400  | Invalid fields or validation error           |
| 401  | Missing or invalid API key                   |
| 403  | Not permitted to update this partner         |
| 404  | Partner not found                            |
| 409  | Conflict — duplicate or constraint violation |

#### Delete a partner

Removes a partner record.

```http
DELETE /Partners/{id}
```

`id` is the ID of the partner to delete.

**Example request**

```bash
curl -X DELETE "https://api.test.devs.beadpay.io/Partners/{partnerId}" \
     -H "X-Api-Key: {adminApiKey}"
```

**Response codes**

| Code | Condition                                  |
| ---- | ------------------------------------------ |
| 204  | Partner deleted successfully               |
| 400  | Invalid request or business rule violation |
| 401  | Missing or invalid API key                 |
| 403  | Not permitted to delete this partner       |
| 404  | Partner not found                          |

#### Notes

Partner creation and updates can affect downstream merchant ownership, reporting, permissions, tender availability, and which Master Merchant a merchant should be boarded under. Before adding or editing partner records, confirm the intended parent partner ID and target hierarchy branch with Bead.

#### Related pages

* [Advanced Partner Hierarchy](/reference-guide/core-concepts/advanced-partner-hierarchy.md)
* [Merchant Management](/entity-management/merchant-management.md)
* [List Merchants](/entity-management/merchant-management/list-merchants.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/entity-management/partner-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.