Entries

Manage contest participants and their entries.

List Entries

GET/api/v1/contests/:contestId/entries

Public or Private API Key

Returns a paginated list of entries for a specific contest.

Path Parameters

contestIdstring required

The unique contest identifier

Query Parameters

pagenumber optional

Page number, starting at 1. Default: 1

limitnumber optional

Entries per page (1-100). Default: 20

searchstring optional

Search by email or name (case-insensitive)

Request

bash

curl -X GET "https://blitzrocket.com/api/v1/contests/clx1abc123/entries?page=1&limit=10" \
  -H "x-api-key: your_api_key_here"

javascript

const contestId = "clx1abc123";
const params = new URLSearchParams({ page: "1", limit: "10" });

const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/entries?${params}`,
  {
    headers: { "x-api-key": "your_api_key_here" },
  }
);

const { data, pagination } = await response.json();
console.log(`Page ${pagination.page} of ${pagination.totalPages}`);
console.log(data);

python

import requests

contest_id = "clx1abc123"
response = requests.get(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/entries",
    headers={"x-api-key": "your_api_key_here"},
    params={"page": 1, "limit": 10}
)

result = response.json()
print(f"Page {result['pagination']['page']} of {result['pagination']['totalPages']}")
print(result["data"])

Response

json

{
  "success": true,
  "data": [
    {
      "id": "entry_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "phone": null,
      "points": 150,
      "emailConfirmed": true,
      "disqualified": false,
      "referralCode": "REF-XYZ789",
      "createdAt": "2025-06-15T10:30:00.000Z"
    },
    {
      "id": "entry_def456",
      "email": "john@example.com",
      "name": "John Smith",
      "phone": "+1234567890",
      "points": 85,
      "emailConfirmed": true,
      "disqualified": false,
      "referralCode": "REF-ABC456",
      "createdAt": "2025-06-16T14:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1523,
    "totalPages": 153
  }
}

Response Fields

idstring

Unique identifier for the entry

emailstring

Participant's email address

namestring | null

Participant's name

phonestring | null

Participant's phone number

pointsnumber

Total points earned

emailConfirmedboolean

Whether the email has been confirmed

disqualifiedboolean

Whether the entry is disqualified

referralCodestring | null

Unique referral code for this entry

createdAtstring

ISO 8601 timestamp when the entry was created

Get Entry

GET/api/v1/entries/:entryId

Public or Private API Key

Retrieve detailed information about a specific entry.

Path Parameters

entryIdstring required

The unique entry identifier

Request

bash

curl -X GET https://blitzrocket.com/api/v1/entries/entry_abc123 \
  -H "x-api-key: your_api_key_here"

javascript

const entryId = "entry_abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/entries/${entryId}`,
  {
    headers: { "x-api-key": "your_api_key_here" },
  }
);

const { data } = await response.json();
console.log(data);

python

import requests

entry_id = "entry_abc123"
response = requests.get(
    f"https://blitzrocket.com/api/v1/entries/{entry_id}",
    headers={"x-api-key": "your_api_key_here"}
)

data = response.json()
print(data["data"])

Response

json

{
  "success": true,
  "data": {
    "id": "entry_abc123",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "phone": null,
    "points": 150,
    "pointsUsed": 25,
    "emailConfirmed": true,
    "disqualified": false,
    "referralCode": "REF-XYZ789",
    "contestId": "clx1abc123def456",
    "contestTitle": "Summer Giveaway 2025",
    "referralsCount": 3,
    "bonusActionsCompleted": 5,
    "totalPurchaseValue": 129.99,
    "totalPurchaseCount": 2,
    "createdAt": "2025-06-15T10:30:00.000Z"
  }
}

Create Entry

POST/api/v1/contests/:contestId/entries

Private API Key Required

Create a new entry for a contest. Requires a private API key.

Path Parameters

contestIdstring required

The unique contest identifier

Request Body

emailstring optional

Participant's email address. Either email or phone is required.

phonestring optional

Participant's phone number. Either email or phone is required.

namestring optional

Participant's name (optional)

referralCodestring optional

Referral code from another participant (optional)

customFieldDataobject optional

Custom field data object (optional)

Request

bash

curl -X POST https://blitzrocket.com/api/v1/contests/clx1abc123/entries \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "referralCode": "REF-XYZ789"
  }'

