Sign Off Collection

Analyst signs off on a completed collection, certifying its completeness and accuracy.

POST /api/collections/{id}/sign-off

Authorization

• Analyst: Required

note

Collections in completed, partial, or reviewing status can be signed off. The signing analyst is auto-assigned to the collection.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Request Body

Field	Type	Required	Description
signature	string	Yes	Typed signature (non-empty)
checklist	object	Yes	All four boolean items must be true
notes	string	No	Additional notes about the sign-off

Checklist

{
  filesCollected: boolean,   // must be true
  hashesVerified: boolean,   // must be true
  apiLogsReviewed: boolean,  // must be true
  chainComplete: boolean     // must be true
}

Request Example

{
  "signature": "John Doe",
  "checklist": {
    "filesCollected": true,
    "hashesVerified": true,
    "apiLogsReviewed": true,
    "chainComplete": true
  },
  "notes": "Verified all 234 files. Data appears complete for the requested date range."
}

Response

{
  "success": true,
  "collection_id": "col_abc123",
  "status": "signed_off",
  "signed_off_at": "2024-01-16T09:00:00Z",
  "delivery_job_id": "job_zip_789"
}

Side Effects

Sign-off triggers the following:

1. Collection status updated to signed_off; signing analyst auto-assigned
2. signed_off_at, signature, and notes recorded
3. Chain of custody event logged (analyst_signed_off) including the checklist
4. A create-zip (delivery) job is queued

Chain of Custody Event

The sign-off creates an immutable record:

{
  "event_type": "analyst_signed_off",
  "actor_id": "analyst_001",
  "actor_type": "analyst",
  "timestamp": "2024-01-16T09:00:00Z",
  "event_data": {
    "analyst_name": "John Doe",
    "notes": "Verified all 234 files...",
    "checklist": {
      "filesCollected": true,
      "hashesVerified": true,
      "apiLogsReviewed": true,
      "chainComplete": true
    },
    "files_collected": 234
  }
}

Example Request

curl -X POST "https://api.traces.io/api/collections/col_abc123/sign-off" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "John Doe",
    "checklist": {
      "filesCollected": true,
      "hashesVerified": true,
      "apiLogsReviewed": true,
      "chainComplete": true
    },
    "notes": "Collection verified and complete."
  }'

Error Responses

400 Bad Request

Incomplete checklist:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "All checklist items must be confirmed"
  }
}

Missing signature:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Signature is required"
  }
}

Collection not in a sign-off-able state:

{
  "error": {
    "code": "INVALID_STATE",
    "message": "Cannot sign off collection in 'in_progress' status. Must be completed, partial, or reviewing."
  }
}

403 Forbidden

Non-analyst attempting sign-off:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Analyst access required"
  }
}