How to Bulk-Restore Deleted Items by Date Range

This guide explains the algorithm behind bulk-restoring deleted items by date range. It walks through every stage in execution order and shows the exact API calls at each step.

Overview

The algorithm consists of the following stages:

1. Search — find every deleted item in the date window using the bsearch API.
2. Coalesce — group items by the snapshot timestamp they were last seen in.
3. Snapshot lookup — resolve each timestamp group to a concrete snapshot ID.
4. Submit — POST one restore job per group.
5. Verify (optional) — confirm each job was accepted and track its progress.

Stage 1 — Search for Deleted Items

See the Search Backup page for details.

Use the bsearch endpoint to find all deleted items within a date window. The window is matched against each item's snapshot timestamp — the <updated> value in the results (Stage 2): an item is returned when the snapshot in which it was last seen falls between snaptimeFrom and snaptimeTo.

Set the following query parameters:

Optionally, you can paginate through the results: request one page of count items at a time, increasing startIndex by count for each next page, until a page returns fewer than count items. For example, with count=100, request startIndex=0, then 100, then 200, and so on. Combine the <entry> elements from every page into a single result set for Stage 2.

pathRoot by item type

The pathRoot value depends on the item type being restored.

Email:

Code
/Users/{userIdentity}/Outlook/{folderName}

Where userIdentity is the user's UPN or Keepit user ID, and folderName is the mailbox folder to search (e.g. Inbox, Sent, or Deleted Items).

Note: Paths are case-sensitive and must be localized — if the mailbox language isn't English, use the localized folder name (Inbox is not converted automatically).

User objects:

Code
/Users

Search at the top-level Users folder. After retrieving results, filter client-side: keep only items whose title field contains the target UPN. This handles the case where a user was deleted and recreated with a new user ID.

OneDrive:

Code
/Users/{userIdentity}/{pathFromRoot}

If the search returns zero results, retry with the alternate OneDrive path:

• If pathFromRoot starts with OneDrive: /Users/{userIdentity}/OneDriveSP/DocLibs/Documents/Content
• Otherwise: /Users/{userIdentity}/OneDrive

SharePoint:

Code
/SharePoint/{encodedSiteUrl}

Omit /{encodedSiteUrl} to search across all SharePoint sites. To target one site, set encodedSiteUrl to the escape-masked site URL. For example, https://m365x47291058.sharepoint.com/sites/allcompany becomes /SharePoint/https-c-s-sm365x47291058.sharepoint.com-ssites-sallcompany.

Groups & Teams:

Code
/Groups/{groupId}

Omit /{groupId} to search across all groups. To target one group, set groupId to the escape-masked group GUID. For example, /Groups/f3a1b2c4--d7e8--4f91--a023--b6c5d4e3f2a1.

Path segment encoding

Special characters inside individual path segments must be escaped before building pathRoot. See Escape Masking for the full rules and examples.

Code
curl -s -u "{username}:{password}" \
  "https://{baseUrl}/users/{accountId}/bsearch\
        ?apiVersion=2\
        &device={connectorId}\
        &pathRoot={pathRoot}\
        &filterAnd=AND:deleted;\
        &snaptimeFrom={iso8601}\
        &snaptimeTo={iso8601}\
        &recursive={recursive}\
        &count={count}\
        &startIndex=0"

Code
GET https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/bsearch?apiVersion=2&device=ou1ab2-3cde4-fg5hi6&pathRoot=/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p/Outlook/Inbox&filterAnd=AND:deleted;&snaptimeFrom=2026-07-01T00:00:00Z&snaptimeTo=2026-07-23T23:59:59Z&recursive=1&count=100&startIndex=0

Code
<feed>
  <opensearch:totalResults>142</opensearch:totalResults>
  <entry>
    <id>kng://{connectorId}/Users/{user}/Outlook/Inbox/...</id>
    <title>Q1 budget review</title>
    <updated>2026-07-22T09:15:13Z</updated>
    <deleted/>
  </entry>
  …
</feed>

[!TIP] <updated> is a UTC ISO 8601 timestamp identifying the snapshot in which the item was last seen — you will need this value in Stage 2. <opensearch:totalResults> gives the total match count across all pages.

Stage 2 — Coalesce by Snapshot Timestamp

Take the items collected in Stage 1 and group them by their <updated> value. Each distinct <updated> timestamp corresponds to a different backup snapshot, and all items sharing that timestamp can be restored together in a single job — far more efficient than one job per item.

The grouping, in illustrative Python (deletedItems is the Stage 1 result set):

Code
# deletedItems : every <entry> collected in Stage 1
# item.Updated : that entry's <updated> value
groups = {}
for item in deletedItems:
    groups[item.Updated] = groups.get(item.Updated, []) + [item]

The result is a map of snapshot timestamp → list of items, where each item still carries its full <id> from Stage 1. The timestamp key drives the snapshot lookup in Stage 3; each item's <id> becomes a <Path> in Stage 4. For example, items last seen across two snapshots collapse into two groups:

