Skip to main content
API docs by Redocly

Nimbus Document Purchase API (1.0.0)

Download OpenAPI specification:Download

Nimbus Support: support@nimbusproperty.co.uk License: Proprietary

API service for purchasing Nimbus-provided documents, including land registry (HMLR) documents and other property-related documents.

This API enables customers to:

  • Check document availability and pricing for a title number
  • View pending applications on the title
  • Purchase documents with token-based billing
  • Receive documents via webhook delivery

Authentication

All requests must carry a valid Entra ID Bearer token issued for the Document API audience. Two OAuth 2.0 grant types are supported; choose the one that fits your integration.

Delegated user flow (authorization code)

Use this flow when your server calls the API on behalf of an authenticated end user. Every purchase and audit record is tied to that user's identity.

  1. Direct the user to the Entra ID authorization endpoint to sign in
  2. Receive an authorization code and exchange it for an access token
  3. Request the scopes your integration needs: docs.read, docs.purchase, and/or docs.webhooks.manage
  4. Include the access token in the Authorization: Bearer <token> header
  5. Use the refresh token to obtain a new access token when the current one expires

Internally, the API uses the OAuth 2.0 On-Behalf-Of (OBO) flow to exchange the incoming user token for backend-specific tokens when calling HMLR Legacy API and the Ledger service. This is transparent to callers — you only need the delegated scopes listed above.

Application flow (client credentials)

Use this flow when your server calls the API autonomously, without an end user authenticating in real time. Purchases and audit records are tied to a Nimbus service identity provisioned for your integration.

  1. Contact Nimbus to have an Entra application registration created for your integration
  2. Acquire a token using the client credentials grant against the Document API audience
  3. Include the token in the Authorization: Bearer <token> header

Endpoint access is controlled by app roles granted to your registration. Always request the /.default scope when acquiring client credentials tokens.

Rate Limits

  • 60 requests per minute per user
  • 1,000 requests per hour per user

Workflow

  1. Call /check-availability to see available documents and costs
  2. Call /purchase with the documents you want to buy
  3. Documents are delivered to your webhook URL when ready
  4. Optionally poll /orders/{order_id} to check status

Documents

Document availability and purchase operations

Check document availability and costs

Check which HMLR documents are available for a given title and the token cost for each. Also returns information about any pending applications on the title.

You can query by either:

  • title_number: UK Land Registry title number (e.g., AB123456)
  • title_id: Internal UUID identifier for the title

Exactly one of these parameters must be provided.

This endpoint:

  • Queries HMLR for available documents
  • Queries HMLR for pending applications
  • Calculates token costs based on document types
  • Returns current account balance

Results are cached for 5 minutes in Azure API Management.

Authorizations:
OAuth2OAuth2ClientCredentials
query Parameters
title_number
string [ 2 .. 10 ] characters ^[A-Z]{1,3}[0-9]{1,7}$
Example: title_number=AB123456

UK Land Registry title number (e.g., AB123456). Either title_number or title_id must be provided.

title_id
string <uuid>
Example: title_id=0000a942-3cee-431d-bd71-d07cb27197ec

Internal UUID identifier for the title. Either title_number or title_id must be provided.

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    },
  • "total_token_cost_estimate": 14,
  • "current_balance": 150
}

Purchase documents

Purchase one or more documents for a title.

Prerequisites:

  • Must have subscribed to webhooks via POST /subscribe
  • Sufficient token balance in account

This endpoint:

  • Validates document availability with the document provider
  • Checks account balance
  • Deducts tokens from your account via the Ledger API
  • Creates order in backend system
  • Returns immediately with an order ID

Documents are delivered asynchronously to your subscribed webhook URL when ready.

Document types

Use documents for standard HMLR documents (register, title_plan).

Use referred_documents for referred documents (deeds, leases, transfers, etc.). Each referred document is identified by the three values returned in the check-availability response: type_code, date, and filed_under. This allows you to select specific documents precisely — for example, the first and third lease on a title — rather than ordering all documents of a given type.

At least one of documents or referred_documents must be provided.

Authorizations:
OAuth2OAuth2ClientCredentials
Request Body schema: application/json
required
title_number
required
string^[A-Z]{1,3}[0-9]{1,7}$

UK Land Registry title number

documents
Array of strings <= 2 items
Items Enum: "register" "title_plan"

Standard HMLR documents to purchase. Only register and title_plan are accepted. Optional if referred_documents is provided.

Array of objects (ReferredDocumentPurchaseItem) <= 50 items