javascript

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/entries`,
  {
    method: "POST",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "newuser@example.com",
      name: "New User",
      referralCode: "REF-XYZ789",
    }),
  }
);

const { data } = await response.json();
console.log(data);

python

import requests

contest_id = "clx1abc123"
response = requests.post(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/entries",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={
        "email": "newuser@example.com",
        "name": "New User",
        "referralCode": "REF-XYZ789"
    }
)

data = response.json()
print(data["data"])

Response (201 Created)

json

{
  "success": true,
  "data": {
    "entryId": "entry_new789",
    "email": "newuser@example.com",
    "alreadyExists": false,
    "isReferred": true,
    "pointsAwarded": {
      "advocate": 10,
      "friend": 5
    }
  }
}

If the email already exists in the contest, the response will include "alreadyExists": true with a 200 OK status.

Update Entry

PUT/api/v1/entries/:entryId

Private API Key Required

Update an existing entry's information. At least one field must be provided.

Path Parameters

entryIdstring required

The unique entry identifier

Request Body

namestring optional

Updated name

emailstring optional

Updated email address

phonestring optional

Updated phone number

customFieldDataobject optional

Updated custom field data

Request

bash

curl -X PUT https://blitzrocket.com/api/v1/entries/entry_abc123 \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Updated",
    "phone": "+1987654321"
  }'

javascript

const entryId = "entry_abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/entries/${entryId}`,
  {
    method: "PUT",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Jane Updated",
      phone: "+1987654321",
    }),
  }
);

const { data } = await response.json();
console.log(data);

python

import requests

entry_id = "entry_abc123"
response = requests.put(
    f"https://blitzrocket.com/api/v1/entries/{entry_id}",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={
        "name": "Jane Updated",
        "phone": "+1987654321"
    }
)

data = response.json()
print(data["data"])

Response

json

{
  "success": true,
  "data": {
    "id": "entry_abc123",
    "email": "jane@example.com",
    "name": "Jane Updated",
    "phone": "+1987654321",
    "points": 150
  }
}

Disqualify Entry

POST/api/v1/entries/:entryId/disqualify

Private API Key Required

Disqualify or re-qualify an entry.

Path Parameters

entryIdstring required

The unique entry identifier

Request Body

disqualifyboolean optional

Set to true to disqualify, false to re-qualify. Omit to toggle.

Request

bash

curl -X POST https://blitzrocket.com/api/v1/entries/entry_abc123/disqualify \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{"disqualify": true}'

javascript

const entryId = "entry_abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/entries/${entryId}/disqualify`,
  {
    method: "POST",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ disqualify: true }),
  }
);

const { data } = await response.json();
console.log(data.message);
// => "Entry has been disqualified"

python

import requests

entry_id = "entry_abc123"
response = requests.post(
    f"https://blitzrocket.com/api/v1/entries/{entry_id}/disqualify",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={"disqualify": True}
)

data = response.json()
print(data["data"]["message"])
# => "Entry has been disqualified"

Response

json

{
  "success": true,
  "data": {
    "entryId": "entry_abc123",
    "disqualified": true,
    "message": "Entry has been disqualified"
  }
}

Adjust Points

POST/api/v1/entries/:entryId/points

Private API Key Required

Add or remove points from an entry. Points cannot go below zero.

Path Parameters

entryIdstring required

The unique entry identifier

Request Body

pointsnumber required

Points to add (positive) or remove (negative)

reasonstring required

Reason for the adjustment

Request

bash

curl -X POST https://blitzrocket.com/api/v1/entries/entry_abc123/points \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 50,
    "reason": "Bonus for completing survey"
  }'

javascript

const entryId = "entry_abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/entries/${entryId}/points`,
  {
    method: "POST",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      points: 50,
      reason: "Bonus for completing survey",
    }),
  }
);

const { data } = await response.json();
console.log(`Points: ${data.previousTotal} → ${data.newTotal}`);

python

import requests

entry_id = "entry_abc123"
response = requests.post(
    f"https://blitzrocket.com/api/v1/entries/{entry_id}/points",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={
        "points": 50,
        "reason": "Bonus for completing survey"
    }
)

data = response.json()
print(f"Points: {data['data']['previousTotal']} → {data['data']['newTotal']}")

Response

json

{
  "success": true,
  "data": {
    "message": "Successfully added 50 points",
    "previousTotal": 150,
    "newTotal": 200,
    "adjustment": 50
  }
}

To remove points, use a negative value:

json

{
  "points": -25,
  "reason": "Penalty for rule violation"
}

Error Responses

Common error responses for this endpoint.

Status	Error	Description
`400`	Missing points or reason	Both fields are required
`403`	Private key required	This endpoint requires a private API key
`404`	Entry not found	No entry exists with the given ID