# NYS DOCCS In-Custody Details (`jippylong12/nys-doccs-in-custody-details`) Actor Enriches a completed NYS DOCCS Basic Snapshot dataset by keeping IN CUSTODY records and fetching per-DIN custody, sentence, parole, crime, facility, and provenance details. Requires a successful Basic Snapshot dataset as input. - **URL**: https://apify.com/jippylong12/nys-doccs-in-custody-details.md - **Developed by:** [Marcus Salinas](https://apify.com/jippylong12) (community) - **Categories:** Automation, Other - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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](https://apify.com/jippylong12/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. ```json [ { "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 ```json { "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](https://apify.com/jippylong12/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. # Actor input Schema ## `sourceDatasetId` (type: `string`): Required upstream basic snapshot dataset. This requests READ access so the Actor can consume a completed source dataset while still running under limited permissions. ## `sourceRunId` (type: `string`): Optional upstream basic snapshot run ID for provenance. In production this should come from {{resource.id}} on the Actor-to-Actor integration. ## `resumeMode` (type: `string`): Auto resumes the current unfinished detail logical run for the same source dataset. Force new abandons the previous unfinished logical run and starts a fresh detail run. ## `workerCount` (type: `integer`): Number of parallel DIN detail workers. Keep this conservative because each worker uses residential proxy traffic and its own cookie-backed session. ## `requestDelayMs` (type: `integer`): Base pacing delay applied independently inside each detail worker session before requests. ## `delayJitterMs` (type: `string`): Optional fixed integer or min-max range added to requestDelayMs on every request. Default 250-500. ## `sessionRotationEveryItems` (type: `integer`): Rotate each worker's residential proxy session after this many DIN detail lookups. ## `checkpointEveryItems` (type: `integer`): Persist the next unprocessed item index after this many newly committed DINs, plus on clean worker boundaries. ## `retainedCompletedRuns` (type: `integer`): How many completed named final datasets to keep after cleanup. Older retained copies are deleted automatically. ## `sampleRowLimit` (type: `integer`): How many sample enriched rows to include in the final OUTPUT summary record. ## Actor input object example ```json { "resumeMode": "auto", "workerCount": 4, "requestDelayMs": 3000, "delayJitterMs": "250-500", "sessionRotationEveryItems": 100, "checkpointEveryItems": 25, "retainedCompletedRuns": 2, "sampleRowLimit": 10 } ``` # Actor output Schema ## `results` (type: `string`): Clean final default dataset of unique in-custody DIN records enriched through SearchByDin, including detail fields, flattened crime fields, source snapshot provenance, detail status, and any row-level error. ## `summary` (type: `string`): JSON run summary stored as OUTPUT in the default key-value store, including source dataset ID, optional source run ID, counts, failures, retained dataset name, transport usage, and sample rows. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("jippylong12/nys-doccs-in-custody-details").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("jippylong12/nys-doccs-in-custody-details").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call jippylong12/nys-doccs-in-custody-details --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jippylong12/nys-doccs-in-custody-details", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "NYS DOCCS In-Custody Details", "description": "Enriches a completed NYS DOCCS Basic Snapshot dataset by keeping IN CUSTODY records and fetching per-DIN custody, sentence, parole, crime, facility, and provenance details. Requires a successful Basic Snapshot dataset as input.", "version": "0.4", "x-build-id": "xrfh0DjjskXWMIfjx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jippylong12~nys-doccs-in-custody-details/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jippylong12-nys-doccs-in-custody-details", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/jippylong12~nys-doccs-in-custody-details/runs": { "post": { "operationId": "runs-sync-jippylong12-nys-doccs-in-custody-details", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/jippylong12~nys-doccs-in-custody-details/run-sync": { "post": { "operationId": "run-sync-jippylong12-nys-doccs-in-custody-details", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "sourceDatasetId" ], "properties": { "sourceDatasetId": { "title": "Source dataset", "minLength": 1, "type": "string", "description": "Required upstream basic snapshot dataset. This requests READ access so the Actor can consume a completed source dataset while still running under limited permissions." }, "sourceRunId": { "title": "Source run ID", "minLength": 1, "type": "string", "description": "Optional upstream basic snapshot run ID for provenance. In production this should come from {{resource.id}} on the Actor-to-Actor integration." }, "resumeMode": { "title": "Resume mode", "enum": [ "auto", "forceNew" ], "type": "string", "description": "Auto resumes the current unfinished detail logical run for the same source dataset. Force new abandons the previous unfinished logical run and starts a fresh detail run.", "default": "auto" }, "workerCount": { "title": "Worker count", "minimum": 1, "maximum": 12, "type": "integer", "description": "Number of parallel DIN detail workers. Keep this conservative because each worker uses residential proxy traffic and its own cookie-backed session.", "default": 4 }, "requestDelayMs": { "title": "Delay between requests per worker (ms)", "minimum": 0, "type": "integer", "description": "Base pacing delay applied independently inside each detail worker session before requests.", "default": 3000 }, "delayJitterMs": { "title": "Per-request jitter (ms)", "pattern": "^\\d+(\\s*-\\s*\\d+)?$", "type": "string", "description": "Optional fixed integer or min-max range added to requestDelayMs on every request. Default 250-500.", "default": "250-500" }, "sessionRotationEveryItems": { "title": "Session rotation every items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Rotate each worker's residential proxy session after this many DIN detail lookups.", "default": 100 }, "checkpointEveryItems": { "title": "Checkpoint every items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Persist the next unprocessed item index after this many newly committed DINs, plus on clean worker boundaries.", "default": 25 }, "retainedCompletedRuns": { "title": "Retained completed runs", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many completed named final datasets to keep after cleanup. Older retained copies are deleted automatically.", "default": 2 }, "sampleRowLimit": { "title": "Sample rows in OUTPUT", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many sample enriched rows to include in the final OUTPUT summary record.", "default": 10 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```