Referred documents (deeds, leases, transfers, etc.) to purchase. Each item uses the exact type_code, date, and filed_under values from the check-availability response to uniquely identify the document. Optional if documents is provided.

customer_reference
string <= 255 characters

Your internal reference for this order

Responses

Request samples

Content type
application/json
Example
{
  • "title_number": "AB123456",
  • "documents": [
    ],
  • "customer_reference": "CUST-ORDER-12345"
}

Response samples

Content type
application/json
{
  • "order_id": "770e8400-e29b-41d4-a716-446655440002",
  • "status": "PROCESSING",
  • "title_number": "BK383592",
  • "documents_ordered": [
    ],
  • "referred_documents_ordered": [
    ],
  • "total_tokens_charged": 21,
  • "new_balance": 129,
  • "estimated_delivery": "2026-01-15T14:35:00Z"
}

Download a purchased document

Download a document from a completed order using its unique document ID.

This endpoint allows you to:

  • Re-download documents that were previously delivered via webhook
  • Download documents when webhook delivery failed
  • Access documents from past orders

No additional charge - You've already paid for the document.

Documents are stored indefinitely so you can always re-download your previously purchased documents.

Getting the document_id: The unique document ID is provided in the order status response after the document has been downloaded. Use the document_id field (UUID) from the DocumentDeliveryStatus.

Authorizations:
OAuth2OAuth2ClientCredentials
path Parameters
document_id
required
string <uuid>
Example: 990e8400-e29b-41d4-a716-446655440003

The unique document ID for the document (UUID from order status response)

Responses

Response samples

Content type
application/json
{
  • "document_id": "990e8400-e29b-41d4-a716-446655440003",
  • "document_type_code": "REGISTER",
  • "format": "pdf",
  • "content": "JVBERi0xLjQKJeLjz9MK...",
  • "metadata": {
    },
  • "downloaded_at": "2026-01-15T14:32:15Z"
}

Verify ownership of a title

Verify if a named person is the registered proprietor of a property title using HMLR's Online Owner Verification (OOV) service.

Cost: This endpoint charges 1 token per verification.

This endpoint:

  • Verifies if the person you specify matches the registered proprietor(s)
  • Returns match status: SINGLE_MATCH, MULTIPLE_MATCHES, or NO_MATCHES
  • Provides detailed match quality for partial matches
  • Useful for identity verification, AML/KYC checks, and pre-transaction due diligence
  • Deducts 1 token from your account balance after successful verification

This is a verification service, not a discovery service. You must provide the person's name to verify. To discover who owns a property, purchase and review the Official Copy of the Register.

Authorizations:
OAuth2OAuth2ClientCredentials
Request Body schema: application/json
required
title_number
required
string [ 1 .. 9 ] characters ^[A-Z]{1,3}[0-9]{1,7}$

UK Land Registry title number

