# 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**.

### Find partner records

Use this endpoint to retrieve partner records with pagination and filters.

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

Use this endpoint to retrieve a specific partner record.

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

Use partner lookup before creating or updating records to confirm the correct parent partner ID and target hierarchy branch.

### Add a partner

Use this endpoint to create 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 sub-partner 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`   | No additional partner hierarchy records are required |

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.

### Add partner request body

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

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

### Add partner fields

| Field                  | Required | Description                                                                                                              |
| ---------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------ |
| `partnerType`          |      Yes | Partner type to create. Supported advanced hierarchy values are `iso`, `agent`, `corporateEntity`, and `masterMerchant`. |
| `name`                 |      Yes | Partner display name.                                                                                                    |
| `feeInfo`              |      Yes | Partner fee configuration.                                                                                               |
| `tenderTypes`          |      Yes | Tender types enabled for the partner.                                                                                    |
| `email`                |       No | Partner contact email.                                                                                                   |
| `phoneNumber`          |       No | Partner contact phone number.                                                                                            |
| `maxTransactionAmount` |       No | Optional maximum transaction amount for this partner.                                                                    |

### Add another Agent branch

If Bead has instructed you to create another Agent under an existing ISO, create the Agent as a child partner of the ISO.

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

When the Agent is added, Bead automatically creates the Corporate Entity and Master Merchant records under that Agent branch.

### Edit a partner

Use this endpoint to update an existing partner.

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

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

### Edit partner request body

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

### Edit partner fields

| Field                  | Required | Description                                           |
| ---------------------- | -------: | ----------------------------------------------------- |
| `name`                 |      Yes | Partner display name.                                 |
| `feeInfo`              |      Yes | Partner fee configuration.                            |
| `tenderTypes`          |      Yes | Tender types enabled for the partner.                 |
| `email`                |       No | Partner contact email.                                |
| `phoneNumber`          |       No | Partner contact phone number.                         |
| `maxTransactionAmount` |       No | Optional maximum transaction amount for this partner. |

### 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.

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


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.