Send your contestant list to Pageant Alert

What this is

Pageant Alert gives a pageant director a one-way broadcast channel to her contestants — push notifications and email — plus a contestant list that survives between seasons. It is free for directors and free for contestants.

There is one endpoint. CSV upload, Jotform exports, Bombyhead, and Dempsi are all clients of the same path; you would be another.

Pageant Alert holds no account mapping

There is no account linking, no OAuth, and no per-product integration code on our side. The director is the join: she creates a key in her Pageant Alert settings, pastes it into your product, and every export authenticates as her. A director with three accounts in your system exports all three into one Pageant Alert login and her list is whole.

Don't build a linking table. It is deliberately not needed, and adding one creates a retrofit problem later.

US pageants only

Addresses, phone numbers, and dates are handled in US formats, and contestant-facing pageant discovery runs on US ZIP codes. A non-US state or ZIP on a contestant is dropped rather than stored — the row still lands, but those fields would feed a feature that cannot use them.

The endpoint

`POST https://pageantalert.com/api/import`, with `Content-Type: application/json`.

Authenticate with an API key

`Authorization: Bearer pa_live_…`

The director creates a key under Settings → Connected tools in her Pageant Alert dashboard, and pastes it into your product. Store it against her account in your system.

• A key reaches this endpoint and nothing else. It cannot sign in as her, read her roster, or send a message.
• She can turn it off from her own settings without changing her password or affecting anything else.
• On a `401`, the key is wrong or has been revoked. Clear what you stored and ask her for a new one — never retry in a loop.
• If she has no account, send her to pageantalert.com/register. It takes about a minute, and there is no billing step.

HTTP Basic with her email and password also works, and is how Bombyhead and Dempsi started. Don't use it for a new integration: it hands you the credential that also opens her dashboard, so a breach in your system becomes a full account takeover rather than an unwanted import.

The request

Send `source` (a short name for your product), the contest, and the contestants. `send_invites` defaults to true.

• contest — send `{ "id": "…" }` once you have one. First time, send `name` and `end_date` (`YYYY-MM-DD`) and we create it and return the id. Store that id and use it from then on.
• contestants[] — `name` and `email` are required. Optional: `phone`, `state`, `zip`, `dob`, `guardian_name`, `guardian_phone`, `titles`.

Identity is email and name together

Several contestants can share one address, and it is common: a mother entering two daughters puts her own address on both entry forms, and a young child has no address of her own. Roughly one account in twenty enters more than one girl in the same pageant.

Same address with a different name is a different girl, and both records are created. Same address and same name is the same girl, upserted. Every address carrying more than one contestant comes back in `shared_emails[]` — informational, nothing merged and nothing lost.

Send siblings as separate rows. There is no need to hold them back or merge them yourself.

• Max 5000 contestants per request.

Send the date of birth if you have it

Pageant Alert uses DOB, not an over-18 checkbox, and it drives real behaviour: under 13 the child has no login and her guardian holds the account; 13–17 needs a guardian; 18+ is the contestant alone. Without it we cannot tell, and the girl gets asked again at signup.

The response, and the one field that will catch you out

`200 OK`, snake_case throughout, including inside the nested objects. You get `contest_id`, `contest_url` (her shareable sign-up link — worth showing her), and counts: `created`, `matched`, `invited`, `already_subscribed`, `malformed`, plus `errors[]`, `possible_duplicates[]` and `needs_guardian[]`.

`matched` does not mean "already on her list"

Contestants are platform-level: one girl is one record across every director. A girl who competed for a different director last year already exists on the platform, so a first-ever export can legitimately return `created: 0, matched: 40`.

Do not tell the director "40 were already imported" — she will think the export failed. Report `created + matched` as the number on her list, and `invited` separately.

Malformed rows are not errors

A row with no email comes back in `errors[]` with a `200`. The good rows still land. Show her the reasons verbatim; they are written to be read by a director.

Re-exporting is always safe

This is the property the whole integration rests on. An export is a snapshot; the answer to staleness is export again.

Sending the same payload twice creates nothing new — the first run reports `created: 2, matched: 0`, the second `created: 0, matched: 2`.

• Don't build change detection, diffing, or "only export new entries".
• Don't warn her that she already exported.
• Let her press the button after every batch of registrations. That is the intended use.

An upsert fills blanks only. A girl who already told Pageant Alert her phone number keeps it, along with her push set-up, her subscriptions, and her pageant history — and she gets no duplicate invitation.

What to build on your side

Keep it small. The point is that she doesn't have to learn a second product.

• A button on the pageant's admin screen, near her contestant list.
• Her key, once. Ask for it the first time, store it, never ask again unless a `401` comes back.
• A confirmation showing how many contestants are going and whether invitations will be emailed. This is the last moment before real email reaches real people, and an invitation cannot be recalled.
• A result she can act on: `created + matched` as the headline, `invited` separately, her `contest_url` with a copy button, any `errors[]` verbatim, and `needs_guardian[]` if it isn't empty.
• Store `contest_id` against your pageant record.

Invitations go out from Pageant Alert's domain with the director's name in the from-label and the subject — "Sarah Mitchell has invited you to Miss Tennessee Teen" — because she is the reason they get opened.

Testing

There is no separate sandbox, and none is needed. Register a throwaway director at pageantalert.com/register, create a key, and export with `send_invites: false` until you are confident — nothing reaches a real inbox.

Worth confirming before you ship:

• A first export with `name` + `end_date` returns a `contest_id`, and you store it.
• A second export with `contest.id` returns `created: 0` and the roster does not grow.
• A row with no email comes back in `errors[]` and the other rows still land.
• A `401` clears the stored key and re-prompts rather than looping.
• Your success message uses `created + matched`, not `created`.
• `dob` is being sent, in `YYYY-MM-DD`, for every contestant who has one.