# Land Registry Report

Search and retrieve official land documents in minutes.

***

#### Flow

1. Optionally use `/lra/search` to find the Property Reference Number (PRN)
2. Pass the PRN to `/lra/request` to initiate the report request
3. Receive results via **webhook** or **poll** `/lra/poll`

***

#### Result Delivery

**Webhook (recommended)** — Pass a `callbackUrl` in the `/lra/request` body. When the report is ready, a `POST` request is sent to that URL with the report payload wrapped in a `WebhookPayload` envelope. Polling remains available as a fallback if delivery fails.

**Polling** — Call `/lra/poll` with the returned token until a `200` response is returned.

## Request

> Each request maps to exactly one returned document.\
> \
> Specify either PRN (if known or found through \`/lra/search\`) or address.\
> \
> Requests with the PRN will return within 5 minutes most of the time.\
> \
> Requests with Just the address will be manually resolved within 1-2 days.\
> \
> For requests that are not a PRN (Memorials), please pass the Memorial ID into the address field like \`{"address": "Memorial 1234567"}\`. These requests will be manually resolved within 1-2 days.\
> \
> \*\*Dry Run:\*\* Set \`dryRun: true\` to test the integration without incurring costs.\
> A sample Land Registry PDF is uploaded to the report path and returned immediately — no\
> retrieval script or manual process runs. The response includes \`dryRun: true\` and a token\
> that can be polled normally via \`/lra/poll\`.\
> \
> \*\*Webhook Delivery:\*\* Provide \`callbackUrl\` to receive a \`POST\` with the completed report\
> when it is ready. The webhook body is a \[\`WebhookPayload\`]\(#/components/schemas/WebhookPayload)\
> containing the same data as a \`200\` response from \`/lra/poll\`.\
> The request includes \`X-Webhook-Event: lra.report.completed\` and \`X-Request-Id\` headers,\
> plus any custom headers supplied in \`callbackHeaders\`.\
> Polling via \`/lra/poll\` remains available regardless of whether a \`callbackUrl\` is provided.<br>

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Land Registry Report","description":"Search and retrieve official land documents in minutes.\n\n---\n\n### Flow\n\n1. Optionally use `/lra/search` to find the Property Reference Number (PRN)\n\n2. Pass the PRN to `/lra/request` to initiate the report request\n\n3. Receive results via **webhook** or **poll** `/lra/poll`\n\n---\n\n### Result Delivery\n\n**Webhook (recommended)** — Pass a `callbackUrl` in the `/lra/request` body.\nWhen the report is ready, a `POST` request is sent to that URL with the report payload\nwrapped in a [`WebhookPayload`](#/components/schemas/WebhookPayload) envelope.\nPolling remains available as a fallback if delivery fails.\n\n**Polling** — Call `/lra/poll` with the returned token until a `200` response is returned.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}}},"paths":{"/lra/request":{"post":{"tags":["Land Registry Report"],"summary":"Request","description":"Each request maps to exactly one returned document.\n\nSpecify either PRN (if known or found through `/lra/search`) or address.\n\nRequests with the PRN will return within 5 minutes most of the time.\n\nRequests with Just the address will be manually resolved within 1-2 days.\n\nFor requests that are not a PRN (Memorials), please pass the Memorial ID into the address field like `{\"address\": \"Memorial 1234567\"}`. These requests will be manually resolved within 1-2 days.\n\n**Dry Run:** Set `dryRun: true` to test the integration without incurring costs.\nA sample Land Registry PDF is uploaded to the report path and returned immediately — no\nretrieval script or manual process runs. The response includes `dryRun: true` and a token\nthat can be polled normally via `/lra/poll`.\n\n**Webhook Delivery:** Provide `callbackUrl` to receive a `POST` with the completed report\nwhen it is ready. The webhook body is a [`WebhookPayload`](#/components/schemas/WebhookPayload)\ncontaining the same data as a `200` response from `/lra/poll`.\nThe request includes `X-Webhook-Event: lra.report.completed` and `X-Request-Id` headers,\nplus any custom headers supplied in `callbackHeaders`.\nPolling via `/lra/poll` remains available regardless of whether a `callbackUrl` is provided.\n","operationId":"lraRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"countryCode":{"type":"string","description":"Country code for the property"},"prn":{"type":"string","description":"Property Reference Number"},"address":{"type":"string","description":"Property Address"},"bestMatch":{"type":"object","description":"Best match information from search","properties":{"aiAgent":{"type":"object","required":["prn","free_format_addr_eng"],"properties":{"prn":{"type":"string","description":"Property Reference Number"},"free_format_addr_eng":{"type":"string","description":"Free format English address"}}},"lotSearch":{"type":"array","items":{"type":"string"},"description":"Array of lot search results"},"gemini":{"type":"object","required":["query_address","status","reason","result"],"properties":{"query_address":{"type":"string","description":"The original query address"},"status":{"type":"string","enum":["not found","potential match","multiple found","error"],"description":"Status of the address search (all statuses except \"found\")"},"reason":{"type":"string","description":"Reason for the status"},"result":{"type":"array","items":{"type":"object","required":["prn","free_format_addr_eng"],"properties":{"prn":{"type":"string","description":"Property Reference Number"},"free_format_addr_eng":{"type":"string","description":"Free format English address"}}}}}}}},"emailList":{"type":"array","items":{"type":"string","format":"email"},"description":"Optional field for usage analytics"},"externalRefId":{"type":"string","description":"Your own reference ID (optional field for usage analytics)"},"dryRun":{"type":"boolean","description":"Set to `true` to test the full request-poll flow without incurring costs.\nA sample Land Registry PDF is uploaded to S3 and the request returns immediately.\n"},"express":{"type":"boolean","description":"Expediate request speed (Only used if turn-around times have been agreed upon)"},"callbackUrl":{"type":"string","format":"uri","pattern":"^https://.+","description":"HTTPS URL to receive a webhook POST when the report is ready.\nWhen provided, the completed report (same payload as a `200` response from `/lra/poll`)\nis delivered to this URL.\nPolling remains available as a fallback.\n"},"callbackHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Custom HTTP headers to include in the webhook request.\nUse this to pass authentication or any other headers your endpoint requires\n(e.g. `{\"Authorization\": \"Bearer <token>\", \"X-Api-Key\": \"...\"}`).\n"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Poll with this token"},"dryRun":{"description":"Echoed back as `true` when the request was a dry run — no cost incurred","type":"boolean"}}}}}}}}}}}
```

## Poll Report

> Check the status of a land registry report request.\
> Keep polling until a \`200\` response is returned.\
> \
> Returns \`202\` while the report is still being processed.\
> \
> If a \`callbackUrl\` was provided in \`/lra/request\`, the report is also\
> delivered via webhook when ready. Polling is always available as a fallback.<br>

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Land Registry Report","description":"Search and retrieve official land documents in minutes.\n\n---\n\n### Flow\n\n1. Optionally use `/lra/search` to find the Property Reference Number (PRN)\n\n2. Pass the PRN to `/lra/request` to initiate the report request\n\n3. Receive results via **webhook** or **poll** `/lra/poll`\n\n---\n\n### Result Delivery\n\n**Webhook (recommended)** — Pass a `callbackUrl` in the `/lra/request` body.\nWhen the report is ready, a `POST` request is sent to that URL with the report payload\nwrapped in a [`WebhookPayload`](#/components/schemas/WebhookPayload) envelope.\nPolling remains available as a fallback if delivery fails.\n\n**Polling** — Call `/lra/poll` with the returned token until a `200` response is returned.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}}},"paths":{"/lra/poll":{"post":{"tags":["Land Registry Report"],"summary":"Poll Report","description":"Check the status of a land registry report request.\nKeep polling until a `200` response is returned.\n\nReturns `202` while the report is still being processed.\n\nIf a `callbackUrl` was provided in `/lra/request`, the report is also\ndelivered via webhook when ready. Polling is always available as a fallback.\n","operationId":"lraPoll","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["token"],"type":"object","properties":{"token":{"type":"string","description":"Output of `/lra/request`"}}}}}},"responses":{"200":{"description":"Report ready","content":{"application/json":{"schema":{"type":"object","required":["message","data"],"properties":{"message":{"type":"string"},"data":{"type":"string","description":"Presigned URL to download the report"}}}}}},"202":{"description":"Report is pending","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}}}}}}}}}}
```

