Core Request API

This page covers the request lifecycle endpoints that are not already documented in the dedicated verification, manifest, delivery, appeals, audit, subject, and retention pages.

Shared Intake Payload

Request creation and capture use the same intake body:

• jurisdiction (string, required)
• intakeSource (object, required)
• intakeSource.channel (string, required)
• intakeSource.rawText (string, required)
• intakeSource.receivedAt (string, required)
• intakeSource.contact (string, optional)
• intakeSource.sourceEvidence (array, optional)
• requestor (object, optional)
• requestor.type (string, required when present)
• requestor.name (string, optional)
• requestor.email (string, optional)
• requestor.relation (string, optional)
• authority (object, optional)
• authority.evidenceArtifacts (array, required when present)
• authority.status (string, required when present)
• authority.verifiedAt (string, optional)
• receivedAt (string, optional)

intakeSource.receivedAt is the timestamp from the original external intake channel and is required for provenance. The top-level receivedAt is the time DSAR recorded or ingested the request and may be later than the intake-source timestamp or omitted entirely.

POST /requests

Create a request.

Response (202):

{
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"status": "received"
}

POST /requests/capture

Capture intake and return due-date context immediately.

Response (202):

{
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"status": "received"
}

GET /requests

List requests in the queue.

Query parameters:

• limit (number, optional)
• offset (number, optional)
• status (string, optional)
• sortBy (string, optional)
• sortOrder (string, optional)
• atRiskDays (number, optional)

Response (200):

{
	"items": [],
	"limit": 25,
	"offset": 0,
	"sortBy": "receivedAt",
	"sortOrder": "desc",
	"total": 0
}

GET /requests/:id

Return a request detail record.

Response (200):

{
	"appeals": [],
	"authority": {
		"evidenceArtifacts": [],
		"status": "not_required"
	},
	"clockMode": "active",
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"receivedAt": "2026-01-01T00:00:00.000Z",
	"requestor": {
		"type": "subject"
	},
	"status": "in_progress"
}

GET /requests/:id/timeline

Return the request timeline.

Response (200):

{
	"events": [
		{
			"createdAt": "2026-01-01T00:00:00.000Z",
			"eventType": "request_created",
			"id": "evt-123",
			"payload": {}
		}
	],
	"requestId": "req-123"
}

GET /requests/:id/clock/explain

Explain how DSAR calculated the current deadline.

The response includes the base deadline, final due date, policy pack/version, extensions, pauses, and segmented legal-clock history.

Response (200):

{
	"baseDeadline": "2026-01-31T00:00:00.000Z",
	"clock": {
		"clockMode": "receipt",
		"dueAt": "2026-02-05T00:00:00.000Z",
		"receivedAt": "2026-01-01T00:00:00.000Z",
		"segments": [
			{
				"actor": "system",
				"countsTowardDeadline": true,
				"from": "2026-01-01T00:00:00.000Z",
				"policyVersion": "1.0.0",
				"reason": "base",
				"to": "2026-01-31T00:00:00.000Z"
			}
		]
	},
	"extensions": [
		{
			"additionalDays": 5,
			"justification": "policy_extension"
		}
	],
	"finalDueAt": "2026-02-05T00:00:00.000Z",
	"pauses": [
		{
			"duration": "2 days",
			"reason": "verification"
		}
	],
	"policyPack": "gdpr-eu",
	"policyVersion": "1.0.0",
	"requestId": "req-123"
}

Lifecycle Transition Endpoints

These endpoints all return the common lifecycle response shape:

{
	"dueAt": "2026-02-01T00:00:00.000Z",
	"id": "req-123",
	"status": "in_progress"
}

POST /requests/:id/clarifications/request

Pause progress and request clarification from the subject or requestor.

POST /requests/:id/clarifications/receive

Record that the clarification was received and let the workflow continue.

POST /requests/:id/extensions

Extend the legal deadline for the request.

POST /requests/:id/refusals

Refuse the request.

Request body:

• message (string, optional)
• rationale (string, optional)
• reason (string, optional)

POST /requests/:id/closures

Close the request.

POST /requests/:id/acknowledgements

Record that the request was acknowledged.

PUT /requests/:id/requestor

Replace or set the requestor snapshot.

Request body:

• type (string, required)
• name (string, optional)
• email (string, optional)
• relation (string, optional)

Response (202): Lifecycle response envelope.

Authority Endpoints

Use these endpoints when a representative or agent must prove authority to act for the data subject.

POST /requests/:id/authority/submit

Request body:

• evidenceArtifacts (array, required)
• status (string, required)
• verifiedAt (string, optional)

POST /requests/:id/authority/approve

Approve submitted authority evidence.

POST /requests/:id/authority/reject

Reject submitted authority evidence.

All three endpoints return the lifecycle response envelope.

Notification History

GET /requests/:id/notifications

List notification events and delivery attempts for a request.

Response (200):

{
	"events": [
		{
			"attempts": [
				{
					"attempt": 1,
					"channel": "email",
					"createdAt": "2026-01-01T00:00:00.000Z",
					"destination": "user@example.com",
					"status": "delivered"
				}
			],
			"createdAt": "2026-01-01T00:00:00.000Z",
			"eventId": "evt-123",
			"eventType": "request_fulfilled",
			"status": "delivered"
		}
	],
	"requestId": "req-123"
}

POST /requests/:id/notifications/:eventId/replay

Replay one notification event.

Response (202):

{
	"eventId": "evt-123",
	"status": "replayed"
}

Related Pages

• Verification API
• Manifest API
• Delivery API
• Appeals API
• Audit API
• Request Lifecycle