Skip to main content

Creating Evidence Requests

Evidence Requests are requests for specific data for a given data collection period within a Document Instance. They define how the evidence collection should be organized withing the monitoring period (one-time vs in batches). Fields such as due dates, collection periods, and status can also be tracked within the Evidence Request, which can help manage the evidence collection process.

Evidence Requests can be one-time submissions or organized by batches.

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 evidence to be submitted per batch.

Batch Requests

When an Evidence Request is configured as a BATCH type, the Evidence and Expected Field Values can be organized by batchItemId, enabling accurate data entry and calculations across batches. 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" \
  }'

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.