Frequently Asked Questions

Find answers to common questions about using the ZhenRent API.

General

What is ZhenRent?

ZhenRent is the Agent2Human fulfillment and human fallback network in the Zhen ecosystem. It connects developers and agent systems with human execution capacity for real-world tasks like verification, photography, exception handling, and evidence collection.

Who should use ZhenRent?

Ideal for:

E-commerce platforms (verify merchant locations)
AI/ML companies (collect training data)
Logistics companies (confirm delivery addresses)
Real estate platforms (capture property photos)
Market research firms (conduct on-site surveys)

How is ZhenRent different from a generic crowdsourcing marketplace?

Agent2Human First: The product is framed as managed human fallback for workflows, not an open gig marketplace
API-First: Integrate in minutes, not days
Geographic Matching: PostGIS-powered location intelligence
Real-Time: WebSocket and webhook support
Platform Handoff: Billing, account, and API key lifecycle management belong in Platform Console
China-Focused: Localized for Chinese market

Getting Started

How do I get started?

Sign in through Platform Console
Add funds or activate a task package in Platform Console
Create API key in Platform Console
Follow Quick Start Guide
Create your first task in 15 minutes

Do I need a credit card?

Yes, to add funds to your account. We accept:

Alipay (recommended)
WeChat Pay (coming soon)
Bank transfer (for企业账户 ≥1,000 RMB)

Is there a free trial?

Currently no free tier, but we offer:

No setup fees
No monthly minimums
Pay only for completed tasks
100 RMB minimum deposit

Authentication

What's the difference between API Keys and JWT tokens?

Feature	API Key	JWT Token
Used by	Agents (developers)	Workers (mobile app users)
Validity	Long-term (90+ days)	Short-term (15 min access, 7 day refresh)
Format	`zr_live_*`	Standard JWT
Permissions	Task management	Worker actions

Can I use the same API key for dev and production?

No. Create separate keys:

Development: Test features, debugging
Staging: Pre-production testing
Production: Live traffic

Why? Easy to revoke compromised keys without affecting other environments.

How do I rotate API keys?

Create new API key in Platform Console
Update application configuration
Deploy changes
Test with new key
Delete old key

Recommended frequency: Every 90 days

What happens if my API key is leaked?

Immediately delete the compromised key in Platform Console
Create new API key
Update application
Review recent API activity for unauthorized usage
Consider IP whitelisting for new key

Tasks

How long does it take for tasks to be completed?

Average times:

Simple photo tasks: 2-4 hours
Verification tasks: 4-8 hours
Data collection: 1-2 days

Factors affecting speed:

Location (urban faster than rural)
Budget (higher pays faster)
Time of day (weekdays faster)
Required skills (common skills faster)

Can I cancel a task?

Yes, but refund depends on status:

Status	Refund	Fee
`pending`	100%	None
`assigned`	70%	30% to worker
`in_progress`	Not allowed	N/A
`submitted`	Not allowed	N/A

How to cancel:

DELETE /api/v1/tasks/{task_id}

What happens if a worker doesn't complete the task?

If deadline expires without completion:

Task status → failed
Payment refunded to your balance
Worker reputation decreases
You can recreate the task

If worker abandons task:

Task reassigned to another worker automatically
No additional cost to you
Original worker's reputation decreases

Can I require specific skills?

Yes, specify in requirements.skills:

{
  "requirements": {
    "skills": ["photography", "data_entry"],
    "min_reputation": 4.5
  }
}

Common skills:

photography
data_entry
surveying
translation
quality_inspection

How do I ensure good quality results?

Clear instructions: Detailed task description
Example photos: Show what you expect
Minimum reputation: Set min_reputation: 4.0+
Adequate budget: Higher pay attracts better workers
Review and feedback: Rate workers honestly

Payments

How does pricing work?

Formula:

Total Cost = Worker Payout + Platform Fee (10%)

Example (50 RMB task):

Worker receives: 45 RMB (90%)
Platform fee: 5 RMB (10%)
Total cost: 50 RMB

What payment methods do you accept?

Funding methods:

Alipay (instant)
WeChat Pay (coming soon)
Bank transfer (1-3 business days, ≥1,000 RMB)

When am I charged?

Charge timing:

Task created → Balance deducted → Held in escrow
Task completed + approved → Released to worker
Task failed/cancelled → Refunded to balance

You're charged when task is created, not when completed.

How do I check my balance?

curl "https://www.zhenrent.com/api/v1/payment/balance" \
  -H "Authorization: Bearer zr_live_your_key"

{
  "balance_cents": 50000,
  "balance_rmb": 500.0
}

Can I get a refund?

Full refund scenarios:

Task cancelled before assignment
Task failed (deadline expired without completion)
Technical issue on our platform

Partial refund scenarios:

Task cancelled after assignment (70% refund)

No refund scenarios:

Task completed and approved
Agent-side cancellation after work started

Do you issue invoices?

Yes!

Process:

Navigate to Platform Console → Billing → Request Invoice
Fill in company information
Select transactions to invoice
Submit request

Types available:

增值税普通发票 (VAT ordinary invoice)
增值税专用发票 (VAT special invoice)

Delivery time: 5-7 business days

Technical

What's the API response time?

Performance benchmarks:

P50 (median): 80ms
P95: 165ms
P99: 280ms

SLA: 99.5% uptime (≤3.6 hours downtime/month)

Are there rate limits?

Yes:

Tier	Requests/Minute	Requests/Day
Free	100	10,000
Paid	1,000	100,000

Rate limit exceeded response:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 60 seconds."
  }
}

Do you support webhooks?

Yes! Configure webhooks to receive real-time notifications:

Platform Console → Webhooks → Add Endpoint
URL: https://your-app.com/webhooks/zhenrent
Events: task.completed, task.failed

