Frequently Asked Questions

General

What is EnvoyX?

EnvoyX is an AI-powered medical invoice extraction platform that automates the processing of insurance claims and invoices. Upload a PDF invoice, and our multi-agent AI system extracts structured data, validates it against your business rules, and notifies you in real-time.

What file formats do you support?

Currently, we support PDF files only. Support for images (PNG, JPG) and scanned documents is coming soon.

How long does invoice processing take?

Most invoices are processed in 15-25 seconds. Complex or large invoices may take up to 60 seconds.

What happens if extraction fails?

If the AI cannot extract data from your invoice, the status will be set to FAILED with an error message explaining what went wrong. Common causes include:

Corrupted PDF files
Image-based PDFs without OCR
Unsupported document formats
File size too large (>10MB)

Authentication

How do API keys work?

API keys provide simple, secure access to the EnvoyX API. You create and manage keys through the EnvoyX Dashboard. Include your key in the X-API-Key header with every request:

curl -X GET https://staging-api.tryenvoyx.com/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY"

See the Authentication Guide for details.

Why do I need to verify my email?

Email verification is required for security when creating your account. You must verify your email through the dashboard before you can create API keys.

Invoices

What data do you extract from invoices?

We extract:

Claim Number
Insured ID
Partner/Insurance Name
Patient Name
Invoice Number
Service Category
Total Amount (Insurance Value)
Max Coverage
Out of Pocket
Submission Date
Invoice Date
Provider Name

What are validation flags?

After extraction, we run 5 validation checks:

Partner Valid: Insurance name is in your approved list
Category Valid: Service category is recognized
Amount Valid: Amount is between $0 and $1,000,000
Date Valid: Invoice date is within last 3 months
Duplicate Check: Claim number + date combination is unique

If any check fails, the invoice is flagged for manual review.

Can I customize validation rules?

Yes! Contact support at Email Support to configure custom validation rules for your account.

How do I handle duplicate invoices?

The duplicate check flags invoices with the same claim number and submission date. You can:

Review flagged duplicates manually
Approve if it's a legitimate duplicate (rare)
Reject if it's an accidental re-upload

How do I download processed invoices?

The invoice object includes a file_url field with a signed URL to download the original PDF:

curl -X GET https://staging-api.tryenvoyx.com/api/v1/invoices/{invoice_id} \
  -H "X-API-Key: YOUR_API_KEY"

The file_url is valid for 1 hour.

Webhooks & WebSockets

Should I use webhooks or WebSockets?

Webhooks: Server-to-server integrations, guaranteed delivery, asynchronous processing
WebSockets: Real-time web/mobile apps, instant updates, bidirectional communication

You can use both simultaneously!

How do I test webhooks locally?

Use a tunnel service like ngrok or localhost.run:

# Start your local server
node server.js  # Port 3000

# Create tunnel with ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
https://abc123.ngrok.io/webhooks/envoyx

See the Webhooks Guide for details.

Why am I not receiving webhook events?

Common issues:

Endpoint returns non-200 status: Ensure your endpoint returns 200 OK
Timeout: Endpoint must respond within 5 seconds
Invalid signature: Verify you're using the correct webhook secret
Webhook inactive: Check if webhook is enabled in dashboard
URL unreachable: Ensure your server is publicly accessible

Check the delivery history to see what happened.

How long do WebSocket connections stay open?

Connections stay open indefinitely as long as you send a ping message every 30 seconds. If no ping is received for 60 seconds, the server will close the connection.

Rate Limits

What are the rate limits?

Endpoint Type	Limit	Window
General API	100 requests	1 minute
Invoice Upload	100 uploads	1 hour
WebSocket	5 connections	Per API key

Rate limits are per API key. Contact support for higher limits.

How do I handle rate limiting?

If you hit a rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again later.",
  "data": {
    "retry_after": 60
  }
}

Implement exponential backoff or use the retry_after value.

Can I increase my rate limits?

Yes! Contact Email Support to discuss custom rate limits for your use case.

Billing & Pricing

Is there a free tier?

Yes! All accounts get:

100 free invoice uploads per month
Full API access
Webhook and WebSocket support

How do I upgrade my plan?

Contact Email Support for pricing and plan details.

Do you charge for failed extractions?

No, you're only charged for successfully processed invoices (PROCESSED or FLAGGED status). FAILED invoices don't count against your quota.

Technical

Is there a sandbox environment?

All accounts can use the production API for testing with the free tier. Test invoices don't affect your production data.

What regions do you support?

EnvoyX is currently available in:

United States (US East)
Europe (EU West)

Data residency options are available for enterprise customers.

Do you have SDKs?

Official SDKs are coming soon! Currently, you can use any HTTP client with our REST API. OpenAPI specification is available at:

https://staging-api.tryenvoyx.com/api/v1/openapi.json

Invoices: Encrypted at rest in AWS S3
Extracted data: Encrypted in PostgreSQL database
Passwords: Hashed with bcrypt
API keys: Hashed with SHA-256

Email: Email Support
GitHub Issues: github.com/envoyx/api/issues
Documentation: EnvoyX Docs

What's your support response time?

Free tier: 48-hour response time
Paid plans: 24-hour response time
Enterprise: Priority support with dedicated account manager

Can I request new features?

Absolutely! Submit feature requests via:

GitHub Issues
Email support
Direct feedback in dashboard

We prioritize features based on user demand and feasibility.

Frequently Asked Questions

On this page