## Search HK Land Registry address records

> Queries the \`address\_table\` in PostgreSQL to find matching property records.\
> Returns up to 300 matching records. All filter conditions are combined with AND logic.\
> At least one search parameter should be provided.<br>

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Land Registry Report","description":"Search and retrieve official land documents in minutes.\n\n---\n\n### Flow\n\n1. Optionally use `/lra/search` to find the Property Reference Number (PRN)\n\n2. Pass the PRN to `/lra/request` to initiate the report request\n\n3. Receive results via **webhook** or **poll** `/lra/poll`\n\n---\n\n### Result Delivery\n\n**Webhook (recommended)** — Pass a `callbackUrl` in the `/lra/request` body.\nWhen the report is ready, a `POST` request is sent to that URL with the report payload\nwrapped in a [`WebhookPayload`](#/components/schemas/WebhookPayload) envelope.\nPolling remains available as a fallback if delivery fails.\n\n**Polling** — Call `/lra/poll` with the returned token until a `200` response is returned.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}}},"paths":{"/lra/search":{"post":{"tags":["Land Registry Report"],"summary":"Search HK Land Registry address records","description":"Queries the `address_table` in PostgreSQL to find matching property records.\nReturns up to 300 matching records. All filter conditions are combined with AND logic.\nAt least one search parameter should be provided.\n","operationId":"lraSearch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Search filters for address lookup. All fields are optional but at least one should be provided.\nAll supplied conditions are combined with AND logic.\n","properties":{"block":{"type":"string","description":"Block or tower identifier (e.g. \"BLOCK B\", \"TOWER 1\").\nExact match against the `block` column.\n"},"eng_street_name":{"type":"string","description":"English street name. Case-insensitive containment match\n(`UPPER(street_name_eng) LIKE '%value%'`).\nTolerates partial matches.\n"},"ch_street_name":{"type":"string","description":"Chinese street name. Containment match against `street_name_chn`.\nOnly used if `eng_street_name` is not provided.\n"},"flat":{"type":"string","description":"Flat or unit identifier (e.g. \"A\", \"12\", \"B1\").\nCase-insensitive containment match (`UPPER(flat) LIKE '%value%'`).\n"},"floor":{"type":"string","description":"Floor designation (e.g. \"8\", \"G/F\", \"MEZZANINE\").\nCase-insensitive containment match (`UPPER(floor) LIKE '%value'`).\n"},"free_entry":{"type":"array","items":{"type":"string"},"description":"Free-form substrings matched against the `free_format_addr_eng` column.\nEach entry is matched independently with case-insensitive containment\n(`UPPER(free_format_addr_eng) LIKE '%value%'`).\nMultiple entries are combined with AND — all must match.\nUseful for searching building names, estate names, or partial addresses.\n"},"house_prefix":{"type":"array","items":{"type":"number"},"minItems":1,"maxItems":2,"description":"Numeric part of the house/building number.\n- **1 value** `[86]`: exact match (`house_num_prefix = 86`).\n- **2 values** `[80, 90]`: inclusive range (`house_num_prefix BETWEEN 80 AND 90`).\n"},"house_suffix":{"type":"string","description":"Alphabetic suffix of the building number (e.g. \"A\" in \"12A\").\nExact match against the `house_num_suffix` column.\n"}}}}}},"responses":{"200":{"description":"Matching address records (max 300).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["prn","free_format_addr_eng"],"properties":{"prn":{"type":"string","description":"Property Reference Number — unique identifier for the property in HK Land Registry."},"free_format_addr_eng":{"type":"string","description":"Full English free-format address as stored in the registry."}}}}}}}}}}}}
```


---

# 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://docs.fill-easy.com/land-registry-report.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.