Getting Started with NLDS API

Welcome to the Natural Language Document Search (NLDS) API. This guide walks you through integrating NLDS into your system step by step, explaining every concept before diving into the reference documentation.

Table of Contents

• 1. Overview
• 2. Authentication
  • Token Request
  • Using the Token
  • Token Lifecycle
  • Security Notes
• 3. Company ID and Pagination
  • Pagination for List APIs
• 4. Products
  • List Available Products
• 5. Cases
  • List Cases
  • Create a Case
  • Get Case Details
• 6. Documents
  • Lookup Documents
  • List Case Documents
  • Batch Register Documents
  • Complete Upload
  • Get Document Status
• 7. Webhooks
  • Supported Webhook Event Types
  • Webhook HTTP Headers
  • Common Webhook Payload Envelope
  • Example Payloads
  • Retry and Delivery Semantics
  • Response Expectation
• 8. Query Flow
  • Submit Query
  • Check Query Status
  • Get Query Results
  • Sandbox Quick Start

1. Overview

NLDS is a platform that ingests mortgage documents (PDFs) from your system, validates and indexes them using OCR and AI extraction, and lets you query them using natural-language text, a structured document checklist, or both.

What you can do:

• Upload mortgage documents (closing disclosures, promissory notes, title policies, appraisals, and more) from your system
• Query indexed documents by submitting natural-language text, a structured checkList of document types with optional attribute filters, or both
• Retrieve search results with extracted metadata (borrower name, document date, and signature status)

Two integration flows:

1. Ingest flow: You upload documents via the case upload API; NLDS validates and indexes them asynchronously
2. Query flow: You submit natural-language text, a structured checkList, or both against a case's indexed documents; NLDS searches and returns results asynchronously

Async design: Upload validation and ingestion run asynchronously in the backend. Your API calls return quickly; use the case and document status endpoints to track progress.

2. Authentication

NLDS uses OAuth 2.0 machine-to-machine (M2M) authentication. Your integration system acts as a confidential OAuth client, obtaining a token from the AuthX service and passing it in the Authorization header for all API calls.

Token Request

Request a token from AuthX using the client_credentials grant type.

Endpoint: POST https://id.digilytics.solutions/authx/oauth2/token

Request (form-encoded):

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=nldocsearch.api

cURL example:

curl -X POST https://id.digilytics.solutions/authx/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=nldocsearch.api"

Token Response (JSON):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Using the Token

Include the token in the Authorization header of every API call:

Authorization: Bearer {access_token}

Example:

curl -X GET https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Lifecycle

• Token lifetime: 30 minutes
• No refresh token is issued; when the token expires, request a new one using the same client_credentials flow
• Always cache the token locally; reuse it for all requests until expiry
• Store client_id, client_secret, and tokens in secure secret storage (e.g., environment variables, HashiCorp Vault, Azure Key Vault) — never store them in source code

Security Notes

• Only confidential systems should store client_secret. Public/browser-based clients cannot use this flow
• For token inspection and validation, you can verify the JWT signature using the AuthX JWKS endpoint (/.well-known/jwks.json). See the AuthX developer guide for details
• Tokens are bearer tokens; anyone with the token can make API calls on your behalf. Treat tokens as sensitive as passwords

3. Company ID and Pagination

Your company is identified by a companyId - a long integer provisioned during onboarding.

Example: companyId = 123456

Every API path includes your companyId as a required segment:

/api/v1/{companyId}/products
/api/v1/{companyId}/cases

The API validates that the companyId in the path matches the companyId claim in your JWT token. A mismatched or missing companyId returns 403 Forbidden.

Pagination for List APIs

The product list, case list/search, and case document list APIs are paginated.

Use these optional query parameters:

Each paginated response returns records under data.content[] and page details under data.

{
  "meta": {
    "code": 200,
    "type": "success",
    "message": "success"
  },
  "data": {
    "content": [
      {
        "...": "..."
      }
    ],
    "page": 0,
    "size": 50,
    "totalElements": 123,
    "totalPages": 3,
    "first": true,
    "last": false
  }
}