first_forename
required
string non-empty ^[a-zA-Z0-9\-']+$

First forename of the person to verify

middle_name
string non-empty ^[a-zA-Z0-9\-\s']+$

Middle name(s) of the person to verify (optional)

surname
required
string non-empty ^[a-zA-Z0-9\-\s']+$

Surname of the person to verify

customer_reference
string <= 25 characters ^[A-Za-z0-9\s~!"@#$%'()*+,\-./:;=>?\[\\\]_\{\...

Your reference for tracking this ownership verification

Responses

Request samples

Content type
application/json
Example
{
  • "title_number": "BK126329",
  • "first_forename": "Nicolas",
  • "surname": "Neate",
  • "customer_reference": "VERIFY-001"
}

Response samples

Content type
application/json
Example
{
  • "verification_id": "eoov-a6d8f57f84c4",
  • "title_number": "BK126329",
  • "match_result": "SINGLE_MATCH",
  • "property_address": {
    },
  • "surname_match": "MATCH",
  • "forename_match": "MATCH",
  • "middle_name_match": "NO_MATCH",
  • "match_information": {
    },
  • "customer_reference": "VERIFY-001",
  • "tokens_charged": 1,
  • "new_balance": 149,
  • "verified_at": "2026-02-25T21:04:35Z"
}

Orders

Order status and management

Get order status

Retrieve the current status of a document order.

Order statuses:

  • PENDING_PAYMENT: Payment is being processed
  • PROCESSING: Documents are being ordered from the provider
  • COMPLETED: Documents have been delivered to webhook
  • FAILED: Order failed (see error_message)
  • WEBHOOK_FAILED: Documents ready but webhook delivery failed
Authorizations:
OAuth2OAuth2ClientCredentials
path Parameters
order_id
required
string <uuid>
Example: 770e8400-e29b-41d4-a716-446655440002

The unique identifier of the order

Responses

Response samples

Content type
application/json
Example
{
  • "order_id": "770e8400-e29b-41d4-a716-446655440002",
  • "status": "COMPLETED",
  • "customer_reference": "CUST-ORDER-12345",
  • "documents": [
    ],
  • "total_tokens_charged": 14,
  • "created_at": "2026-01-15T14:30:00Z",
  • "completed_at": "2026-01-15T14:32:15Z"
}

Health

Service health checks

Health check endpoint

Check the health status of the API service and its dependencies.

Returns 200 if all systems are operational. Returns 503 if any critical dependency is unavailable.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "timestamp": "2026-01-15T14:30:00Z",
  • "checks": {
    }
}

Webhooks

Subscribe to webhook notifications

Register a webhook endpoint to receive notifications when purchased documents are ready.

The subscription is associated with your authentication credentials. All subsequent document purchases will automatically trigger webhook notifications to this endpoint.

Important: Save the returned secret immediately. It cannot be retrieved later and is required to verify webhook signatures using HMAC-SHA256.

Webhook Delivery

When documents are ready, you'll receive:

POST {your_webhook_url}
Content-Type: application/json
X-Webhook-Signature: {base64_hmac_sha256_signature}
X-Webhook-Event: document.status_changed
X-Webhook-Id: {unique_event_id}
Authorizations:
OAuth2OAuth2ClientCredentials
Request Body schema: application/json
required
webhook_url
required
string <uri>

HTTPS URL where order completion webhooks will be delivered.

Requirements:

  • Must use HTTPS (not HTTP)
  • Must be publicly accessible
  • Must not be localhost/127.0.0.1
  • Should respond within 30 seconds
  • Should return 2xx status for successful delivery

The webhook will receive POST requests with:

  • Content-Type: application/json
  • X-Webhook-Signature: HMAC-SHA256 signature for verification
  • Body: Order completion details (OrderStatusResponse)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Cancel a webhook subscription

Cancel an active webhook subscription. Once cancelled, no further webhook notifications will be delivered for new document purchases.

Authorizations:
OAuth2OAuth2ClientCredentials
path Parameters
subscription_id
required
string <uuid>
Examples: 8f8d2e40-1234-5678-9abc-def012345678

UUID of the subscription to cancel

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get webhook delivery audit log

Retrieve a paginated log of webhook delivery attempts for your subscriptions. Useful for debugging missed or failed webhook deliveries.

Authorizations:
OAuth2OAuth2ClientCredentials
Request Body schema: application/json
optional
start_date
string or null <date-time>

Start of date range filter (ISO 8601)

end_date
string or null <date-time>

End of date range filter (ISO 8601)

subscription_id
string or null <uuid>

Filter to a specific subscription

document_reference
string or null

Filter to a specific document reference

page_number
integer >= 1
Default: 1

Page number (1-indexed)

page_size
integer [ 1 .. 100 ]
Default: 20

Number of items per page

Responses

Request samples

Content type
application/json
{
  • "start_date": "2026-04-14T00:00:00Z",
  • "end_date": "2026-04-21T23:59:59Z",
  • "page_number": 1,
  • "page_size": 20
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total_count": 0,
  • "page_number": 0,
  • "page_size": 0,
  • "total_pages": 0
}

Get webhook event delivery details

Retrieve all delivery attempts for a specific webhook event, including HTTP response codes and error messages for each attempt.

Authorizations:
OAuth2OAuth2ClientCredentials
path Parameters
event_id
required
string <uuid>
Examples: 550e8400-e29b-41d4-a716-446655440000

UUID of the webhook event

Responses

Response samples

Content type
application/json
{
  • "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  • "attempts": [
    ]
}

Get webhook delivery statistics

Retrieve delivery success/failure statistics for a date range. Includes total attempts, success rate, and average delivery duration.

Authorizations:
OAuth2OAuth2ClientCredentials
Request Body schema: application/json
required
start_date
required
string <date-time>

Start of the statistics window (ISO 8601)

end_date
required
string <date-time>

End of the statistics window (ISO 8601)

Responses

Request samples

Content type
application/json
{
  • "start_date": "2026-03-22T00:00:00Z",
  • "end_date": "2026-04-21T23:59:59Z"
}

Response samples

Content type
application/json
{
  • "total_attempts": 0,
  • "successful_deliveries": 0,
  • "failed_deliveries": 0,
  • "success_rate": 0.97,
  • "average_duration_ms": 145.3
}