Code
2026-07-22T09:15:13Z → [ kng://{connectorId}/Users/…/Outlook/Inbox/AAMkAD…,
                         kng://{connectorId}/Users/…/Outlook/Inbox/AAMkAE…,
                         …  (26 items in total) ]
2026-07-22T09:00:20Z → [ kng://{connectorId}/Users/…/Outlook/Inbox/AAMkAF…,
                         …  (4 items in total) ]

Carry each group into Stage 3 independently — one snapshot lookup per group.

Stage 3 — Resolve Snapshot IDs

See the [Retrieve Snapshot History Range] page for details.

For each timestamp group you need the snapshot ID that corresponds to that point in time. Query the snapshot history range endpoint backwards from the group's <updated> timestamp (UTC ISO 8601).

Send the following <range> body:

Code
curl -s -u "{username}:{password}" \
  -X PUT \
  -H "Content-Type: application/xml" \
  -d '<range>
        <start>{updated}</start>
        <span>P30D</span>
        <count>1</count>
        <reverse/>
      </range>' \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/history/range"

Code
PUT https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/history/range

Code
<range>
  <start>2026-07-22T09:15:13Z</start>
  <span>P30D</span>
  <count>1</count>
  <reverse/>
</range>

Code
<history>
  <backup>
    <tstamp>2026-07-22T09:05:43Z</tstamp>
    <root>c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4</root>
    <type>c</type>
    <size>1653770815</size>
    <account>ab1cd2-3efgh4-ij5klm</account>
  </backup>
</history>

Repeat this call once per distinct timestamp group. Each group will yield its own snapshot ID, which is used independently in Stage 4.

Stage 4 — Build and Submit Restore Jobs

See the Create Device Job page for details.

For each timestamp group, construct the XML job definition and POST it to the API.

Build the following <job> body:

XML job definition

Code
<job>
  <description>Bulk Restore ({type}) - {N} items</description>
  <type>srestore</type>
  <immediate/>
  <priority>1</priority>
  <commands>
    <restore>
      <RestoreConfig>
        <SnapshotId>{snapshotId}</SnapshotId>
        <Rules>
          <Mode>
            <FolderRestoreMode>DeltaAppend</FolderRestoreMode>
            <FileConflictResolutionMode>Restore</FileConflictResolutionMode>
            <Method>InPlace</Method>
          </Mode>
          <RestorePaths>
            <Path>{xmlEscapedPath1}</Path>
            <Path>{xmlEscapedPath2}</Path>
          </RestorePaths>
        </Rules>
      </RestoreConfig>
    </restore>
  </commands>
</job>

Path values inside <Path> elements:

Strip the kng://{connectorId} prefix from item.Id to get the bare path, then XML-escape the result as defined by the XML specification (encode &, <, >, ", and ' as their XML entities).

Code
curl -s -u "{username}:{password}" \
  -X POST \
  -H "Content-Type: application/xml" \
  -d '<job>...</job>' \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/jobs/"

Code
POST https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/jobs/

Code
<job>
  <description>Bulk Restore (Email) - 2 items</description>
  <type>srestore</type>
  <immediate/>
  <priority>1</priority>
  <commands>
    <restore>
      <RestoreConfig>
        <SnapshotId>c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4</SnapshotId>
        <Rules>
          <Mode>
            <FolderRestoreMode>DeltaAppend</FolderRestoreMode>
            <FileConflictResolutionMode>Restore</FileConflictResolutionMode>
            <Method>InPlace</Method>
          </Mode>
          <RestorePaths>
            <Path>/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p/Outlook/Inbox/AAMkAD...</Path>
            <Path>/Users/a1b2c3d4--e5f6--78gh--i9j0--12kl3m4n5o6p/Outlook/Inbox/AAMkAE...</Path>
          </RestorePaths>
        </Rules>
      </RestoreConfig>
    </restore>
  </commands>
</job>

Stage 5 — Verify the Restore Jobs (optional)

See the List Device Jobs page for details.

To confirm the jobs were accepted and track their progress, query the jobs endpoint and match on the description you set in Stage 4.

Code
curl -s -u "{username}:{password}" \
  "https://{baseUrl}/users/{accountId}/devices/{connectorId}/jobs"

Code
GET https://dk-co.keepit.com/users/ab1cd2-3efgh4-ij5klm/devices/ou1ab2-3cde4-fg5hi6/jobs

Code
<jobs>
  <job>
    <guid>9ab1c2-de3fg4-hi5jk6-lm7nop</guid>
    <description>Bulk Restore (Email) - 2 items</description>
    <type>srestore</type>
    <priority>1</priority>
    <active>false</active>
    <started>2026-07-23T08:43:54Z</started>
    <succeeded>2026-07-23T08:44:00Z</succeeded>
    <progress>1.0</progress>
  </job>
</jobs>