Use camelCase sort field names, such as createdAt and lastModifiedAt. Do not send snake_case database column names such as created_at or last_modified_at.

Invalid pagination or sort input returns 400 Bad Request.

4. Products

List Available Products

Endpoint: GET /api/v1/{companyId}/products

This endpoint returns active products available to the company. The response is paginated, and product records are returned in data.content[].

Query parameters:

Allowed sort fields:

• productCode
• displayName
• createdAt
• lastModifiedAt

Example requests:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/products" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/products?page=0&size=50&sort=productCode,asc" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/products?page=1&size=25&sort=displayName,asc" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "message": "success",
    "type": "success"
  },
  "data": {
    "content": [
      {
        "productCode": "HELOC",
        "displayName": "Home Equity Line of Credit",
        "status": "ACTIVE",
        "createdAt": "2024-06-01T00:00:00Z",
        "lastModifiedAt": "2024-06-01T00:00:00Z"
      },
      {
        "productCode": "MORTGAGE",
        "displayName": "Residential Mortgage",
        "status": "ACTIVE",
        "createdAt": "2024-06-01T00:00:00Z",
        "lastModifiedAt": "2024-06-01T00:00:00Z"
      }
    ],
    "page": 0,
    "size": 50,
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

5. Cases

List Cases

Endpoint: GET /api/v1/{companyId}/cases

This endpoint lists or searches cases visible to the company. The response is paginated, and case records are returned in data.content[].

Query parameters:

Allowed sort fields:

• lastModifiedAt
• createdAt
• displayName
• externalCaseId
• productCode
• status

Example requests:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases?page=0&size=50&sort=lastModifiedAt,desc" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases?productCode=mortgage-premium&q=smith&page=1&size=25&sort=createdAt,asc" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "message": "success",
    "type": "success"
  },
  "data": {
    "content": [
      {
        "casePublicId": "8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2",
        "productCode": "MORTGAGE",
        "externalCaseId": "LOS-998877",
        "displayName": "Smith Mortgage - LOS-998877",
        "status": "ACTIVE",
        "createdAt": "2024-12-15T14:32:00Z",
        "lastModifiedAt": "2024-12-15T14:32:00Z",
        "documentSummary": {
          "total": 3,
          "uploadPending": 0,
          "uploaded": 1,
          "validationPending": 0,
          "validationPassed": 3,
          "validationFailed": 0,
          "ingestionQueued": 2,
          "indexed": 1,
          "ingestionFailed": 0
        }
      }
    ],
    "page": 0,
    "size": 50,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

Create a Case

Endpoint: POST /api/v1/{companyId}/cases

Request:

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "MORTGAGE",
    "externalCaseId": "LOS-998877",
    "displayName": "Smith Mortgage - LOS-998877"
  }'

Request Body:

{
  "productCode": "MORTGAGE",
  "externalCaseId": "LOS-998877",
  "displayName": "Smith Mortgage - LOS-998877"
}

Response (201 Created):

{
  "meta": {
    "code": 201,
    "message": "success",
    "type": "success"
  },
  "data": {
    "casePublicId": "8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2",
    "productCode": "MORTGAGE",
    "externalCaseId": "LOS-998877",
    "displayName": "Smith Mortgage - LOS-998877",
    "status": "ACTIVE",
    "createdAt": "2024-12-15T14:32:00Z",
    "documentSummary": {
      "total": 0,
      "uploadPending": 0,
      "uploaded": 0,
      "validationPending": 0,
      "validationPassed": 0,
      "validationFailed": 0,
      "ingestionQueued": 0,
      "indexed": 0,
      "ingestionFailed": 0
    }
  }
}

Get Case Details

Endpoint: GET /api/v1/{companyId}/cases/{casePublicId}

Request:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK): Same shape as case creation response, with current document status counts.

6. Documents

This section covers client-facing document APIs for lookup, listing, registration, upload completion, and status retrieval.

