Overview
Corvus is RAVEN5's sweepstakes platform. Your entry form sends each entry to Corvus through this API, and Corvus stores it against the sweepstake your API key belongs to.
Base URL: https://corvus.raven5.com/api. Requests and responses are JSON, except file uploads, which are multipart/form-data.
| Endpoint | What it does |
|---|---|
| GET /profile | The sweepstake's name, rules, privacy text, dates and prizes, for showing on your site. |
| POST /enter | Records one entry. Returns an entry code. |
| POST /media | Attaches images (receipts, photos) to an entry, using its entry code. |
Authentication
Each sweepstake has one API key, supplied by RAVEN5. Send it on every request, with an Accept header so errors come back as JSON:
Authorization: Bearer YOUR_API_KEY
Accept: application/json
- The key decides which sweepstake an entry goes to. You can't choose it in the request.
- Keep the key on your server. Anyone who has it can submit entries.
- A missing, unknown or revoked key gets 401 Unauthorized. RAVEN5 revokes keys when a sweepstake closes, and can restore the same key if it reopens.
Limits
- 60 requests per minute per IP address. Request 61 within a minute gets 429 Too Many Attempts with a Retry-After header (seconds). That entry is not saved, so wait and send it again.
- If entries are sent from your server, they all share your server's IP address. Talk to RAVEN5 before a launch that could go past 60 entries a minute.
- Uploads: jpg, jpeg, png or webp, up to 10 MB per file.
GET /profile
Returns the sweepstake your key belongs to.
curl https://corvus.raven5.com/api/profile \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"
Response fields
| Field | Type | Notes |
|---|---|---|
| name | string | The sweepstake's name. |
| description | string or null | |
| rules | HTML or null | Full official rules. |
| rules_mini | HTML or null | Short rules for the bottom of a form. |
| privacy | HTML or null | Privacy text. |
| privacy_link | URL or null | Link to the privacy policy. |
| start_at | date or null | When entries open. Null means already open. |
| end_at | date or null | When entries close. |
| select_at | date or null | When winners are drawn. |
| image_primary_url | URL or false | The sweepstake's main image, or false if there isn't one. |
| prizes | list | Each prize has name and description. |
Dates are UTC, formatted YYYY-MM-DD HH:MM:SS (Eastern time is UTC−5, or UTC−4 during daylight saving). The response may include other fields; ignore anything not listed here.
{
"success": true,
"data": {
"name": "2026 Summer Sweepstakes",
"description": "Win a trip for two.",
"rules": "<h2>Official Rules</h2><p>No purchase necessary...</p>",
"rules_mini": "No purchase necessary. Open to residents of...",
"privacy": "<p>We collect...</p>",
"privacy_link": "https://example.com/privacy",
"start_at": "2026-06-01 04:00:00",
"select_at": "2026-09-05 16:00:00",
"end_at": "2026-08-31 03:59:59",
"image_primary_url": "https://storage.googleapis.com/.../summer.jpg",
"prizes": [
{ "name": "Grand prize", "description": "Trip for two" }
]
}
}
POST /enter
Records one entry and returns its entry code. Send JSON with Content-Type: application/json.
Fields
| Field | Required | Rules |
|---|---|---|
| reference_id | Required | Your own ID for the entry (order number, transaction ID). 5 to 200 characters. |
| name | Required | The entrant's name, usually first and last. 3 to 200 characters. |
| Optional | A valid email address. | |
| phone | Optional | Free text, up to 200 characters. Not checked. |
| state / province | Optional | Send either name. 2-letter code: a US state (plus DC and PR) or a Canadian province or territory (AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT). |
| zip / postal_code | Optional | Send either name. US ZIP 12345 or 12345-6789, or Canadian A1A 1A1. |
| date_birth | Optional | YYYY-MM-DD, in the past. |
| agree_terms | Optional | true / false (1 / 0). |
| agree_marketing | Optional | true / false (1 / 0). Whether the entrant opted in to marketing. |
| latitude | Optional | Number between -90 and 90. |
| longitude | Optional | Number between -180 and 180. |
Only send the fields above.
Any other field (a typo, an extra form field) rejects the whole entry with "This field is not allowed." code and sweepstake_id are accepted but ignored.
- Each call creates a new entry. Corvus does not remove duplicates by reference_id or email, so send each entry once.
- State / province and ZIP / postal code are tidied before they're checked: "tx" becomes TX, and "m5v2t6" becomes M5V 2T6. Both are stored in the same place whichever name you send, and a validation error for either comes back under province or postal_code.
curl -X POST https://corvus.raven5.com/api/enter \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"reference_id": "order-0012345",
"name": "Jane Doe",
"email": "jane@example.com",
"state": "CO",
"zip": "80465",
"agree_terms": 1,
"agree_marketing": 0
}'
const res = await fetch('https://corvus.raven5.com/api/enter', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CORVUS_API_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({ reference_id: 'order-0012345', name: 'Jane Doe', email: 'jane@example.com' }),
});
const body = await res.json();
if (res.ok) {
const entryCode = body.data.code; // keep this to attach media
} else if (res.status === 429) {
// too many requests: wait Retry-After seconds, then send again
}
{
"success": true,
"data": { "code": "bfca8a22-edfe-4706-9197-d21316244ba3" }
}
{
"success": false,
"message": {
"validation_errors": {
"province": ["Province / state must be a 2-letter Canadian province or US state code (e.g. ON, BC, CO, TX)."]
}
}
}
POST /media
Attaches one or more images to an entry. Send multipart/form-data.
| Field | Required | Rules |
|---|---|---|
| entrant_code | Required | The code returned by POST /enter for an entry in the same sweepstake. |
| file | One of these | A single image: jpg, jpeg, png or webp, up to 10 MB. |
| files[] | One of these | Several images in one request, same rules for each. |
curl -X POST https://corvus.raven5.com/api/media \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-F "entrant_code=bfca8a22-edfe-4706-9197-d21316244ba3" \
-F "files[]=@receipt-front.jpg" \
-F "files[]=@receipt-back.jpg"
{
"success": true,
"data": {
"entrant_code": "bfca8a22-edfe-4706-9197-d21316244ba3",
"media": [
{
"id": 11,
"uuid": "991e1583-b93d-4b8f-9ef4-9c607aa913c2",
"name": "receipt-front",
"file_name": "4f0c2d7e-0b7a-4c55-9f3e-2a6c1d9e8b10.jpg",
"mime_type": "image/jpeg",
"size": 204800,
"url": "https://storage.googleapis.com/r5-corvus/..."
}
]
}
}
Stored files get a random name. An entry code from another sweepstake, or one that doesn't exist, gets 404.
Errors
| Status | When, and the response body |
|---|---|
| 200 | Entry saved, or profile returned (201 for /media). {"success": true, "data": {...}} |
| 401 | API key missing, unknown or revoked. {"error": {"message": "Unauthorized"}} |
| 403 | /enter: the sweepstake has ended. The message gives the closing time (Eastern). Entries before the start date are accepted, so you can test before launch. {"success": false, "message": "This sweepstake has ended. Entries closed Nov 15, 2026 at 11:59:59 PM EST."} |
| 404 | /media: the entry code isn't in this sweepstake. {"success": false, "message": "Entrant not found for this sweepstake."} |
| 422 | A field failed its rules, a required field is missing, or a field isn't allowed. {"success": false, "message": {"validation_errors": {...}}} |
| 429 | More than 60 requests in a minute from your IP. Wait Retry-After seconds and send again. {"message": "Too Many Attempts."} |
| 500 | Something went wrong on our side. Safe to retry once; email help@raven5.com if it repeats. {"success": false, "message": "Unknown error"} |
| 503 | Corvus is down for maintenance (every endpoint). Nothing is saved: wait Retry-After seconds (300) and send it again. {"success": false, "message": "Service temporarily unavailable"} |
Org API
Everything above is the entry API: one key per sweepstake, used by the entry form. The Org API is for organizations that manage their own sweepstakes (agencies and companies with an account in Corvus). It uses an organization master key, and everything it does is limited to that organization.
Base URL: https://corvus.raven5.com/api/v1/org. JSON in, JSON out. The machine-readable spec (OpenAPI 3) is at /docs/org-api.yaml.
The Org API does not create entries. Entries still go to POST /enter with each sweepstake's entry_key.
Send GET https://corvus.raven5.com/api/v1/org to see your organization. It also returns corvus.version (the release running now), capabilities (what your key can do), rate_limit (requests a minute for this key) and docs (this page). The organization object is unchanged.
Org API: authentication and limits
Create a master key in your organization panel (Master keys), or ask RAVEN5. Send it on every request:
Authorization: Bearer cvk_YOUR_MASTER_KEY
Accept: application/json
- A key is shown once, when it is created. It expires in 60 days at most. About a week before, we email your organization's contact address.
- You can hold several active keys, so you can rotate without downtime: create the new key, switch over, revoke the old one.
- A key made through the API also emails the contact address (never the key itself).
- A missing, unknown, expired or revoked key gets 401 with a message that says which. A suspended organization gets 403.
- 60 requests per minute per key. Past that, 429 with a Retry-After header. The count is kept per server, so treat the limit as approximate.
- Keep the key on your server. It can create sweepstakes and more keys.
Org API: lifecycle
- A new sweepstake is a draft. Change it with PATCH while it is a draft.
- POST .../submit makes it pending and tells RAVEN5. From then on it is locked to you (409 on changes) until RAVEN5 approves it or sends it back to draft. There is no endpoint to approve or change status.
- Draft and pending sweepstakes still take entries, so you can test the entry form. Once approved, status is scheduled, live or ended by its dates.
- Send dates as YYYY-MM-DD in Eastern time. A start date means 12:00:01 AM ET, an end date means 11:59:59 PM ET. Timestamps in responses are Eastern with an offset.
- Rules are plain text: tags are stripped, blank lines make paragraphs.
- /contests works everywhere /sweepstakes does (same behavior and JSON, which always says sweepstake).
- Another organization's id is a 404, the same as one that doesn't exist.
Org API: endpoints
| Endpoint | What it does |
|---|---|
| GET / | Your organization. |
| GET /sweepstakes | List your sweepstakes, newest first. Filter with ?status=draft|pending|scheduled|live|ended; page with ?page= and ?per_page= (up to 100). |
| POST /sweepstakes | Create a sweepstake as a draft. Returns it with its entry key. |
| GET /sweepstakes/{id} | One sweepstake, with status and entry key. |
| PATCH /sweepstakes/{id} | Change a draft. 409 once it is pending or approved. |
| POST /sweepstakes/{id}/submit | Submit a draft for RAVEN5 review (draft to pending). 409 if it is not a draft. |
| GET /sweepstakes/{id}/stats | Total entrants, yesterday and today (Eastern days), and when the last entry came in. |
| GET /keys | Your master keys: prefix, status, expiry, last used. Never the key itself. |
| POST /keys | Create a master key (days 1 to 60, default 60). The plain key is returned once. |
| DELETE /keys/{id} | Revoke a master key. |
Create fields
| Field | Required | Rules |
|---|---|---|
| name | Required | Text, up to 255 characters. |
| client_name | Required | The brand or client. Text, up to 100 characters. |
| start_at | Required | Date, YYYY-MM-DD, Eastern time. Means 12:00:01 AM ET. |
| end_at | Required | Date, YYYY-MM-DD, on or after start_at. Means 11:59:59 PM ET. |
| rules | Optional | Official rules, plain text, up to 60,000 characters. Can be added or changed while a draft. |
Any other field is refused with "This field is not allowed." (for example approval_status). PATCH takes the same fields, all optional.
Org API: example
curl -X POST https://corvus.raven5.com/api/v1/org/sweepstakes \
-H "Authorization: Bearer cvk_YOUR_MASTER_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "Summer Giveaway",
"client_name": "Acme",
"start_at": "2026-12-01",
"end_at": "2026-12-31",
"rules": "No purchase necessary.\n\nOpen to US residents 18+."
}'
curl -X POST https://corvus.raven5.com/api/v1/org/sweepstakes/123/submit \
-H "Authorization: Bearer cvk_YOUR_MASTER_KEY" \
-H "Accept: application/json"
{
"sweepstake": {
"id": 123,
"name": "Summer Giveaway",
"client_name": "Acme",
"status": "draft",
"start_at": "2026-12-01T00:00:01-05:00",
"end_at": "2026-12-31T23:59:59-05:00",
"rules": "No purchase necessary.\n\nOpen to US residents 18+.",
"entry_key": "...",
"created_at": "2026-11-05T14:30:00-05:00"
}
}
GET https://corvus.raven5.com/api/v1/org/sweepstakes/123/stats
{ "stats": { "sweepstake_id": 123, "total_entrants": 1520, "yesterday": 210, "today": 87, "last_entry_at": "2026-11-05T14:02:11-05:00", "timezone": "America/Toronto" } }
POST https://corvus.raven5.com/api/v1/org/keys { "name": "Cookbook", "days": 45 }
{ "key": { "id": 7, "name": "Cookbook", "prefix": "cvk_AbCd", "status": "active", "expires_at": "...", "plain_key": "cvk_..." },
"note": "Store plain_key now. It is shown only once." }
Org API: errors
| Status | When |
|---|---|
| 401 | Missing, unknown, expired or revoked key. The message says which, and what to do. |
| 403 | Your organization is not active. |
| 404 | Not found, or it belongs to another organization. |
| 409 | The sweepstake is not a draft, so it can not be changed or submitted. |
| 422 | Validation failed (bad or unknown field, end before start, key days over 60, organization has no contact email). |
| 429 | Over 60 requests a minute for this key. Wait Retry-After seconds. |
Every error is JSON with a message. Validation errors (422) add an errors object keyed by field.
Corvus MCP
An MCP server (Model Context Protocol) for asking an AI app about sweepstakes: what is live, how many entered today, when the last entry came in. Server address: https://corvus.raven5.com/mcp (streamable HTTP).
Add that address as a connector in your AI app (in Claude: Settings, Connectors, add custom connector). You are sent to a Corvus page showing "Connect Claude?" with your account; sign in if asked, then click Allow. There is no key to copy.
- No personal data, and almost all read-only. It returns program details and counts. It never returns entrant or winner names, emails or any contact detail, and never an entry key. It can't create entries or manage keys. When RAVEN5 turns writing on, it can also create, edit and submit drafts only; RAVEN5 reviews and approves before anything goes live.
- It shows the sweepstakes your Corvus account can see, and can never do more than you can do yourself: if your access ends, so does the connection. If your account isn't set up for it, the connection is refused. Sign-ins last a day and renew for up to 30 days.
- Limited to 60 requests a minute per person. Dates are Eastern time. Sweepstake names and rules are text written by organizations, handed to the AI as data. Most tools take one sweepstake id or several, to compare programs.
| Tool | What it does |
|---|---|
| whoami | Who is connected and what they can see. |
| list_sweepstakes | Sweepstakes (also called contests), newest first, with their organization. Filter by status: draft, pending, scheduled, live, ended. "What is live?" |
| get_sweepstake | One sweepstake: name, brand, status, Eastern dates and the rules text. |
| get_sweepstake_stats | Total entrants, yesterday, today and when the last entry came in. "How many entered today?" Takes one id or several. |
| count_entrants_by_day | Entries per Eastern day, up to 92 days back. One id or several. |
| get_entry_breakdown | Entries by source (API or imported), and how many agreed to the terms and to marketing. Counts only. |
| list_prizes | The prizes of one sweepstake. One id or several. |
| get_winner_status | Selections at each winner stage, split by winner or alternate and by prize, with claim deadlines (next, overdue), forfeits by reason and alternates promoted. Counts only. |
| get_winner_compliance | W-9s by status, acceptances and releases recorded, guests signed, skill-question attempts. Counts only. |
| get_winner_emails | Winner emails by type: sent, delivered, failed, opened, clicked. Never recipients. |
| get_draw_history | Each draw: status, when it ran, pool size, and winners and alternates per prize. |
| get_program_setup | How a sweepstake is set up (rules, privacy, dates, prizes, regions, claim window, W-9 threshold) and what is missing. |
| list_organizations | Organizations, id and name only (staff see all; a key sees its own). Used to pick organization_id when creating a draft. |
| get_capabilities | What Corvus can do for this connection: who is connected, every tool (read-only or write), whether writing is on, the rules, the version and the recent changes. Call it first if unsure. |
| create_sweepstake_draft | Creates a draft sweepstake: name, client name, start and end date (Eastern) and optional plain-text rules. Draft only; RAVEN5 reviews and approves before anything goes live. |
| update_sweepstake_draft | Changes those fields on a draft. A pending, approved or live program is refused. |
| submit_sweepstake | Draft to pending, and the RAVEN5 admins are emailed. Cannot approve or launch. |
Corvus API v1.8 · Powered by RAVEN5 · Questions: help@raven5.com