Skip to main content

Creating Evidence Requests

What are Evidence Requests?​

Evidence Requests are requests for specific data for a given data collection period within a Document Instance. They define:

  • What evidence should be collected
  • When it should be collected (collection period)
  • By when it's due (due date)
  • How it should be organized (standard or batch)

Evidence Requests can be one-time submissions or recurring collections.

Evidence Request Types​

STANDARD​

A standard evidence request for individual file uploads or field value submissions.

BATCH​

A batch evidence request where data is organized by batch IDs, allowing multiple batches to be submitted together.

Batch Requests

When a document is configured as a BATCH type evidence request, all Evidence and Expected Field Values can be organized by batchItemId, enabling efficient data entry where common field values are specified once per batch. Read the next section on Batches to learn more.

Evidence Request Statuses​

Evidence Request statuses reflect readiness for audit:

StatusDescription
PENDINGInitial state; evidence collection in progress
READY_FOR_REVIEWEvidence submitted and ready for review
APPROVEDEvidence has been reviewed and approved
SKIPPEDEvidence request intentionally skipped with reason
Status Visibility

These statuses are for internal tracking and are not visible to the Reviewer or Auditor during the review process.

Creating an Evidence Request​

To create an evidence request, use POST /v0/evidence-requests:

Creating a Standard Evidence Request​

Create evidence request
curl -X 'POST' "/v0/evidence-requests" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "STANDARD", \
    "documentInstanceId": "document-instance-uuid", \
    "dueDate": "2024-12-31T23:59:59Z", \
    "collectionStartDate": "2024-01-01T00:00:00Z", \
    "collectionEndDate": "2024-12-31T23:59:59Z" \
  }'

Creating a Batch Evidence Request​

Create evidence request
curl -X 'POST' "/v0/evidence-requests" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "type": "BATCH", \
    "documentInstanceId": "document-instance-uuid", \
    "dueDate": "2024-12-31T23:59:59Z", \
    "collectionStartDate": "2024-01-01T00:00:00Z", \
    "collectionEndDate": "2024-12-31T23:59:59Z" \
  }'

Parameters​

  • documentInstanceId (required) - UUID of the document instance
  • type (optional) - STANDARD or BATCH (default: STANDARD)
  • dueDate (optional) - When the evidence is due
  • collectionStartDate (optional) - Start of data collection period
  • collectionEndDate (optional) - End of data collection period

Listing Evidence Requests​

To view all evidence requests:

Get evidence requests
curl -X 'GET' "/v0/evidence-requests" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Response Schema​

type
required
string
Enum: "STANDARD" "BATCH"
status
required
string
Enum: "PENDING" "READY_FOR_REVIEW" "APPROVED" "SKIPPED"
id
required
string
dueDate
required
string or null <date-time>
collectionStartDate
required
string or null <date-time>
collectionEndDate
required
string or null <date-time>
reasonSkipped
required
string or null

Getting a Specific Evidence Request​

To retrieve details about a specific evidence request:

Get evidence request
curl -X 'GET' "/v0/evidence-requests/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"

Updating an Evidence Request​

You can update an evidence request using PATCH /v0/evidence-requests/{id}:

Update evidence request
curl -X 'PATCH' "/v0/evidence-requests/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "status": "READY_FOR_REVIEW", \
    "dueDate": "2025-01-15T23:59:59Z", \
    "collectionEndDate": "2024-12-31T23:59:59Z" \
  }'

Updatable Fields​

  • status - Change the status (e.g., to READY_FOR_REVIEW or SKIPPED)
  • reasonSkipped - Provide a reason when status is SKIPPED
  • dueDate - Adjust the due date
  • collectionStartDate - Adjust collection period start
  • collectionEndDate - Adjust collection period end

Skipping an Evidence Request​

If an evidence request doesn't apply, you can skip it:

Update evidence request
curl -X 'PATCH' "/v0/evidence-requests/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER" \
  -d '{ \
    "status": "SKIPPED", \
    "reasonSkipped": "Not applicable for this monitoring period" \
  }'
Provide Reasoning

Always include a reasonSkipped explanation when setting status to SKIPPED. This helps auditors understand why evidence was not submitted.

Deleting an Evidence Request​

To delete an evidence request:

Delete evidence request
curl -X 'DELETE' "/v0/evidence-requests/{id}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"
Deletion Warning

Deleting an Evidence Request will remove all associated Evidence files and Expected Field Values. This action cannot be undone.

Pinned Documents and Evidence Requests​

warning

If a document is pinned in a facility, it's possible to pull in its Evidence Request(s) from a different Document Instance in the MyPuro UI. Document pinning is not supported via the API as of now.

Next Steps​

Now that you've created evidence requests, you need to understand how to work with batches if you're using batch-type evidence requests.