Lookup Documents

What is a document ID?

externalDocumentId is your system's identifier for a source document (e.g., "DOC-CD-2024-001"). When supplied, NLDS uses it to identify the document within the same company, product, and case.

documentPublicId is the NLDS document identifier returned during registration. Store this value and use it for lookup, retry, or re-register flows when externalDocumentId is not available.

Endpoint: POST /api/v1/{companyId}/cases/{casePublicId}/documents:lookup

Request:

Lookup by externalDocumentIds:

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/ab3cb669-3df7-4c8a-beaa-a7ccafd76e90/documents:lookup" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "externalDocumentIds": ["DOC-001", "DOC-002"]
  }'

Lookup by documentPublicIds:

{
  "documentPublicIds": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ]
}

Lookup with both identifier lists:

{
  "externalDocumentIds": ["DOC-001"],
  "documentPublicIds": ["660e8400-e29b-41d4-a716-446655440001"]
}

At least one identifier list must be supplied. Empty request bodies and empty identifier lists are not allowed. Use GET /api/v1/{companyId}/cases/{casePublicId}/documents to list documents in a case.

Validation rules:

• externalDocumentIds can contain up to 200 entries
• documentPublicIds can contain up to 200 entries
• externalDocumentId can contain letters, digits, dot (.), underscore (_), hyphen (-), colon (:), and slash (/)
• documentPublicId must be a UUID
• Duplicate documentPublicIds in the same lookup request are rejected

Response (200 OK):

{
  "meta": {
    "code": 200,
    "message": "success",
    "type": "success"
  },
  "data": [
    {
      "externalDocumentId": "DOC-001",
      "found": true,
      "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
      "casePublicId": "ab3cb669-3df7-4c8a-beaa-a7ccafd76e90",
      "originalFilename": "Closing_Disclosure_signed.pdf",
      "contentSize": 1024576,
      "contentHash": "sha256:9f1c2a4b...",
      "uploadStatus": "UPLOADED",
      "validationStatus": "PASSED",
      "ingestionStatus": "INDEXED",
      "lastModifiedAt": "2026-05-28T10:00:00Z"
    },
    {
      "externalDocumentId": "DOC-002",
      "found": false,
      "documentPublicId": null,
      "casePublicId": null,
      "originalFilename": null,
      "contentSize": null,
      "contentHash": null,
      "uploadStatus": null,
      "validationStatus": null,
      "ingestionStatus": null,
      "lastModifiedAt": null
    }
  ]
}

The API returns one lookup result per requested value. Existing documents return found=true with document details. Missing values return found=false. Results are scoped to the case in the path and do not return matches from another case.

List Case Documents

Endpoint: GET /api/v1/{companyId}/cases/{casePublicId}/documents

This endpoint returns documents belonging to the specified case. The response is paginated, and document records are returned in data.content[].

Query parameters:

Allowed sort fields:

• createdAt
• lastModifiedAt
• originalFilename
• uploadStatus
• validationStatus
• ingestionStatus

Example requests:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/ab3cb669-3df7-4c8a-beaa-a7ccafd76e90/documents" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/ab3cb669-3df7-4c8a-beaa-a7ccafd76e90/documents?page=0&size=50&sort=createdAt,asc" \
  -H "Authorization: Bearer {access_token}"

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/ab3cb669-3df7-4c8a-beaa-a7ccafd76e90/documents?page=2&size=20&sort=originalFilename,desc" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "message": "success",
    "type": "success"
  },
  "data": {
    "content": [
      {
        "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
        "casePublicId": "ab3cb669-3df7-4c8a-beaa-a7ccafd76e90",
        "originalFilename": "Closing_Disclosure_signed.pdf",
        "contentType": "application/pdf",
        "contentSize": 1024576,
        "uploadStatus": "UPLOADED",
        "validationStatus": "PASSED",
        "ingestionStatus": "INDEXED",
        "diagnostics": [],
        "createdAt": "2026-05-28T10:00:00Z",
        "lastModifiedAt": "2026-05-28T10:00:00Z"
      }
    ],
    "page": 0,
    "size": 50,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "last": true
  }
}

