Detection

The Detection endpoints run sensitive-entity detection against a previously uploaded PDF. The response contains the detected entities (text, label, page position, and confidence score) inline in the result object, and a reference to an FDF file produced by the job and stored on the Manager. Both are needed to start a redaction job: the entity list is passed inline as redactionInput, and the FDF reference is passed as fdfFileId and fdfDekToken. The FDF itself only needs to be downloaded when the entities need to be reviewed or modified visually in a PDF viewer before redaction. The cURL examples use the Manager’s default address (http://localhost:9982); substitute the host and port of your deployment as needed.

Sync and async processing

Each detection request specifies a processingMode:

• sync — the request blocks until detection completes. The response is 200 with the full result.
• async — the request returns 202 immediately with a jobId. Use the result endpoint to poll until jobStatus is finished or error.

Use sync for small, interactive flows. Use async for large documents that would exceed HTTP timeouts in sync mode, or when starting many jobs in parallel.

Detection configuration

The optional detectionConfiguration field on the request overrides the built-in detection defaults for that single request. Use it to add custom recognizers, change the score threshold, or supply keyword exclusions. When omitted, the built-in defaults are used.

For the full schema and the available options, refer to Detection configuration.

Endpoints

Start a detection job

POST /v1/jobs/detection

Detects sensitive entities in a previously uploaded PDF. The behavior depends on processingMode: sync blocks until the result is ready; async returns immediately with a jobId for polling.

Request body — DetectionRequest.

Response — DetectionResponse.

Status codes:

Code	Meaning
200	Sync only. The job completed and the response contains the full result.
202	Async only. The job was accepted and is running. Poll the result endpoint with the returned jobId.
400	The request was malformed, or pdfFileId and dekToken don’t match an existing file.
404	No file with the given pdfFileId exists.
429	Admission control rejected the request because too many jobs are pending.
503	The job couldn’t be dispatched to a worker.

Sync example:

curl -X POST "http://localhost:9982/v1/jobs/detection" \
  -H "Content-Type: application/json" \
  -d "{\"processingMode\": \"sync\", \"pdfFileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}"

Async example:

curl -X POST "http://localhost:9982/v1/jobs/detection" \
  -H "Content-Type: application/json" \
  -d "{\"processingMode\": \"async\", \"pdfFileId\": \"$FILE_ID\", \"dekToken\": \"$DEK_TOKEN\"}"

Get the result of a detection job

GET /v1/jobs/detection/{jobId}/result

Returns the current state of an async detection job. Poll this endpoint until jobStatus is finished or error. The response uses the same shape whether the job is still in progress or has completed.

Path parameters:

Name	Type	Description
jobId	string (UUID)	The jobId returned by the start-job request.

Response — DetectionResponse.

Status codes:

Code	Meaning
200	The job has finished. The response contains the full result.
202	The job is still running. Poll again.
400	The request was malformed.
404	No job with the given jobId exists.

Example:

curl "http://localhost:9982/v1/jobs/detection/$JOB_ID/result"

Schemas

DetectionRequest schema

Field	Type	Description
processingMode	ProcessingMode	Whether the request blocks until the job completes (sync) or returns immediately for polling (async).
pdfFileId	string (UUID)	Identifier of the previously uploaded PDF, returned by an upload endpoint.
dekToken	string	DEK token returned alongside the pdfFileId at upload time.
detectionConfiguration	DetectionConfiguration	Optional. Overrides the built-in detection defaults for this request. When omitted, the built-in defaults are used.

DetectionResponse schema

Field	Type	Description
jobId	string (UUID)	Identifier of the job. Use it to poll the result endpoint.
jobType	JobType	Always detection for this endpoint.
jobStatus	JobStatus	Current state of the job.
error	ApiErrorResponse	Set when jobStatus is error. Otherwise omitted.
outputFiles	array of FileResult	References to files produced by the job. For detection, contains one entry pointing at the FDF file with the detected entities as visual annotations. Pass fileId and dekToken as fdfFileId and fdfDekToken on a redaction request. Empty until the job is finished.
result	DetectionResult	Detected entities returned inline. The same set is encoded in the FDF file referenced by outputFiles. Empty until the job is finished.

DetectionResult schema

Field	Type	Description
redactions	array of RedactionEntityDto	Detected entities. The same set is encoded in the FDF file in outputFiles.

RedactionEntityDto schema

Field	Type	Description
pageIndex	integer	Zero-based page index where the entity appears.
text	string	The matched text. Required.
label	string	The entity type, for example EMAIL_ADDRESS or PERSON. Required.
score	number	Confidence score between 0 and 1.
quadrilaterals	array of QuadrilateralDto	On-page bounding regions for the entity.

QuadrilateralDto schema

All four corners are required. Quadrilaterals can describe rotated or skewed text regions, not only axis-aligned rectangles.

Field	Type	Description
bottomLeft	PointDto	Bottom-left corner.
bottomRight	PointDto	Bottom-right corner.
topRight	PointDto	Top-right corner.
topLeft	PointDto	Top-left corner.

PointDto schema

Field	Type	Description
x	number	X coordinate in PDF user-space points.
y	number	Y coordinate in PDF user-space points.

FileResult schema

Field	Type	Description
fileId	string (UUID)	Identifier of the result file.
fileCode	string	Role of the file in the job result.
size	integer	File size in bytes.
dekToken	string	DEK token required to download or use the result file.
dekTokenExpiresAt	string (UTC date-time)	Expiration of the DEK token.

JobStatus enum

Value	Description
inProgress	The job is running.
finished	The job completed successfully. The result is available in outputFiles and result.
error	The job failed. The cause is available in error.

JobType enum

Value	Description
detection	A detection job.
redaction	A redaction job.

ProcessingMode enum

Value	Description
sync	The request blocks until the job completes.
async	The request returns immediately with a jobId. Poll the result endpoint until jobStatus is finished or error.