API Documentation
Corvo is a REST API for sending arbitrary PDF documents as tracked physical mail. Upload or reference a PDF, create a draft shipment to get live USPS, FedEx, and UPS rates, buy the quote you want, and then poll the shipment record for fulfillment, tracking, and mailing records.
Base URL
Production API requests use:
https://corvo.toAuthentication
Authenticate public API calls with a Bearer API key in the Authorization header.
curl https://corvo.to/api/v1/shipments \
-H "Authorization: Bearer $CORVO_API_KEY"Core workflow
1. Upload or reference a PDF
Use the Documents API for direct uploads or a presigned S3 upload flow, then keep the returned document_key.
2. Create a draft shipment
POST /api/v1/shipments always returns draft quotes first. It never purchases postage.
3. Buy the selected quote
Call POST /api/v1/shipments/{id}/buy with the chosen quote_id. The public API assumes your organization already has billing configured in the dashboard.
4. Poll shipment status
Use shipment detail responses for fulfillment milestones, tracking, mailing-record summaries, and the event timeline.
Response format
Successful responses wrap the result in a data key. Errors return an error object with a human-readable message and a machine-readable code.
{
"data": {
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"status": "queued",
"shipment_name": "Mortgage Contract"
}
}{
"error": {
"message": "Either name or company is required",
"code": "VALIDATION_ERROR"
}
}Key conventions
1289.f47ac10b-58cc-4372-a567-0e02b2c3d479.Endpoint groups
Status
Health checks and smoke tests.
Documents
Direct uploads and presigned upload targets for PDFs.
Shipments
Draft creation, listing, retrieval, purchase, and cancellation.
Mailing Records
List retained evidence artifacts, download mailing-record summaries, and export evidence bundles for certified-mail shipments.