Batch Register Documents

Endpoint: POST /api/v1/{companyId}/cases/{casePublicId}/documents:register

Request:

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2/documents:register" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "originalFilename": "Closing_Disclosure_signed.pdf",
        "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
        "externalDocumentId": "DOC-CD-2024-001",
        "contentLength": 1024576,
        "pageCount": 48,
        "declaredContentType": "application/pdf",
        "sourceSystemPath": "closing-package/CD_signed_final.pdf"
      }
    ]
  }'

Request Body:

{
  "documents": [
    {
      "originalFilename": "Closing_Disclosure_signed.pdf",
      "documentPublicId": "optional UUID, used for retry/re-register when externalDocumentId is not available",
      "externalDocumentId": "optional case-scoped external id",
      "contentLength": 1024576,
      "pageCount": 48,
      "declaredContentType": "application/pdf",
      "sourceSystemPath": "closing-package/CD_signed_final.pdf"
    }
  ]
}

Validation rules:

• documents is required and cannot be empty
• Maximum 50 documents per request
• Only PDF upload extension is currently supported
• Duplicate externalDocumentId values inside the same register request are rejected per document
• Duplicate documentPublicId values inside the same register request are rejected per document
• pageCount > 1000 for a PDF fails per document
• contentLength above the configured limit fails per document

The API always returns documentPublicId for successful registrations. Store this value. If externalDocumentId is not available, use documentPublicId later to look up the document, re-register or retry the document, and request a fresh SAS URL after failed upload or failed validation.

Response (201 Created - full success):

{
  "meta": {
    "code": 201,
    "type": "success",
    "message": "Documents registered successfully"
  },
  "data": [
    {
      "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
      "originalFilename": "Closing_Disclosure_signed.pdf",
      "externalDocumentId": "DOC-CD-2024-001",
      "sourceSystemPath": "closing-package/CD_signed_final.pdf",
      "uploadStatus": "UPLOAD_PENDING",
      "validationStatus": "PENDING",
      "ingestionStatus": "PENDING",
      "createdAt": "2026-05-28T10:00:00Z",
      "lastModifiedAt": "2026-05-28T10:00:00Z",
      "sasUploadUrl": "https://...sas...",
      "uploadMethod": "PUT",
      "sasExpiresAt": "2026-05-28T10:15:00Z",
      "existingDocument": false
    }
  ]
}

Response (207 Multi-Status - partial success):

{
  "meta": {
    "code": 207,
    "type": "partial",
    "message": "Some documents registered successfully; some failed"
  },
  "data": {
    "overallStatus": "PARTIAL",
    "successfulDocuments": [
      {
        "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
        "originalFilename": "Closing_Disclosure_signed.pdf",
        "externalDocumentId": "DOC-CD-2024-001",
        "sourceSystemPath": "closing-package/CD_signed_final.pdf",
        "uploadStatus": "UPLOAD_PENDING",
        "validationStatus": "PENDING",
        "ingestionStatus": "PENDING",
        "createdAt": "2026-05-28T10:00:00Z",
        "lastModifiedAt": "2026-05-28T10:00:00Z",
        "sasUploadUrl": "https://...sas...",
        "uploadMethod": "PUT",
        "sasExpiresAt": "2026-05-28T10:15:00Z",
        "existingDocument": false
      }
    ],
    "failedDocuments": [
      {
        "externalDocumentId": "DOC-BAD-001",
        "documentPublicId": null,
        "errorCode": "PDF_PAGE_COUNT_EXCEEDED",
        "errorMessage": "Document pageCount 1001 exceeds maximum allowed 1000 pages"
      }
    ]
  }
}

Response (400 Bad Request - all failed):

