# Entity Management

The Entity Management API provides a unified interface for creating and managing the business objects that drive payments in Bead, including partners, merchants, locations, terminals, and related onboarding flows.

Partner → Merchant → Location → Terminal → Payment

It covers the full life cycle, from initial KYB onboarding through routine updates, so you can automate provisioning flows and build self-service dashboards.

Entity Management connects onboarding, provisioning, and ongoing administration across the Bead platform. Use it to move from initial merchant setup through operational management of merchants, locations, and terminals.

#### Why use Entity Management

**Need:** Onboard a new merchant

**How the API helps:** Submit KYB details, provide applicant and `signerInfo` details, and generate a hosted onboarding link that the merchant signer can complete securely.

**Need:** Track onboarding progress

**How the API helps:** Query onboarding status to see missing or invalid fields and determine when a merchant is ready for production.

**Need:** Manage locations

**How the API helps:** Create, rename, or deactivate merchant locations so your reporting and settlement views reflect the merchant’s structure.

**Need:** Manage terminals

**How the API helps:** Create, list, update, disable, or delete devices and set device-level webhooks that drive payment status events.

#### Available sections

**Onboarding**\
Submit KYB details for merchants and partners, provide required applicant and signer information, generate hosted onboarding links, and track status through approval.

**Merchant Management**\
Create, read, update, and deactivate merchants once onboarding is complete. Check merchant status before enabling production traffic.

**Location Management**\
Create and maintain merchant locations, including display names and address details used in receipts, reporting, and settlement.

**Terminal Management**\
Provision and manage terminals, including webhooks and configuration that control how payments are initiated and where events are delivered.

#### Navigation

Use the left navigation to move between sections:

* [Onboarding](https://developers.bead.xyz/onboarding)
* [Merchant Management](https://developers.bead.xyz/entity-management/merchant-management)
* [Location Management](https://developers.bead.xyz/entity-management/location-management)
* [Terminal Management](https://developers.bead.xyz/entity-management/terminal-management)
* [Change Log](https://developers.bead.xyz/changelog)

#### Getting started

1. **Confirm the authentication method for the API flow you are using**
   * Onboarding requests use an API key sent in the `X-Api-Key` header.
   * Other Entity Management endpoints may use the authentication model documented for that endpoint family.
   * See the Authentication page for current authentication guidance.
2. **Create or retrieve the parent objects in order**
   * Partner → Merchant → Location
3. **Provision terminals under the correct location**
   * Each terminal belongs to a location and merchant.
4. **Use the `terminalId` when creating payments**
   * Payments created through the Payments API reference the terminal and merchant defined here, then appear in Reporting and Settlement.


---

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