Four endpoints.
One workflow.

Authentication

Send your API key with every request using either header. Keep keys on your server.

X-API-Key: YOUR_KEY

# Or
Authorization: Bearer YOUR_KEY

JSON endpoints use this response envelope. Report downloads return PDF bytes directly.

{ "success": true, "code": "OK", "message": "OK", "data": { ... } }

1. Check your account

GET /api/v1/account

Returns your remaining balance in passes. Passes are ez billing credits, not automatically USD or a count of checks.

curl https://api.2022915.xyz/api/v1/account \
  -H "X-API-Key: YOUR_KEY"

2. Submit a document

POST /api/v1/submissions

Multipart fields: file is required; external_id is optional. Use a unique external ID for each logical order. On a retry, reuse that ID to avoid duplicate submissions. Save the returned task_id. Submit multiple files as separate requests; this contract does not define a batch endpoint.

curl https://api.2022915.xyz/api/v1/submissions \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@paper.docx" \
  -F "external_id=my-order-123"

3. Track the submission

GET /api/v1/submissions/{task_id}

Poll every 20–30 seconds. Wait for data.reports.similarity_pdf_ready and, if enabled, ai_pdf_ready. Ready reports include the corresponding *_download_url. Stop on a terminal failure; do not poll indefinitely.

curl https://api.2022915.xyz/api/v1/submissions/TASK_ID \
  -H "X-API-Key: YOUR_KEY"

4. Download the report

GET /api/v1/submissions/{task_id}/reports/{type}

Use sim for Similarity or ai for AI screening if enabled. Successful downloads return the PDF file directly. Check the HTTP status and Content-Type before saving; error responses may be JSON. Download promptly.

curl --fail-with-body https://api.2022915.xyz/api/v1/submissions/TASK_ID/reports/sim \
  -H "X-API-Key: YOUR_KEY" \
  -o report.pdf

Errors & retries

On errors, success is false. Treat data as optional: servers may omit it or return an empty object. A submission timeout does not prove failure. Query the existing task or reconcile using its external ID before resubmitting. A failed job is refunded by ez; do not add a second refund in your application.