{
  "meta": {
    "code": 400,
    "type": "error",
    "message": "Documents registration failed"
  },
  "data": {
    "overallStatus": "FAILED",
    "successfulDocuments": [],
    "failedDocuments": [
      {
        "externalDocumentId": "DOC-BAD-001",
        "documentPublicId": null,
        "errorCode": "PDF_PAGE_COUNT_EXCEEDED",
        "errorMessage": "Document pageCount 1001 exceeds maximum allowed 1000 pages"
      }
    ]
  }
}

Complete Upload

Endpoint: POST /api/v1/{companyId}/cases/{casePublicId}/documents/{documentPublicId}:complete-upload

This endpoint does not accept a request body.

Request:

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2/documents/660e8400-e29b-41d4-a716-446655440001:complete-upload" \
  -H "Authorization: Bearer {access_token}"

Response (202 Accepted):

{
  "meta": {
    "code": 202,
    "type": "success",
    "message": "Upload completion accepted"
  },
  "data": {
    "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
    "uploadStatus": "UPLOADED",
    "validationStatus": "ENQUEUED",
    "ingestionStatus": "PENDING",
    "detectedType": null,
    "contentSize": 1024576,
    "contentHash": null,
    "diagnostics": [],
    "processedAt": "2026-05-28T10:00:00Z"
  }
}

Get Document Status

Endpoint: GET /api/v1/{companyId}/cases/{casePublicId}/documents/{documentPublicId}

Request:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/cases/8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2/documents/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "message": "Document status retrieved",
    "type": "success"
  },
  "data": {
    "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
    "casePublicId": "8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2",
    "originalFilename": "Closing_Disclosure_signed.pdf",
    "contentType": "application/pdf",
    "contentSize": 1024576,
    "uploadStatus": "UPLOADED",
    "validationStatus": "PASSED",
    "ingestionStatus": "QUEUED",
    "diagnostics": [],
    "createdAt": "2026-05-28T10:00:00Z",
    "lastModifiedAt": "2026-05-28T10:00:00Z"
  }
}

Validation failed example:

{
  "meta": {
    "code": 200,
    "message": "Document status retrieved",
    "type": "success"
  },
  "data": {
    "documentPublicId": "660e8400-e29b-41d4-a716-446655440001",
    "casePublicId": "8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2",
    "originalFilename": "not-a-pdf.txt",
    "contentType": "application/pdf",
    "contentSize": null,
    "uploadStatus": "UPLOADED",
    "validationStatus": "FAILED",
    "ingestionStatus": "NOT_APPLICABLE",
    "diagnostics": [
      {
        "code": "FILE_TOO_LARGE",
        "severity": "ERROR",
        "message": "File exceeds maximum allowed size of 200 MB"
      }
    ],
    "createdAt": "2026-05-28T10:00:00Z",
    "lastModifiedAt": "2026-05-28T10:00:00Z"
  }
}

7. Webhooks

NLDS webhooks are asynchronous notifications sent to a client-configured endpoint when selected events occur. NLDS sends webhook deliveries as HTTP POST requests with a JSON payload.

Use the webhook payload to identify the event, then call NLDS APIs if your system needs full details or final results. Webhooks may be retried, so clients must handle duplicate deliveries safely.

Supported Webhook Event Types

The table below lists the webhook events. Query completion uses a single event type; clients should read data.status to determine the outcome.

For query.completed, the outcome is returned in data.status.

Webhook HTTP Headers

NLDS sends the following headers with webhook deliveries. Clients should use these headers for routing, tracing, version handling, and deduplication.

Identifier behavior:

Do not use X-NLDS-Delivery-ID for deduplication. Use X-NLDS-Idempotency-Key instead.

Common Webhook Payload Envelope

All webhook event payloads use the same top-level envelope. Event-specific details are returned under data.

{
  "eventId": "bc1a4d7f-f162-4c7b-a77d-9a4c39e7a111",
  "eventType": "query.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-07-24T09:00:00Z",
  "companyId": 101,
  "productCode": "MORTGAGE",
  "featureScope": "NLDS_QUERY_COMPLETION",
  "idempotencyKey": "whk_idem_8f4b3c92a7d64e0b9c1a2f33",
  "correlationId": "trace-query-001",
  "data": {}
}

