This guide provides an overview of the BetaTesting API resources, common patterns, and conventions.
For complete up-to-date endpoint specifications including request/response schemas, refer to the interactive Swagger documentation available from your Company Settings > Integrations page.
Base URL
https://betatesting.com/api/external/v2
All endpoints below are relative to this base URL.
Available Resources
Tests
Tests (also known as campaigns) are the core resource on BetaTesting. Each test belongs to your company and contains testers, activities, issues, and messages.
Method | Endpoint | Description | Scope |
|
| List all tests with optional status filtering | read |
|
| Get a specific test | read |
|
| Create a new test | write |
|
| Update test details | write |
|
| Copy an existing test | write |
|
| Change a test's stage (e.g., launch, pause, close) | write |
Filtering tests:
status- Filter by test status:draft,pending_review,ready,in_progress,complete,closed,paused
Testers
Manage testers within a specific test - accept applicants, mark them complete, send messages, or remove them.
Method | Endpoint | Description | Scope |
|
| List testers in a test | read |
|
| Get a specific tester in a test | read |
|
| List testers who completed the test | read |
|
| Accept testers into a test | write |
|
| Mark testers as complete | write |
|
| Send a message to testers | write |
|
| Remove a tester from a test | write |
Filtering testers:
search- Search by name or emailstatus- Filter by tester status:incomplete,complete,pending_review,removed,opt_out,stuck
Issues
Issues (e.g. bug reports) are submitted by testers during a test. You can list, view, update status/priority, or delete them.
Method | Endpoint | Description | Scope |
|
| List issues for a test | read |
|
| Get a specific issue | read |
|
| Update an issue (status, priority, notes) | write |
|
| Delete an issue | write |
Filtering issues:
filterStatuses- Comma-separated list:draft,to_do,in_progress,complete,needs_more_info,retest,outside_scopefilterPriorities- Comma-separated list:critical,high,medium,low,trivialsortSubmitDate- Sort by submission date:ascordescsortUpdateDate- Sort by last update:ascordesc
Activities
Activities (surveys and tasks) are distributed to testers within a test. You can create activities, manage their items (questions/tasks), and retrieve results.
Method | Endpoint | Description | Scope |
|
| List activities for a test | read |
|
| Get activity with response data | read |
|
| Create an activity | write |
|
| Update an activity | write |
|
| Delete an activity | write |
|
| Add an item to an activity | write |
|
| Update an activity item | write |
|
| Delete an activity item | write |
Messages
Method | Endpoint | Description | Scope |
|
| List messages for a test | read |
Invites
Method | Endpoint | Description | Scope |
|
| Get invite settings for a test | read |
|
| List invites for a test | read |
|
| Update invite settings | write |
|
| Update an invite | write |
Shipping
Method | Endpoint | Description | Scope |
|
| List shipments for a test | read |
|
| Update a shipment | write |
ID Verification
Method | Endpoint | Description | Scope |
|
| Require ID verification for a test | write |
|
| Remove ID verification requirement | write |
Community
Manage your tester community, the pool of testers available across all your tests.
Method | Endpoint | Description | Scope |
|
| List company custom fields | read |
|
| List community testers | read |
|
| Get a specific community tester | read |
|
| Update a community tester | write |
|
| Bulk create community testers | write |
|
| Add tags to a tester | write |
|
| Remove tags from a tester | write |
|
| Require ID verification | write |
|
| Remove ID verification requirement | write |
Pagination
List endpoints return paginated results. Control pagination with these query parameters:
Parameter | Description | Default |
| Page number (1-based) |
|
| Number of items per page | Varies by endpoint |
Response format:
{
"data": [ ... ],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 20,
"total": 98
}
}Use the meta fields to navigate through pages of results.
Rate Limiting
API requests are rate-limited per client to ensure fair usage and platform stability.
Scope | Default Limit |
Read ( | Per-client limit (configured by BetaTesting) |
Write ( | 30 requests per minute |
Rate limit status is communicated via response headers:
Header | Description |
| Maximum requests allowed in the current window |
| Requests remaining in the current window |
| Seconds until the rate limit resets (only on 429 responses) |
When you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait for the duration specified in Retry-After before retrying.
Idempotency
For write operations (POST, PATCH, DELETE), you can include an Idempotency Key to prevent duplicate actions caused by network retries or client errors.
How to use it:
Include the Idempotency-Key header with a unique value (e.g., a UUID) on any write request:
POST /api/external/v2/tests
Authorization: Bearer btst_your_key
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{ "name": "Mobile App Beta" }
Behavior:
If the same
Idempotency-Keyis sent again within 24 hours, the API returns the cached response from the original request instead of processing the request againThe replayed response includes the header
X-Idempotency-Replayed: trueso you can distinguish it from a fresh responseEach idempotency key is scoped to your company — different companies can use the same key without conflict
Best practice: Use idempotency keys for any operation where a duplicate would be problematic, such as creating tests, accepting testers, or sending messages.
Error Responses
The API uses standard HTTP status codes:
Status | Meaning |
| Success |
| Resource created successfully |
| Resource deleted successfully (no body) |
| Unauthorized — invalid, missing, or expired credentials |
| Forbidden — insufficient scope, IP not allowed, or API access not enabled |
| Resource not found (or does not belong to your company) |
| Validation error — invalid or missing request parameters |
| Rate limit exceeded |
| Internal server error |
Error responses include a descriptive message:
{
"error": "Validation failed",
"message": "The status field must be one of: draft, to_do, in_progress, complete."
}
Best Practices
Use pagination - Always iterate through pages for list endpoints rather than assuming all data fits in one response
Handle rate limits gracefully - Implement exponential backoff when you receive a 429 response
Use idempotency keys - Always include an
Idempotency-Keyfor write operations, especially in automated pipelinesRequest minimal scopes - If your OAuth2 client only reads data, request only
api:readCache when appropriate - For data that doesn't change frequently (e.g., test details, custom fields), cache responses on your end to reduce API calls
Check the Swagger docs - For complete request/response schemas, parameter details, and example payloads, refer to the interactive documentation on your Integrations page