NYS DOCCS In-Custody Details

NYS DOCCS In-Custody Details is the second step in the NYS DOCCS workflow. It enriches the in-custody rows from a successful NYS DOCCS Basic Snapshot run with detailed per-DIN custody data.

This Actor does not crawl the full DOCCS corpus by itself. It will not produce useful output as a standalone run without a completed Basic Snapshot default dataset supplied as sourceDatasetId.

Output

The default dataset is an array of enriched in-custody records. A full run from a current full Basic Snapshot usually returns about 20,000 to 30,000 enriched records. Counts change as DOCCS updates the public lookup.

[
  {
    "din": "22B4926",
    "name": "ADAIR, ISAIAH T",
    "dateOfBirth": "08/06/1998",
    "age": "27 years old",
    "race": "UNKNOWN",
    "minSentence": "0 Years, 0 Months, 0 Days",
    "maxSentence": "7 Years, 0 Months, 0 Days",
    "earliestReleaseDate": "10/27/2027",
    "earliestReleaseType": "CONDITIONAL RELEASE DATE",
    "paroleHearingDate": "08/2027",
    "paroleHearingType": "RELEASE CONDITIONS",
    "condReleaseDate": "10/27/2027",
    "maxExpDate": "10/27/2028",
    "status": "IN CUSTODY",
    "facility": "AUBURN",
    "origRecDate": "11/18/2022",
    "curRecDate": "04/25/2024",
    "admType": "RETURN FROM ANOTHER AGENCY",
    "county": "SCHENECTADY",
    "crime1": "ARSON 2ND",
    "crimeClass1": "B",
    "otherDins": "22B4926",
    "otherNames": "ADAIR, ISAIAH T",
    "detailStatus": "ok",
    "detailFetchedAt": "2026-04-28T23:41:17.668Z",
    "sourceDatasetId": "aqDqHYjjsXe3JP7Dz",
    "sourceRunId": "w0PoNBDMl8gTHdzJo",
    "sourceName": "ADAIR, ISAIAH T",
    "sourceStatus": "IN CUSTODY",
    "sourceFacility": "AUBURN",
    "sourceDateOfBirth": "08/06/1998",
    "sourceAge": "27 years old",
    "sourceRace": "UNKNOWN",
    "sourceSearchPrefix": "AD",
    "sourcePageNumber": 1,
    "sourceClickNextDinUsed": "",
    "sourceScrapedAt": "2026-04-28T21:18:00.077Z",
    "sourceEndpoint": "https://nysdoccslookup.doccs.ny.gov/IncarceratedPerson/SearchByName"
  }
]

Dataset Schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "din": { "type": "string" },
      "nysid": { "type": "string" },
      "name": { "type": "string" },
      "dateOfBirth": { "type": "string" },
      "age": { "type": "string" },
      "race": { "type": "string" },
      "releaseDate": { "type": "string" },
      "minSentence": { "type": "string" },
      "maxSentence": { "type": "string" },
      "earliestReleaseDate": { "type": "string" },
      "earliestReleaseType": { "type": "string" },
      "paroleHearingDate": { "type": "string" },
      "paroleHearingType": { "type": "string" },
      "paroleEligDate": { "type": "string" },
      "condReleaseDate": { "type": "string" },
      "maxExpDate": { "type": "string" },
      "maxExpDateForParole": { "type": "string" },
      "postReleaseSupervisionMaxExpDate": { "type": "string" },
      "paroleBoardDischargeDate": { "type": "string" },
      "status": { "type": "string" },
      "facility": { "type": "string" },
      "origRecDate": { "type": "string" },
      "curRecDate": { "type": "string" },
      "admType": { "type": "string" },
      "county": { "type": "string" },
      "latestRelDate": { "type": "string" },
      "latestRelType": { "type": "string" },
      "crime1": { "type": "string" },
      "crime2": { "type": "string" },
      "crime3": { "type": "string" },
      "crime4": { "type": "string" },
      "crimeClass1": { "type": "string" },
      "crimeClass2": { "type": "string" },
      "crimeClass3": { "type": "string" },
      "crimeClass4": { "type": "string" },
      "otherDins": { "type": "string" },
      "otherNames": { "type": "string" },
      "detailUserDisplayableMessage": { "type": "string" },
      "detailStatus": { "type": "string" },
      "detailFetchedAt": { "type": "string", "format": "date-time" },
      "detailFetchError": { "type": "string" },
      "sourceDatasetId": { "type": "string" },
      "sourceRunId": { "type": "string" },
      "sourceName": { "type": "string" },
      "sourceStatus": { "type": "string" },
      "sourceFacility": { "type": "string" },
      "sourceDateOfBirth": { "type": "string" },
      "sourceAge": { "type": "string" },
      "sourceRace": { "type": "string" },
      "sourceSearchPrefix": { "type": "string" },
      "sourcePageNumber": { "type": "integer" },
      "sourceClickNextDinUsed": { "type": "string" },
      "sourceScrapedAt": { "type": "string", "format": "date-time" },
      "sourceEndpoint": { "type": "string" }
    }
  }
}

