Quick Start Guide

This guide will walk you through creating your first ZhenRent task in under 15 minutes.

Prerequisites

Basic knowledge of REST APIs
Command line or programming environment
Credit/debit card for initial deposit (minimum 100 RMB)

Step 1: Register and Get API Key (5 minutes)

1.1 Create Account

Visit ZhenRent Dashboard
Click "Sign Up" and complete registration
Verify your email address

1.2 Add Funds

Navigate to Wallet section
Click Recharge
Enter amount (minimum 100 RMB)
Complete payment via Alipay

Note: Your account balance must cover task budget + 20% platform fee. For detailed pricing breakdown, see our Pricing Guide.

For API integration: See Payment API Reference for programmatic payment handling.

1.3 Create API Key

Navigate to API Keys section
Click Create New Key
Set key name (e.g., "Development")
Select permissions:
- task:create - Create new tasks
- task:read - Query task status
- task:cancel - Cancel pending tasks
Click Create
Copy your API key (shows only once!)

Your API Key format: zr_live_abcd1234...

Important: Store securely and never commit to version control.

Step 2: Make Your First API Call (2 minutes)

Option A: Using cURL

export ZHENRENT_API_KEY="zr_live_your_actual_key_here"

curl -X POST "https://www.zhenrent.com/api/v1/tasks" \
  -H "Authorization: Bearer $ZHENRENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Verify store opening hours",
    "description": "Please take a clear photo of the store hour sign at the entrance",
    "location": {
      "latitude": 39.916527,
      "longitude": 116.397128,
      "address": "Tiananmen Square, Beijing",
      "max_distance_meters": 500
    },
    "budget_cents": 5000,
    "deadline_at": "2026-04-15T18:00:00Z",
    "task_type": "photo",
    "max_workers": 1,
    "requirements": {
      "skills": ["photography"],
      "min_reputation": 4.0
    }
  }'

Option B: Using Python

import requests
import os
from datetime import datetime, timedelta

API_KEY = os.getenv("ZHENRENT_API_KEY")
BASE_URL = "https://www.zhenrent.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create task
response = requests.post(
    f"{BASE_URL}/tasks",
    headers=headers,
    json={
        "title": "Verify store opening hours",
        "description": "Please take a clear photo of the store hour sign",
        "location": {
            "latitude": 39.916527,
            "longitude": 116.397128,
            "address": "Tiananmen Square, Beijing",
            "max_distance_meters": 500
        },
        "budget_cents": 5000,  # 50 RMB
        "deadline_at": (datetime.now() + timedelta(days=7)).isoformat() + "Z",
        "task_type": "photo",
        "max_workers": 1
    }
)

if response.status_code == 201:
    task = response.json()
    print(f"Success! Task ID: {task['task_id']}")
    print(f"Status: {task['status']}")
    print(f"Cost breakdown:")
    print(f"  Worker payout: {task['cost_breakdown']['worker_payout_cents']/100} RMB")
    print(f"  Platform fee: {task['cost_breakdown']['platform_fee_cents']/100} RMB")
    print(f"  Total: {task['cost_breakdown']['total_cents']/100} RMB")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Expected Response

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "estimated_completion_at": "2026-04-15T16:00:00Z",
  "cost_breakdown": {
    "worker_payout_cents": 4500,
    "platform_fee_cents": 500,
    "total_cents": 5000
  },
  "created_at": "2026-03-31T10:00:00Z"
}

Status Meanings:

pending - Task created, searching for workers
assigned - Worker found and assigned
in_progress - Worker actively working on task
submitted - Worker submitted result, pending your review
completed - You approved result, payment released
failed - Task failed or was cancelled

Step 3: Check Task Status (2 minutes)

curl "https://www.zhenrent.com/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $ZHENRENT_API_KEY"

task_id = task['task_id']
response = requests.get(
    f"{BASE_URL}/tasks/{task_id}",
    headers=headers
)

status = response.json()
print(f"Task: {status['title']}")
print(f"Status: {status['status']}")
print(f"Progress: {status['progress']['assigned_workers']} workers assigned")
print(f"Deadline: {status['deadline_at']}")

Response

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "assigned",
  "title": "Verify store opening hours",
  "description": "Please take a clear photo...",
  "progress": {
    "assigned_workers": 1,
    "completed_workers": 0,
    "estimated_completion_at": "2026-04-15T17:00:00Z"
  },
  "assignments": [
    {
      "worker_id": "worker_abc123",
      "worker_reputation": 4.8,
      "assigned_at": "2026-03-31T10:05:00Z",
      "status": "in_progress"
    }
  ],
  "created_at": "2026-03-31T10:00:00Z",
  "deadline_at": "2026-04-15T18:00:00Z"
}

Step 4: Retrieve Task Result (After Completion)

Once the task status is completed, retrieve the result:

response = requests.get(
    f"{BASE_URL}/tasks/{task_id}/result",
    headers=headers
)

