Use the proof-of-delivery API in your agent
Try a fictional proof-of-delivery batch, then connect your agent to the Provanza API.
Try the demo without an account
The demo replays fixed responses for fictional shipments. It uses no credentials, contacts no carriers, and creates no requests or charges.
- An available proof reaches completed. Download the marked sample PDF to see the result.
- The GLS row is ready at preview and starts on submit. On poll it returns needs_input. Ask the operator for the destination postal code.
- An unavailable proof reaches not_found with document_not_found. Record the outcome without attaching evidence.
Read the results from a terminal
Run this command with curl and jq. It downloads and checks sample-pod.pdf, then runs the fictional batch on the server and prints the outcomes. For local development, set DEMO_ORIGIN to your web server URL.
DEMO_ORIGIN="${DEMO_ORIGIN:-https://provanza.app}"
DEMO_ORIGIN="${DEMO_ORIGIN%/}"
curl -fsS -o sample-pod.pdf "$DEMO_ORIGIN/tools/sample-pod.pdf" &&
test "$(head -c 5 sample-pod.pdf)" = '%PDF-' &&
test "$(tail -n 1 sample-pod.pdf)" = '%%EOF' &&
result=$(curl -fsS -X POST "$DEMO_ORIGIN/tools/pod-demo/run") &&
printf '%s\n' "$result" |
jq -e 'select(.fictional == true and .status == "completed") | .outcomes'Connect an MCP client
Add this URL as a Streamable HTTP server in your MCP client. Call lookup_carrier_evidence with a carrier slug, such as gls. Call run_fictional_pod_demo with no arguments. Both tools are public and require no API key.
https://provanza.app/mcp
Connect to the production API
Send requests to this API origin. https://api.provanza.app
An organization owner or admin creates an API key under Settings → API access. Key creation requires an active or trialing Growth or Pro plan.
Store the key on your server. Send Authorization: Bearer <api key> to /api/v1. Review the preview and get approval before submitting billable work.
POST /api/v1/pod-requests/batch/previewSend entries with clientId and value. Supply carrier, carrierNetwork, or postalCode when needed. Preview classifies each row without starting work or using allowance.
POST /api/v1/pod-requests/batchSend the reviewed entries and the same optional batch postalCode. The response contains rows and may contain a batch group. A preview row marked needs_postal_code starts no new request. New rows can wait for plan allowance.
GET /api/v1/pod-requests/{id}Read each rows[].request.id from the submit response. Poll while status is queued or processing. For needs_input, use inputRequired to ask for the missing data. Stop polling on completed, not_found, or failed.
GET /api/v1/pod-requests/{id}/artifactFor a completed request with an artifact, read delivery. Fetch downloadUrl for public_url without forwarding your API key, or decode bodyBase64 for inline_payload. Handle download URLs as secrets.