> For the complete documentation index, see [llms.txt](https://docs.fill-easy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fill-easy.com/land-registry-report.md).
# 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.
```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"},"category":{"type":"string","enum":["confirm","clarify","reject","lot","memorial"],"description":"Resolver outcome for this order (drives the ops dashboard view)"},"reasoning":{"type":"string","description":"Judge reasoning or defer reason, shown to ops"},"candidates":{"type":"array","description":"Alternative matches considered (shown to ops for clarify/reject)","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 \", \"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.
```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"},"fileName":{"type":"string","description":"Suggested file name — the property address (or PRN), e.g. \"Flat A, 12 F, Block 1, Discovery Bay_Land Search.pdf\"."}}}}}},"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.
```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."}}}}}}}}}}}}
```