Clients should ignore unknown fields so that new optional fields can be added without breaking existing integrations.

Example Payloads

query.completed with SUCCESS:

{
  "eventId": "bc1a4d7f-f162-4c7b-a77d-9a4c39e7a111",
  "eventType": "query.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-07-24T09:00:00Z",
  "companyId": 101,
  "productCode": "MORTGAGE",
  "featureScope": "NLDS_QUERY_COMPLETION",
  "idempotencyKey": "whk_idem_8f4b3c92a7d64e0b9c1a2f33",
  "correlationId": "trace-query-001",
  "data": {
    "queryJobId": "b4c7d9e2-f5a8-4c1d-9e3f-5a2b8c4d7e6f",
    "casePublicId": "cf3e7ee4-c359-4d72-af81-b88854c5733f",
    "externalCaseId": "LOS-998877",
    "status": "SUCCESS",
    "completedAt": "2026-07-24T09:00:00Z"
  }
}

query.completed with PARTIAL:

{
  "eventId": "d5bd5b25-933c-47d6-9cf9-04cf13468732",
  "eventType": "query.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-07-24T09:05:00Z",
  "companyId": 101,
  "productCode": "MORTGAGE",
  "featureScope": "NLDS_QUERY_COMPLETION",
  "idempotencyKey": "whk_idem_4d2a9f0c6e814b73a58d1c20",
  "data": {
    "queryJobId": "b4c7d9e2-f5a8-4c1d-9e3f-5a2b8c4d7e6f",
    "casePublicId": "cf3e7ee4-c359-4d72-af81-b88854c5733f",
    "externalCaseId": "LOS-998877",
    "status": "PARTIAL",
    "completedAt": "2026-07-24T09:05:00Z"
  }
}

query.completed with FAILED:

{
  "eventId": "8bb421b8-0211-4bb0-a2be-845635104395",
  "eventType": "query.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-07-24T09:10:00Z",
  "companyId": 101,
  "productCode": "MORTGAGE",
  "featureScope": "NLDS_QUERY_COMPLETION",
  "idempotencyKey": "whk_idem_91c7e3b58a604f2d83a9e441",
  "correlationId": "trace-query-003",
  "data": {
    "queryJobId": "b4c7d9e2-f5a8-4c1d-9e3f-5a2b8c4d7e6f",
    "casePublicId": "cf3e7ee4-c359-4d72-af81-b88854c5733f",
    "externalCaseId": "LOS-998877",
    "status": "FAILED",
    "failedAt": "2026-07-24T09:10:00Z"
  }
}

case.ready:

{
  "eventId": "4dc7067e-4431-4ed3-b2ce-c6ac7f24d118",
  "eventType": "case.ready",
  "eventVersion": "1.0",
  "occurredAt": "2026-07-24T08:45:00Z",
  "companyId": 101,
  "productCode": "MORTGAGE",
  "featureScope": "NLDS_CASE_READINESS",
  "idempotencyKey": "whk_idem_c65e1b7429a94f8e9d30a627",
  "correlationId": "trace-case-001",
  "data": {
    "casePublicId": "cf3e7ee4-c359-4d72-af81-b88854c5733f",
    "externalCaseId": "LOS-998877",
    "caseStatus": "ACTIVE",
    "documentSummary": {
      "total": 2, 
      "indexed": 2,
      "failed": 0
    }
  }
}

Retry and Delivery Semantics

NLDS may retry webhook delivery if the client endpoint is temporarily unavailable, times out, or returns retryable errors.

Webhooks are delivered at least once. Consumers must handle duplicate deliveries using X-NLDS-Idempotency-Key. Any HTTP 2xx response is considered successful.

