Revup API overview

What you can do with the API

The Revup API is a JSON HTTP API for connecting your own apps, data warehouse, or backend services to your Revup account. Use it to:

• Read your account and list or retrieve promotions.
• List and retrieve participants, including their submission state.
• Create or import participants, up to 50 per request, and optionally update existing ones.
• Add bonus entries to an existing participant by email or phone.
• List contacts and winners, including prize assignment details.

For every endpoint, parameter, response example, and error code, see the Revup API reference.

To work with Revup from ChatGPT, Claude, or another AI assistant instead of writing code, see the Revup MCP documentation.

Before you start

• Create an API key in Account → API. Each key belongs to one account, can include only the scopes it needs, and can be limited to specific promotions. See Create and manage Revup API keys.
• Keep keys on your server. Never place a key in browser code, a mobile app, or source control.
• Send requests over HTTPS to https://revup.com/api/v1 with the key in the x-api-key header.

Make your first request

List the promotions your key can access:

curl https://revup.com/api/v1/promotions \
  -H "x-api-key: rvup_v1_your_key_here" \
  -H "accept: application/json"

A successful response includes "success": true and a data list. Collection endpoints return a next_cursor; pass it as the cursor parameter to fetch the next page, and stop when has_more is false.

Scopes

A request without the required scope returns insufficient_scope. A request for a promotion the key cannot access returns promotion_restricted.

Rate limits

Limits apply per key: 120 read requests, 200 write requests, and 60 heavy read requests per minute. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. When a key is limited, the API returns HTTP 429 with a Retry-After header. Contact support if a production integration needs a higher limit.

Avoid duplicate writes

Include an Idempotency-Key header when adding bonus entries (required) or when a participant update sets initial entries. If a request times out, retry with the same key and body so Revup does not add the entries twice.

Troubleshooting

• 401 error: The key is missing, mistyped, or revoked. Check the x-api-key header or create a new key.
• 403 error: Add the missing scope to a new key, or check whether the key is limited to other promotions.
• 422 error: A parameter failed validation. The error message names the problem. Forms cannot receive bonus entries.
• 429 error: Wait for the Retry-After interval before retrying.

Include the request_id from the response when you contact support. Never send your API key.