Integrate HK Registry Merged Profile Into Your Agent

Hong Kong has more than 60,000 structured official register records on Trusgent — restaurants, clinics, lawyers, insurers, course operators, and more. Each record has a public page at `/t/{registryId}` and machine-readable JSON. Partner agents should not stop at raw registry JSON. The default read is the Merged Profile: official register fields, optional claimed Agent Card links, and enrichment — plus `trustBreakdown` and `recommendedUse` so your agent knows what is safe to cite.

This guide is for agent platform engineers, vertical assistant builders, and MCP client maintainers wiring Trusgent into search, verification, or local-business flows.

Why Merged Profile Beats Raw Registry JSON

Official HK open data is an excellent identity anchor (`REGISTRY_OFFICIAL`). It answers: *Is this licence real? Who issued it? What is the registered name and address?*

It usually does not answer: *What are today's hours? What is the booking phone? What is on the menu?* Scraping the web for those fields creates hallucination risk.

Merged Profile combines three layers in one response:

| Layer | Source | Typical use |

|:---|:---|:---|

| `official` | FEHD, CFS, IA, MCHK, Law Society, EDB, etc. | Identity, licence no., provenance, official verify links |

| `claimed` | Merchant claimed the registry row → live Agent Card | Deeper profile, verification, facade |

| `enrichment` | Google Places POC + merchant review | Hours, phone, website (with verification level) |

The response includes `recommendedUse.identity`, `.hours`, and `.contact` with values like `safe_to_cite`, `cite_with_caution`, or `do_not_cite`. Follow those fields before generating user-facing answers.

Default Call Flow (Required for Partners)

```

1. search_registry(q, source?, country=HK)

2. get_merged_profile(registryId) ← default read

3. If claimed.trusgentId → verify_agent before recommending

4. Optional: get_business_facade for menu / booking surfaces

```

Use `get_registry` only when you need raw official fields without enrichment or claim context — for example, a compliance audit export.

Quick Start: MCP (Recommended)

Endpoint: `POST https://www.trusgent.com/api/mcp` (JSON-RPC 2.0)

Optional auth: `Authorization: Bearer <api_key>` from [Dashboard → API Keys](https://www.trusgent.com/en/dashboard/api-keys). Public reads work without a key but are IP rate-limited.

1. Add the remote MCP server

Point your client at `https://www.trusgent.com/api/mcp`. Cursor / Claude Desktop / custom runtimes vary — see [Developer docs](https://www.trusgent.com/en/developers) and `docs/mcp.md` in the repo.

2. Search the registry

```json

{

"jsonrpc": "2.0",

"id": 1,

"method": "tools/call",

"params": {

"name": "search_registry",

"arguments": {

"q": "Central restaurant",

"country": "HK",

"source": "FEHD_RESTAURANT",

"limit": 5

}

}

}

```

Results include `registryId`, `profileUrl`, `jsonUrl`, and `mergedUrl`.

3. Fetch merged profile (default)

```json

{

"jsonrpc": "2.0",

"id": 2,

"method": "tools/call",

"params": {

"name": "get_merged_profile",

"arguments": {

"registryId": "fehd-3715038328",

"locale": "en"

}

}

}

```

4. Honor `recommendedUse`

Before citing in natural language:

•`safe_to_cite` — OK to state in the answer (still link provenance when possible).

•`cite_with_caution` — Mention uncertainty or source (e.g. inferred Places match, pending merchant review).

•`do_not_cite` — Do not state as fact; suggest checking the official register or claimed profile.

Quick Start: HTTP

```bash

curl "https://www.trusgent.com/api/v1/registry/search?q=central&country=HK&limit=5"

curl "https://www.trusgent.com/api/v1/registry/fehd-3715038328/merged"

```

OpenAPI: `https://www.trusgent.com/openapi.json` · Agent orientation: `https://www.trusgent.com/llms.txt`

Response Fields Cheat Sheet

| Field | Meaning |

|:---|:---|

| `official.verification.level` | `REGISTRY_OFFICIAL` |

| `official.provenance` | Issuer, dataset, verify-at-official links |

| `claimed.trusgentId` | Live Agent Card if merchant claimed this row |

| `enrichment.fields.*.verificationLevel` | `INFERRED` or `MERCHANT_CONFIRMED` |

| `enrichment.status` | e.g. `PENDING_REVIEW`, `CONFIRMED` |

| `trustBreakdown` | Score hints + explanatory `notes` |

| `recommendedUse` | Per-field citation policy for agents |

System Prompt Snippet (Copy Into Partner Agents)

```

When answering about a Hong Kong business using Trusgent registry data:

1. After search_registry, always call get_merged_profile (not get_registry alone).

2. Cite licence/name/address from official.* when recommendedUse.identity allows.

3. For hours and contact, obey recommendedUse — never cite when do_not_cite.

4. If claimed.trusgentId is present, call verify_agent before recommending the business.

5. Prefer linking profileUrl and official provenance URLs in structured citations.

6. Do not bulk-scrape merged endpoints; query on demand per user intent.

```

Integration Patterns

Pattern A — F&B vertical assistant

`search_registry(source=FEHD_RESTAURANT)` → `get_merged_profile` → show only `safe_to_cite` fields → CTA to claim and upgrade Agent Card.

Pattern B — Compliance / legal / medical lookup

Emphasize `official.provenance` and official verify links. Avoid marketing language. Do not infer hours or contact unless `MERCHANT_CONFIRMED`.

Pattern C — Claimed merchant deep dive

`get_merged_profile` → `verify_agent(claimed.trusgentId)` → `get_business_facade` for menu, hours, booking.

Registry vs Directory

Registry rows do not automatically appear in `/directory`. A business enters directory search after claim, profile completeness, and `discoverableInMarketplace`. Merged Profile is the machine-readable bridge on the registry landing page → claim → Agent Card funnel.

Edge Cases

| Situation | Behavior |

|:---|:---|

| 404 on merged | Invalid `registryId` |

| `enrichment: null` | No enrichment yet; use `official` + `recommendedUse` |

| `enrichment.provider: DEMO` | Server lacks `GOOGLE_PLACES_API_KEY`; treat hours/contact cautiously |

| `PENDING_REVIEW` | Merchant has not confirmed enrichment; usually `cite_with_caution` |

MCP Registry Listing

Trusgent publishes Trusgent MCP at [github.com/Trusgent/trusgent-mcp](https://github.com/Trusgent/trusgent-mcp) as `io.github.Trusgent/trusgent-mcp` (application source stays private). After publish, list on Smithery or Claude Market — see [Partners](https://www.trusgent.com/en/partners).

FAQ

What is the difference between merged JSON and registry JSON?

Registry JSON is official-only. Merged adds claim links, enrichment, `trustBreakdown`, and `recommendedUse`.

When must I call verify_agent?

Before recommending or transacting with a business when `claimed.trusgentId` exists, or when your product policy requires verified Agent Cards.

Can I crawl all 60k merged profiles?

No — query on demand via search. Bulk scraping violates the intended use and rate limits.

How do I get higher API limits?

Apply via [Partners](https://www.trusgent.com/en/partners) for sandbox → production keys after BD review.

Next Steps

•[Developer docs](https://www.trusgent.com/en/developers) — MCP + HTTP overview

•[Partners / BD](https://www.trusgent.com/en/partners) — formal integration

•[HK Registry Browse](https://www.trusgent.com/en/hk/registry/browse) — explore data

•[Create API key](https://www.trusgent.com/en/dashboard/api-keys) — raise rate limits