참가자

콘테스트 참가자 및 그들의 참가 내역을 관리합니다.

참가자 목록 조회

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

Public or Private API Key

특정 콘테스트의 참가자 목록을 페이지네이션하여 반환합니다.

경로 매개변수

contestIdstring required

고유한 콘테스트 식별자

쿼리 매개변수

pagenumber

페이지 번호, 1부터 시작. 기본값: 1

limitnumber

페이지당 참가자 수 (1-100). 기본값: 20

searchstring

이메일 또는 이름으로 검색 (대소문자 구분 없음)

요청

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(`페이지 ${pagination.page} / 총 ${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"페이지 {result['pagination']['page']} / 총 {result['pagination']['totalPages']} 페이지")
print(result["data"])

응답

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
  }
}

응답 필드

idstring

참가자의 고유 식별자

emailstring

참가자의 이메일 주소

namestring | null

참가자의 이름

phonestring | null

참가자의 전화번호

pointsnumber

획득한 총 포인트

emailConfirmedboolean

이메일 확인 여부

disqualifiedboolean

참가 자격 박탈 여부

referralCodestring | null

이 참가자에 대한 고유 추천 코드

createdAtstring

참가자가 생성된 ISO 8601 타임스탬프

참가자 상세 조회

GET/api/v1/entries/:entryId

Public or Private API Key

특정 참가자에 대한 상세 정보를 조회합니다.

경로 매개변수

entryIdstring required

고유 참가자 식별자

요청

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"])

응답

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"
  }
}

참가자 생성

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

Private API Key Required

콘테스트에 새 참가자를 생성합니다. 비공개 API 키가 필요합니다.

경로 매개변수

contestIdstring required

고유한 콘테스트 식별자

요청 본문

emailstring

참가자의 이메일 주소입니다. 이메일 또는 전화번호 중 하나는 필수입니다.

phonestring

참가자의 전화번호입니다. 이메일 또는 전화번호 중 하나는 필수입니다.

namestring

참가자의 이름 (선택 사항)

referralCodestring

다른 참가자로부터 받은 추천 코드 (선택 사항)

customFieldDataobject

사용자 정의 필드 데이터 객체 (선택 사항)

요청

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"])

응답 (201 Created)

json

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

이메일이 이미 대회에 존재하는 경우, 응답에는 "alreadyExists": true가 포함되며 상태 코드는 200 OK가 됩니다.

참가 정보 수정

PUT/api/v1/entries/:entryId

Private API Key Required

기존 참가 정보 업데이트. 최소 하나 이상의 필드를 제공해야 합니다.

경로 매개변수

entryIdstring required

고유 참가자 식별자

요청 본문

namestring

수정된 이름

emailstring

수정된 이메일 주소

phonestring

수정된 전화번호

customFieldDataobject

수정된 사용자 정의 필드 데이터

요청

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"])

응답

json

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

참가 자격 박탈

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

Private API Key Required

참가 자격을 박탈하거나 재자격을 부여합니다.

경로 매개변수

entryIdstring required

고유 참가자 식별자

요청 본문

disqualifyboolean

true로 설정하면 자격 박탈, false로 설정하면 재자격 부여. 생략 시 토글 동작.

요청

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"

응답

json

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

포인트 조정

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

Private API Key Required

엔트리의 포인트를 추가하거나 차감합니다. 포인트는 0 미만으로 내려갈 수 없습니다.

경로 매개변수

entryIdstring required

고유한 엔트리 식별자

요청 본문

pointsnumber required

추가할(양수) 또는 차감할(음수) 포인트

reasonstring required

조정 사유

요청

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']}")

응답

json

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

포인트를 차감하려면 음수 값을 사용하세요:

json

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

오류 응답

상태 코드	오류	설명
`400`	points 또는 reason 누락	두 필드 모두 필수입니다
`403`	개인 키 필요	이 엔드포인트는 개인 API 키가 필요합니다
`404`	엔트리 없음	해당 ID의 엔트리가 존재하지 않습니다