result = response.json()
print(f"Task completed at: {result['completed_at']}")
print(f"Quality score: {result['quality_score']}/5.0")
print(f"Photos: {len(result['result']['photos'])} uploaded")

for photo in result['result']['photos']:
    print(f"  - {photo['url']}")
    print(f"    Taken at: {photo['taken_at']}")

if result['result']['worker_notes']:
    print(f"Worker notes: {result['result']['worker_notes']}")

Response

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "data": {
      "verification_status": "confirmed",
      "notes": "Store hours: Mon-Fri 9AM-9PM, Sat-Sun 10AM-8PM"
    },
    "photos": [
      {
        "url": "https://storage.zhenrent.com/photos/abc123.jpg",
        "taken_at": "2026-04-10T14:30:00Z"
      }
    ],
    "worker_notes": "Photo taken during business hours, sign clearly visible"
  },
  "completed_at": "2026-04-10T14:35:00Z",
  "quality_score": 4.9
}

Step 5: List All Your Tasks

# List all tasks
response = requests.get(
    f"{BASE_URL}/tasks",
    headers=headers,
    params={
        "limit": 20,
        "status": "completed"  # Optional: filter by status
    }
)

tasks = response.json()
print(f"Total tasks: {len(tasks['data'])}")
for task in tasks['data']:
    print(f"- {task['title']} (#{task['task_id'][:8]}...)")
    print(f"  Status: {task['status']}, Budget: {task['budget_cents']/100} RMB")

Common Issues

Error: 401 Unauthorized

Cause: Invalid or missing API key

Solution:

Verify API key format starts with zr_live_
Check Authorization header: Bearer YOUR_KEY
Ensure key hasn't been deleted or revoked

# 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
Recharge account via Dashboard
Retry task creation

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

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

Error: 400 Bad Request (Validation)

Cause: Invalid request parameters

Common mistakes:

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

Solution: Check error details:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "budget_cents",
        "message": "Must be at least 1000 (10 RMB)"
      }
    ]
  }
}

Best Practices

1. Store API Keys Securely

Never hardcode API keys:

# Bad
API_KEY = "zr_live_abc123..."

# Good
import os
API_KEY = os.getenv("ZHENRENT_API_KEY")

2. Handle Errors Gracefully

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 402:
        print("Insufficient balance. Please recharge.")
    elif e.response.status_code == 401:
        print("Invalid API key.")
    else:
        print(f"API error: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Network error: {e}")

3. Use Idempotency Keys

Prevent duplicate tasks during network failures:

import uuid

response = requests.post(
    f"{BASE_URL}/tasks",
    headers=headers,
    json={
        "idempotency_key": str(uuid.uuid4()),  # Unique per request
        "title": "...",
        # ... other fields
    }
)

If the same idempotency_key is sent twice, the second request returns the existing task instead of creating a duplicate.

4. Set Reasonable Deadlines

Allow sufficient time for worker discovery and task completion:

from datetime import datetime, timedelta

# Recommended: 3-7 days for standard tasks
deadline = datetime.now() + timedelta(days=5)

# Urgent tasks (higher budget recommended)
deadline = datetime.now() + timedelta(hours=24)

Next Steps

Congratulations! You've created your first ZhenRent task.

Continue Learning:

Pricing Guide - Transparent pricing and cost calculator
Core Concepts - Understand platform architecture
Authentication Guide - Secure API access
Complete API Reference - All endpoints
Python Examples - Production-ready code
Testing Guide - Test before going live

Need Help?

Email: support@zhenrent.com
Expected response: < 24 hours

Prerequisites​

Step 1: Register and Get API Key (5 minutes)​

1.1 Create Account​

1.2 Add Funds​

1.3 Create API Key​

Step 2: Make Your First API Call (2 minutes)​

Option A: Using cURL​

Option B: Using Python​

Expected Response​

Step 3: Check Task Status (2 minutes)​

Response​

Step 4: Retrieve Task Result (After Completion)​

Response​

Step 5: List All Your Tasks​

Common Issues​

Error: 401 Unauthorized​

Error: 402 Payment Required​

Error: 400 Bad Request (Validation)​

Best Practices​

1. Store API Keys Securely​

2. Handle Errors Gracefully​

3. Use Idempotency Keys​

4. Set Reasonable Deadlines​

Next Steps​

Prerequisites

Step 1: Register and Get API Key (5 minutes)

1.1 Create Account

1.2 Add Funds

1.3 Create API Key

Step 2: Make Your First API Call (2 minutes)

Option A: Using cURL

Option B: Using Python

Expected Response

Step 3: Check Task Status (2 minutes)

Response

Step 4: Retrieve Task Result (After Completion)

Response

Step 5: List All Your Tasks

Common Issues

Error: 401 Unauthorized

Error: 402 Payment Required

Error: 400 Bad Request (Validation)

Best Practices

1. Store API Keys Securely

2. Handle Errors Gracefully

3. Use Idempotency Keys

4. Set Reasonable Deadlines

Next Steps