Fields with no source value may be omitted or returned empty depending on export format. The sample above removes null fields so the shape is easier to read.

The Actor also writes an OUTPUT key-value store record with run status, source dataset provenance, counts, failures, retained dataset name, transport usage, and sample rows.

Required Workflow

This Actor is intended to run after Basic Snapshot, not alone.

Recommended manual workflow:

1. Run NYS DOCCS Basic Snapshot.
2. Wait for the Basic Snapshot run to finish successfully.
3. Open the successful Basic Snapshot run and copy/select its default dataset.
4. Start NYS DOCCS In-Custody Details the same day.
5. In the sourceDatasetId input, select the Basic Snapshot default dataset.
6. Optionally pass the Basic Snapshot run ID as sourceRunId for provenance.
7. Leave resumeMode as auto unless you intentionally want to abandon an unfinished detail run and start fresh.

Recommended integration workflow:

1. Create a task for Basic Snapshot.
2. Create a task for In-Custody Details.
3. On the Basic Snapshot task, add an Actor-to-Actor integration that runs Details only on successful completion.
4. Pass these values into Details:
   • sourceDatasetId = {{resource.defaultDatasetId}}
   • sourceRunId = {{resource.id}}
5. Run Basic Snapshot. When it succeeds, Apify starts Details with read access to the correct source dataset.

If sourceDatasetId is missing or points to the wrong dataset, this Actor cannot build the in-custody worklist and will not produce the intended data.

Expected Runtime

A full Details run usually takes about 9 to 12 hours with default production settings. It is slower than Basic Snapshot because it performs a per-DIN detail lookup for each in-custody record with conservative pacing and retry handling.

Run Details the same day as Basic Snapshot when possible. The Basic dataset is the source list of DINs, and the Details actor fetches current per-DIN detail records from that source list.

How It Works

This Actor is the enrichment step for a successful Basic Snapshot run:

1. Reads the Basic Snapshot default dataset selected in sourceDatasetId.
2. Keeps only rows marked IN CUSTODY.
3. Removes duplicate DINs so each person is processed once.
4. Looks up the public detail record for each DIN with conservative pacing and retry handling.
5. Combines the detail data with source provenance from the Basic Snapshot.
6. Tracks progress so interrupted runs can resume safely.
7. On completion, publishes a clean default dataset for export.

The internal staging data is not the product output. Use the completed run's default dataset as the final enriched Details export.

Input

• sourceDatasetId: required Basic Snapshot default dataset selected through the dataset picker.
• sourceRunId: optional Basic Snapshot run ID for provenance.
• resumeMode: auto resumes an unfinished detail run for the same source dataset; forceNew starts fresh.
• workerCount: parallel DIN detail workers.
• requestDelayMs: base delay between requests per worker.
• delayJitterMs: fixed integer or min-max jitter range.
• sessionRotationEveryItems: rotate residential proxy/session after this many DINs.
• checkpointEveryItems: persist progress after this many newly committed DINs.
• retainedCompletedRuns: number of completed retained final datasets to keep.
• sampleRowLimit: number of sample rows copied into the final OUTPUT summary.

Reliability And Failure Behavior

• A few failed DINs do not fail the entire run.
• Failed DINs are emitted with detailStatus = failed and detailFetchError.
• The run checkpoints the next unprocessed committed item index.
• Interrupted runs resume from the checkpoint by default.
• Graceful aborts publish partial output from already staged rows.
• A circuit breaker stops the run only when recent failures look systemic.