> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/verify-business/discover-connections/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Discover connections > Discover businesses connected to your customers through shared people, addresses, and businesses When Middesk verifies a business, it analyzes the people, addresses, and business data associated with that business to discover connections to other businesses in its identity graph. These connections surface other businesses that may share common ownership, management, or operating locations, enabling more comprehensive due diligence without manual research. > **Getting started** > > Middesk automatically discovers connections when you create a business. See the [quickstart](/quickstart) for a basic introduction to verifying a business. ## How Middesk discovers connections Middesk maintains an identity graph built from Secretary of State registrations, business filings, and other public records. When Middesk verifies a business, it compares the business's people, addresses, and data against this graph to find other businesses that share those attributes. A shared officer appearing on two businesses, an overlapping registered address, or a common business relationship each represent a connection worth investigating. Each discovered connection includes a confidence score between 0 and 1 that reflects the overall strength of the connection. The score increases when multiple attributes overlap. Middesk returns results in descending order by confidence, so the strongest connections appear first. > **Note** > > The API returns up to 250 connections per business and omits any beyond that limit. ## Understanding connections Every connection includes the specific connecting elements that link it to the ordered business. There are three connecting element types: * **Connecting people.** Individuals found on both the ordered business and the connected business. Each person includes their name, titles (for example, "CEO" or "Registered Agent"), and the sources where the connection was found, such as Secretary of State registrations. * **Connecting addresses.** Physical addresses shared between both businesses. Each address includes labels (for example, "primary") and the sources where the address was found. A shared registered office or principal address suggests an operational link between the two businesses. * **Connecting businesses.** Businesses found in authoritative records that establish a link between the ordered and connected business. This happens in three ways: * **Outbound reference.** The ordered business's own records name the connected business. * **Inbound reference.** The connected business's records name the ordered business. * **Shared reference.** Both the ordered business and the connected business name the same third business in their records. > **Note** > > Middesk populates the `sources` array from the ordered business's own authoritative records. Inbound references have an empty `sources` array because the evidence lives on the connected business's records, not the ordered business's. To access sources from the connecting business, order a report for the connected business. See [Order a report from a connection](#order-a-report-from-a-connection) below. ## Confidence scoring The `confidence` field is a float between 0 and 1 that represents how strongly two businesses are connected. Higher values indicate more overlapping data points across the connection types described above. The score combines weighted signals: * **High confidence (0.90 or above).** Multiple connecting elements overlap. For example, a shared person plus a shared address, or an outbound or inbound business reference combined with a shared person or address. * **Medium confidence.** A single strong signal is present. For example, a shared person alone, or a direct business reference alone (outbound or inbound, where one business names the other in authoritative records). * **Lower confidence.** A shared address alone, particularly when the address is high-frequency (PO boxes, registered agent offices, or coworking addresses). * **Lowest confidence.** Only a shared third-party reference, with no overlapping people or addresses. This pattern is common when both businesses happen to use the same registered agent or share a generic service provider, which often doesn't indicate a real operational link. Use the confidence score to prioritize which connections to investigate first. Connections with high confidence are strong leads for further diligence, while lower-confidence connections may warrant manual review. ## How to discover connections #### Create or retrieve a business To discover connections, first create a new business or retrieve an existing verified business. **`curl`** ```bash title="curl" curl -X POST https://api.middesk.com/v1/businesses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corporation", "addresses": [ { "address_line1": "123 Main Street", "city": "San Francisco", "state": "CA", "postal_code": "94105" } ], "orders": [ { "product": "business_verification_verify" } ] }' ``` Wait for the `business.updated` webhook indicating verification is complete. Set up [webhooks](/build/webhooks) to receive notifications. #### List connections Once Middesk verifies the business, retrieve its connections. The API paginates results and orders them by confidence score. **`curl`** ```bash title="curl" curl https://api.middesk.com/v1/businesses/{business_id}/connections \ -H "Authorization: Bearer YOUR_API_KEY" ``` Pass `page` and `per_page` query parameters to paginate through results. #### Review connections Each connection in the response includes the connecting people, addresses, and businesses that link it to the ordered business, along with a confidence score. **`Example response`** ```json title="Example response" { "object": "list", "data": [ { "object": "connection", "id": "00000000-0000-0000-0000-000000000001", "name": "Acme Holdings LLC", "confidence": 0.96, "connected_business_id": null, "connecting_people": [ { "name": "John Doe", "titles": ["CEO"], "sources": [ { "id": "00000000-0000-0000-0000-000000000002", "type": "sos_registration", "metadata": { "state": "IL", "file_number": "12345" } } ] } ], "connecting_addresses": [ { "full_address": "123 Main St, Springfield, IL 62701", "labels": ["primary"], "sources": [ { "id": "00000000-0000-0000-0000-000000000002", "type": "sos_registration", "metadata": { "state": "IL", "file_number": "12345" } } ] } ], "connecting_businesses": [ { "name": "Acme Holdings LLC", "titles": ["MANAGER"], "sources": [ { "id": "00000000-0000-0000-0000-000000000002", "type": "sos_registration", "metadata": { "state": "IL", "file_number": "12345" } } ] }, { "name": "Acme Corporation", "titles": [], "sources": [] }, { "name": "National Registered Agents Inc", "titles": ["REGISTERED AGENT"], "sources": [ { "id": "00000000-0000-0000-0000-000000000002", "type": "sos_registration", "metadata": { "state": "IL", "file_number": "12345" } } ] } ] } ], "has_more": false, "total_count": 1 } ``` In this example, "Acme Holdings LLC" shares a person (John Doe, listed as CEO), a primary address, a registered agent, and is also named as its manager on the ordered business's SOS filing. Together, these signals produce a high confidence score of 0.96. The `connected_business_id` is `null` because you haven't ordered a report on this connection yet. The `connecting_businesses` array shows all three reference types: an outbound reference where the ordered business's own SOS filing names "Acme Holdings LLC" as its owner (sources populated); an inbound reference where "Acme Holdings LLC"'s filing names "Acme Corporation" (sources and titles empty because the evidence lives on the connected business's records, not the ordered business's); and a shared reference to "National Registered Agents Inc", a registered agent company that appears on both businesses' filings (sources populated). #### Order a report from a connection To investigate a connection further, create a new business using the connection `id` as the `connection_id`. This pre-fills the business details from the connection so you don't need to provide them manually. **`curl`** ```bash title="curl" curl -X POST https://api.middesk.com/v1/businesses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "connection_id": "00000000-0000-0000-0000-000000000001", "orders": [{ "product": "business_verification_verify" }] }' ``` When you provide a `connection_id`: * Middesk pre-fills the business name from the connection * Middesk pre-fills the business address from the connection's primary address, unless you explicitly provide addresses * The `connected_business_id` on the original connection updates to link back to the newly created business > **Note** > > You can't combine `connection_id` with `signal_id`. The API allows only one source parameter per request. > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access. > Discover businesses connected to your customers through shared people, addresses, and businesses