By default, NLDS attempts webhook delivery up to 4 total times: 1 initial attempt plus 3 retries. Retry delays increase using exponential backoff, up to a maximum delay of 5 minutes between attempts. Any HTTP 2xx response is considered successful and stops further retries. If all delivery attempts fail, NLDS stops retrying and marks the delivery as failed.

Deduplicate deliveries using X-NLDS-Idempotency-Key. If the same idempotency key is received more than once, process it once and safely ignore duplicates. Return a 2xx response only after your endpoint has safely accepted the event.

Automatic retries reuse the same X-NLDS-Delivery-ID and X-NLDS-Idempotency-Key. Manual replay creates a new delivery instance and may use a replay-specific idempotency key. Clients that need to detect that a replay belongs to the same business event should compare eventId / X-NLDS-Event-ID.

Default retry behavior:

Response Expectation

Return a 2xx status only after your endpoint has safely accepted the event. For example, store the event or enqueue it durably before responding if downstream processing is asynchronous.

8. Query Flow

This flow searches indexed case documents asynchronously. Submit a query, check the returned jobId until the query reaches a terminal status, and then retrieve the query results.

All query API responses use the standard envelope:

{
  "meta": {
    "code": 200,
    "type": "success",
    "message": "success"
  },
  "data": {}
}

Client-facing query status values are:

Submit Query

Endpoint: POST /api/v1/{companyId}/query

Submit natural-language text, a structured checkList, or both. At least one of query or checkList is required. When both are provided, the checkList defines the required document criteria, while the natural-language query is used to refine and rank matching results.

Send the optional idempotency key in the X-NLDS-Idempotency-Key header. Do not send it in the request body. If the same idempotency key is submitted again while the original query is still active, NLDS returns the existing jobId instead of creating a new query job.

Request:

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/query" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "X-NLDS-Idempotency-Key: query-20260819-183011" \
  -d '{
    "query": "latest signed Closing Disclosure for Mike",
    "casePublicId": "8d5a3e7c-9f21-4a2c-b8e1-d7c6f5a4e3b2",
    "checkList": [
      {
        "itemId": "REQ-CD-SIGNED",
        "docType": "closing_disclosure",
        "filters": {
          "isSigned": true,
          "applicantName": "Mike",
          "docDateFrom": "2026-01-01",
          "docDateTo": "2026-06-30"
        }
      }
    ]
  }'

Response (202 Accepted):

{
  "meta": {
    "code": 202,
    "type": "success",
    "message": "accepted"
  },
  "data": {
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "ACCEPTED",
    "idempotencyKey": "query-20260819-183011",
    "sandbox": false
  }
}

Clients should retain the returned jobId for subsequent status and result requests.

Check Query Status

Endpoint: GET /api/v1/{companyId}/query/{jobId}/status

Call this endpoint using an appropriate backoff strategy until status reaches one of the terminal states: SUCCESS, PARTIAL, FAILED, or CANCELLED.

Request:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/query/3fa85f64-5717-4562-b3fc-2c963f66afa6/status" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "type": "success",
    "message": "success"
  },
  "data": {
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "SUCCESS",
    "sandbox": false
  }
}

Get Query Results

Endpoint: GET /api/v1/{companyId}/query/{jobId}/results

Read the query answer after the job reaches a terminal status. If the query has not yet completed, the endpoint may return an empty result set rather than an error.

checkListSummary contains one result entry for each submitted checklist item, preserving the original submission order. results contains the documents that matched the submitted query criteria with the client's own externalDocumentId or sourceSystemPath when those were supplied during upload.

Results do not include storage URLs or SAS tokens. Use the document access endpoint for file access.

Request:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/query/3fa85f64-5717-4562-b3fc-2c963f66afa6/results" \
  -H "Authorization: Bearer {access_token}"

Response (200 OK):

