Check my entries

Every frontend has a page where a consumer types their phone number and sees what happened to their entries. It is how someone who closed the page while a receipt was being checked learns the result.

The call

A POST, so the phone never travels in an address. Forward the consumer's IP address in UTC-Client-IP.

curl -s -X POST "$UTC_API_URL/api/v1/submissions/lookup" \
  -H "Authorization: Bearer $UTC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "UTC-Client-IP: 196.41.60.77" \
  -d '{"phone":"0712345678"}'

{
  "submissions": [
    {
      "id": "3f2b8f0e-7c1a-4d55-9a53-0d7e2f5c9b11",
      "ref": "K7M2Q9",
      "date": "2026-10-13",
      "display_status": "entered",
      "message": "You're in. Good luck!",
      "entries": 1
    }
  ],
  "total_entries": 1,
  "timezone": "Africa/Dar_es_Salaam"
}

const { submissions, total_entries } = await utc.lookup({ phone: phone }, { clientIp: consumerIp })

What to show

• One row per submission: ref, date, the label for display_status, message, and entries.
• total_entries as the headline: it counts accepted submissions only.
• For an empty list: "No entries for this number." The reply for a phone we have never seen has the same shape as any other, on purpose.
• date is a day in the campaign's timezone, never a time.

The labels for display_status are on Concepts. Rejected submissions are in the list too, with their message, so the consumer can see why.

Limits

This call answers a question about a phone number, so it is limited tightly:

• 5 lookups per phone number every 10 minutes.
• 30 lookups per consumer address range every 10 minutes. A range is the /24 around an IPv4 address or the /48 around an IPv6 one.

Over either, the answer is 429 rate_limited with Retry-After. Show the rate_limited message. Without UTC-Client-IP the address limit counts your server's own address, so every consumer shares one allowance: always forward it. Take the address from your host's trusted header (on Vercel, the first entry of x-forwarded-for), never from the request body.

Polling one submission

Right after a submission you already have its id; poll that instead of looking the phone up again. It has no per-phone limit.

curl -s "$UTC_API_URL/api/v1/submissions/$SUBMISSION_ID" \
  -H "Authorization: Bearer $UTC_API_KEY"