Webhook events:

task.assigned
task.started
task.submitted
task.completed
task.failed

Learn more about webhooks

Is there a sandbox environment?

Test environment coming soon!

Current workaround:

Use small budget tasks (10-20 RMB)
Test in production with real workers
Cancel tasks immediately after assignment to get 70% refund

What regions do you support?

Currently supported:

Mainland China (all cities)

Coming soon:

Hong Kong, Macau, Taiwan
Southeast Asia (Singapore, Thailand, Vietnam)

Do you have SDKs?

Official SDKs:

Python: pip install zhenrent (coming soon)
JavaScript: npm install zhenrent-sdk (coming soon)
Go: go get github.com/zhenrent/zhenrent-go (coming soon)

Current workaround: Use REST API directly (see API Reference)

Troubleshooting

Error: 401 Unauthorized

Causes:

Missing Authorization header
Invalid API key format
Expired or deleted API key

Solution:

# Correct format
headers = {
    "Authorization": f"Bearer {API_KEY}"  # Note "Bearer " prefix
}

Error: 402 Payment Required

Cause: Insufficient account balance

Solution:

Check balance: GET /api/v1/payment/balance
Add funds or activate package in Platform Console
Retry task creation

Error: 400 Validation Error

Cause: Invalid request parameters

Common issues:

Budget < 1000 cents (minimum 10 RMB)
Deadline in the past
Invalid coordinates
Missing required fields

Solution: Check error details:

{
  "error": {
    "code": "validation_error",
    "details": [
      {
        "field": "budget_cents",
        "message": "Input should be greater than or equal to 1000"
      }
    ]
  }
}

Task stuck in "pending" status

Possible causes:

Location too remote: No workers nearby
Budget too low: Workers not accepting
Requirements too strict: Few qualified workers
Off-peak hours: Workers not active

Solutions:

Increase budget (try 50% more)
Expand max_distance_meters
Reduce min_reputation requirement
Extend deadline to allow more time

How do I report a bug?

Report channels:

Email: support@zhenrent.com
GitHub: https://github.com/zhenrent/zhenrent/issues

Include in report:

Task ID or API request ID
Request/response details
Expected vs actual behavior
Timestamp
Environment (production/staging)

Billing & Pricing

How much do tasks cost?

Pricing factors:

Task complexity
Location (urban vs rural)
Urgency (deadline)
Required skills

General guidelines:

Task Type	Suggested Price	Duration
Simple photo	20-50 RMB	15-30 min
Store verification	30-80 RMB	30-60 min
Data collection	50-150 RMB	1-2 hours
Survey/interview	100-300 RMB	2-4 hours

Platform fee: 10% on all transactions

Can I negotiate enterprise pricing?

Yes! Contact sales@zhenrent.com if you:

Process > 10,000 tasks/month
Need custom SLA
Require dedicated support
Want volume discounts

Enterprise benefits:

Discounted platform fees (8-9%)
Higher rate limits
Priority support
Custom contract terms

Support

How do I contact support?

Email: support@zhenrent.com (response < 24h)
Platform Console: Help → Contact Support
Emergency: For production outages, use "Urgent" tag

Is there developer community?

Coming soon! We're building:

Discord server
Developer forum
GitHub discussions

Subscribe to updates: https://www.zhenrent.com/newsletter

Do you offer consulting services?

Yes, for enterprise customers:

Integration assistance
Architecture review
Custom feature development
Training and onboarding

Contact: enterprise@zhenrent.com

Legal

What are your terms of service?

Read full terms: https://www.zhenrent.com/terms

Key points:

You own task data and results
Workers are independent contractors
ZhenRent is platform provider, not employer
Escrow protects both parties

We follow data protection best practices:

Data encrypted in transit (TLS 1.3)
Data encrypted at rest
Workers consent to data collection
You control task data

Note: GDPR primarily applies to EU. We're China-focused.

Who owns the task results?

You (the Agent) own:

Task descriptions
Results and deliverables
Photos taken by workers
Data collected

Workers own:

Their personal information
Their account data

ZhenRent owns:

Platform software
Matching algorithms
Anonymous analytics data

Still Have Questions?

Can't find your answer? Contact us:

Email: support@zhenrent.com
Response time: < 24 hours
Available: Monday-Friday, 9AM-6PM Beijing Time

Or explore more documentation:

General​

What is ZhenRent?​

Who should use ZhenRent?​

How is ZhenRent different from a generic crowdsourcing marketplace?​

Getting Started​

How do I get started?​

Do I need a credit card?​

Is there a free trial?​

Authentication​

What's the difference between API Keys and JWT tokens?​

Can I use the same API key for dev and production?​

How do I rotate API keys?​

What happens if my API key is leaked?​

Tasks​

How long does it take for tasks to be completed?​

Can I cancel a task?​

What happens if a worker doesn't complete the task?​

Can I require specific skills?​

How do I ensure good quality results?​

Payments​

How does pricing work?​

What payment methods do you accept?​

When am I charged?​

How do I check my balance?​

Can I get a refund?​

Do you issue invoices?​

Technical​

What's the API response time?​

Are there rate limits?​

Do you support webhooks?​

Is there a sandbox environment?​

What regions do you support?​

Do you have SDKs?​

Troubleshooting​

Error: 401 Unauthorized​

Error: 402 Payment Required​

Error: 400 Validation Error​

Task stuck in "pending" status​

How do I report a bug?​

Billing & Pricing​

How much do tasks cost?​

Can I negotiate enterprise pricing?​

Support​

How do I contact support?​

Is there developer community?​

Do you offer consulting services?​

Legal​

What are your terms of service?​

Are you GDPR compliant?​

Who owns the task results?​

Still Have Questions?​