API Reference

The User-X API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://api.user-x.com

Authentication

The User-X API uses API keys to authenticate requests. You can view and manage your API keys in the User-X Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer authentication. Provide your API key as the bearer token value.

Authorization: Bearer sk_test_...

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Opportunities

Opportunities represent campaigns or challenges that users can participate in.

List Opportunities

GET /api/opportunities

Returns a list of active opportunities.

Parameters

Parameter	Type	Description
limit	integer	Number of opportunities to return (1-100, default: 20)
offset	integer	Number of opportunities to skip (default: 0)
status	string	Filter by status: `active`, `draft`, `completed`

Response

{
  "data": [
    {
      "id": "opp_1234567890",
      "title": "Customer Feedback Survey",
      "description": "Help us improve our services",
      "status": "active",
      "totalTasks": 3,
      "estimatedTime": 15,
      "reward": {
        "type": "voucher",
        "value": 25.00,
        "currency": "USD"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-02-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Get Opportunity

GET /api/opportunities/{id}

Retrieves the details of an existing opportunity.

Response

{
  "id": "opp_1234567890",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our services",
  "status": "active",
  "tasks": [
    {
      "id": "task_1",
      "title": "Complete Survey",
      "description": "Fill out our feedback form",
      "type": "survey",
      "required": true,
      "order": 1
    }
  ],
  "reward": {
    "type": "voucher",
    "value": 25.00,
    "currency": "USD"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-02-15T10:30:00Z"
}

Claims

Claims represent a user's participation in an opportunity.

Create Claim

POST /api/claims

Creates a new claim for an opportunity.

Parameters

Parameter	Type	Required	Description
opportunityId	string	Yes	The ID of the opportunity
userId	string	Yes	The ID of the user

Request Body

{
  "opportunityId": "opp_1234567890",
  "userId": "user_1234567890"
}

Response

{
  "id": "claim_1234567890",
  "opportunityId": "opp_1234567890",
  "userId": "user_1234567890",
  "status": "active",
  "progress": {
    "completedTasks": 0,
    "totalTasks": 3,
    "percentage": 0
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Claim

GET /api/claims/{id}

Retrieves the details of an existing claim.

Verifications

Verifications represent proof submissions for task completion.

Create Verification

POST /api/verifications

Submits a verification for a task.

Parameters

Parameter	Type	Required	Description
taskId	string	Yes	The ID of the task
claimId	string	Yes	The ID of the claim
text	string	No	Text description of the verification
assets	array	No	Array of asset objects (images, videos, etc.)
surveyResponses	array	No	Array of survey response objects

Request Body

{
  "taskId": "task_1234567890",
  "claimId": "claim_1234567890",
  "text": "I completed the survey as requested",
  "assets": [
    {
      "uri": "https://example.com/screenshot.jpg",
      "mediaType": "image",
      "caption": "Screenshot of completed survey"
    }
  ],
  "surveyResponses": [
    {
      "questionId": "q1",
      "answer": "Very satisfied"
    }
  ]
}

Response

{
  "id": "ver_1234567890",
  "taskId": "task_1234567890",
  "claimId": "claim_1234567890",
  "status": "pending",
  "text": "I completed the survey as requested",
  "assets": [
    {
      "uri": "https://example.com/screenshot.jpg",
      "mediaType": "image",
      "caption": "Screenshot of completed survey"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z"
}

List Verifications

GET /api/verifications

Returns a list of verifications.

Parameters

Parameter	Type	Description
claimId	string	Filter by claim ID
taskId	string	Filter by task ID
status	string	Filter by status: `pending`, `approved`, `rejected`
limit	integer	Number of verifications to return (1-100, default: 20)
offset	integer	Number of verifications to skip (default: 0)

Users

User management endpoints.

Get User

GET /api/users/{id}

Retrieves user information.

Response

{
  "id": "user_1234567890",
  "email": "[email protected]",
  "name": "John Doe",
  "profile": {
    "avatar": "https://example.com/avatar.jpg",
    "bio": "User bio"
  },
  "stats": {
    "totalClaims": 5,
    "completedClaims": 3,
    "totalRewards": 75.00
  },
  "createdAt": "2024-01-01T00:00:00Z"
}

Rewards

Reward management endpoints.

List Rewards

GET /api/rewards

Returns a list of rewards for a user.

Parameters

Parameter	Type	Description
userId	string	Filter by user ID
status	string	Filter by status: `pending`, `issued`, `redeemed`
limit	integer	Number of rewards to return (1-100, default: 20)

Response

{
  "data": [
    {
      "id": "reward_1234567890",
      "claimId": "claim_1234567890",
      "userId": "user_1234567890",
      "type": "voucher",
      "value": 25.00,
      "currency": "USD",
      "voucherCode": "REWARD123",
      "status": "issued",
      "expiresAt": "2024-12-31T23:59:59Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Error Codes

The User-X API uses conventional HTTP response codes to indicate the success or failure of an API request.

Code	Description
200	OK - Everything worked as expected
400	Bad Request - The request was unacceptable
401	Unauthorized - No valid API key provided
402	Request Failed - The parameters were valid but the request failed
403	Forbidden - The API key doesn't have permissions
404	Not Found - The requested resource doesn't exist
409	Conflict - The request conflicts with another request
429	Too Many Requests - Too many requests hit the API too quickly
500, 502, 503, 504	Server Errors - Something went wrong on our end