{
  "meta": {
    "code": 200,
    "type": "success",
    "message": "success"
  },
  "data": {
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "SUCCESS",
    "checkListSummary": [
      {
        "itemId": "REQ-CD-SIGNED",
        "submittedDocType": "closing_disclosure",
        "docType": "closing_disclosure",
        "status": "FOUND"
      }
    ],
    "pendingDocumentCount": 0,
    "failedDocumentCount": 0,
    "results": [
      {
        "docType": "closing_disclosure",
        "pageRanges": [],
        "caseDocumentId": "cd-4471",
        "fileName": "closing_package.pdf",
        "externalDocumentId": null,
        "sourceSystemPath": null
      }
    ],
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "queriedAt": "2026-08-19T18:32:04Z",
    "sandbox": false
  }
}

Sandbox Quick Start

Sandbox mode lets you test the query workflow without uploading or indexing real documents. Use it to validate request structure, authentication, status, result parsing, query activity filtering, and webhook handling against a predictable response.

Sandbox behavior is controlled by the product's sandbox flag. When you create a case under a sandbox-enabled product and submit a query, NLDS accepts the request through the same query endpoint used in production, but returns a predefined terminal result instead of running the normal document search pipeline.

1. Create a case under the sandbox product

Create a normal case using the sandbox product code.

{
  "productCode": "MORTGAGE_SANDBOX",
  "externalCaseId": "SANDBOX-CASE-001",
  "displayName": "Sandbox Query Test"
}

Store the returned casePublicId.

2. Submit a query

Use the same query endpoint documented above.

curl -X POST "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/query" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest signed Closing Disclosure",
    "casePublicId": "{sandbox_case_public_id}",
    "checkList": [
      {
        "itemId": "REQ-CD-SIGNED",
        "docType": "closing_disclosure",
        "filters": {
          "isSigned": true
        }
      }
    ]
  }'

3. Retrieve the sandbox query result

A sandbox query returns a terminal SUCCESS result immediately.

{
  "meta": {
    "code": 202,
    "type": "success",
    "message": "accepted"
  },
  "data": {
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "SUCCESS",
    "sandbox": true
  }
}

Then call the results endpoint with the returned jobId.

{
  "meta": {
    "code": 200,
    "type": "success",
    "message": "success"
  },
  "data": {
    "jobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "SUCCESS",
    "checkListSummary": [
      {
        "itemId": "REQ-CD-SIGNED",
        "submittedDocType": "closing_disclosure",
        "docType": "closing_disclosure",
        "status": "FOUND"
      }
    ],
    "pendingDocumentCount": 0,
    "failedDocumentCount": 0,
    "results": [
      {
        "docType": "closing_disclosure",
        "pageRanges": [
          "1-1"
        ],
        "caseDocumentId": "5d0f2a18-9c41-4f7b-8a63-1e2c4b5d6f70",
        "fileName": "closing-disclosure.pdf",
        "externalDocumentId": "sandbox-doc-1",
        "sourceSystemPath": "sandbox/MORTGAGE_SANDBOX/closing-disclosure.pdf"
      }
    ],
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "queriedAt": "2026-08-19T18:32:04Z",
    "sandbox": true
  }
}

4. Verify sandbox query activity

Sandbox queries appear in query activity. Use the sandbox=true filter to view only practice queries:

curl -X GET "https://nlsearch-api.digilytics.solutions/nldocsearch/api/v1/123456/queries?sandbox=true&page=0&size=20" \
  -H "Authorization: Bearer {access_token}"

5. Verify sandbox webhook delivery

Sandbox queries still reach terminal SUCCESS, so a query.completed webhook can be delivered when a matching webhook subscription is configured. The webhook payload follows the same envelope documented in the Webhooks section and includes eventType: "query.completed" with query identifiers under data. See Webhook HTTP Headers for the headers sent with each delivery.

{
  "eventType": "query.completed",
  "featureScope": "NLDS_QUERY_COMPLETION",
  "data": {
    "queryJobId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "casePublicId": "{sandbox_case_public_id}",
    "status": "SUCCESS",
    "completedAt": "2026-08-24T16:07:39.383472613Z"
  }
}

Use sandbox mode to validate request structure, response parsing, status handling, idempotency behavior, query activity filtering, and webhook integration.