API reference

Entries

For your server, with the secret key: read entries, invite them, move them up and delete them.

List entries

GET/api/v1/entriesSecret key

Entries of the key's product, newest first. Pass nextCursor of one page as cursor to get the next; nextCursor is null on the last page. With email the list holds the entry of that address or nothing: the way from an address to its entry id.

curl "$NEARLYIN_URL/api/v1/entries?state=confirmed&limit=50" \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY"

Parameters

statequery · "pending" | "confirmed" | "invited" | "redeemed" · optional: Only entries in this state.
emailquery · string · optional: Only the entry of this address. Trimmed and lowercased before the lookup.
limitquery · integer · optional: Entries per page.
cursorquery · string · optional: nextCursor of the previous page.

Responses

200 One page of entries.

{
  "data": [
    {
      "id": "cmgk3x9f20001abcd1234efgh",
      "email": "ada@example.com",
      "state": "confirmed",
      "createdAt": "2026-10-11T09:12:45.120Z",
      "confirmedAt": "2026-10-11T09:14:02.004Z",
      "invitedAt": null,
      "redeemedAt": null,
      "referralCode": "k4m9q2xh7d",
      "referrals": 0
    }
  ],
  "nextCursor": null
}

400 invalid_request: The request could not be read or is missing a required field. / invalid_cursor: The cursor is not one this API issued. / invalid_email: This is not a valid email address.

401 unauthorized: Missing, unknown or revoked key.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Invite the next people in line

POST/api/v1/entries/invite-nextSecret key

Invites the first count people in line: confirmed, not invited yet, in order of their place (order of confirmation, moved up by referrals). Answers with the ids of the entries that were invited and of those whose mail could not be handed over; those stay in line.

Send an Idempotency-Key to make the request safe to repeat: a repeat with the same key and count gets the first answer, marked with Idempotent-Replayed: true, and invites nobody else.

curl -X POST $NEARLYIN_URL/api/v1/entries/invite-next \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" -d '{"count":10}'

Parameters

Idempotency-Keyheader · string · optional: 1 to 255 visible ASCII characters, unique per invitation you intend to send.

Body

countinteger · required: How many people from the front of the line.

Responses

200 Done. invited and failed hold entry ids, in the order of the line.

{
  "invited": [
    "cmgk3x9f20001abcd1234efgh"
  ],
  "failed": []
}

400 invalid_idempotency_key: The Idempotency-Key must be 1 to 255 visible ASCII characters. / invalid_request: The request could not be read or is missing a required field.

401 unauthorized: Missing, unknown or revoked key.

409 idempotency_in_progress: A request with this Idempotency-Key is still running.

422 idempotency_key_reused: This Idempotency-Key was already used for a different request.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Read one entry

GET/api/v1/entries/{id}Secret key

Entries of other products, or of the other mode, do not exist for this key.

curl $NEARLYIN_URL/api/v1/entries/$ENTRY_ID \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY"

Parameters

idpath · string · required: Id of the entry, as returned by the list.

Responses

200 The entry.

{
  "id": "cmgk3x9f20001abcd1234efgh",
  "email": "ada@example.com",
  "state": "confirmed",
  "createdAt": "2026-10-11T09:12:45.120Z",
  "confirmedAt": "2026-10-11T09:14:02.004Z",
  "invitedAt": null,
  "redeemedAt": null,
  "referralCode": "k4m9q2xh7d",
  "referrals": 0
}

401 unauthorized: Missing, unknown or revoked key.

404 not_found: No such entry.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Delete one entry

DELETE/api/v1/entries/{id}Secret key

Removes the entry for good, whatever its state. Sends no mail. An invitation code that was already sent stops working.

curl -X DELETE $NEARLYIN_URL/api/v1/entries/$ENTRY_ID \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY"

Parameters

idpath · string · required: Id of the entry, as returned by the list.

Responses

204 Deleted.

401 unauthorized: Missing, unknown or revoked key.

404 not_found: No such entry.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Invite one entry

POST/api/v1/entries/{id}/inviteSecret key

Sends the invitation mail with a personal code and marks the entry as invited. Only confirmed entries can be invited.

Send an Idempotency-Key (any unique string, for example a UUID) to make the request safe to repeat: if you got no answer and send it again with the same key, the mail still goes out exactly once and you get the answer of the first attempt, marked with the response header Idempotent-Replayed: true. Keys are remembered for 24 hours. If the mail could not be handed over (mail_failed), nothing is remembered and the same key can be used to try again.

curl -X POST $NEARLYIN_URL/api/v1/entries/$ENTRY_ID/invite \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Parameters

idpath · string · required: Id of the entry, as returned by the list.
Idempotency-Keyheader · string · optional: 1 to 255 visible ASCII characters, unique per invitation you intend to send.

Responses

200 Invited. The entry as it is now.

{
  "id": "cmgk3x9f20001abcd1234efgh",
  "email": "ada@example.com",
  "state": "invited",
  "createdAt": "2026-10-11T09:12:45.120Z",
  "confirmedAt": "2026-10-11T09:14:02.004Z",
  "invitedAt": "2026-10-12T08:00:00.000Z",
  "redeemedAt": null,
  "referralCode": "k4m9q2xh7d",
  "referrals": 0
}

400 invalid_idempotency_key: The Idempotency-Key must be 1 to 255 visible ASCII characters.

401 unauthorized: Missing, unknown or revoked key.

404 not_found: No such entry.

409 not_confirmed: The entry has not confirmed its address yet and cannot be invited. / already_invited: The entry was already invited. / idempotency_in_progress: A request with this Idempotency-Key is still running.

422 idempotency_key_reused: This Idempotency-Key was already used for a different request.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

502 mail_failed: The mail could not be handed over. Nothing was changed; try again.

Send an invitation again

POST/api/v1/entries/{id}/reinviteSecret key

Sends an invited entry its invitation mail again, with a new personal code. The old code stops working once the new mail was handed over, and the 30 days of the code start anew. invitedAt stays the time of the first invitation. An entry that has redeemed its code is refused (already_redeemed): the person is in already. No webhook goes out: the entry was invited before and still is.

Idempotency-Key works as for inviting: with the same key the mail goes out once.

curl -X POST $NEARLYIN_URL/api/v1/entries/$ENTRY_ID/invite \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Parameters

idpath · string · required: Id of the entry, as returned by the list.
Idempotency-Keyheader · string · optional: 1 to 255 visible ASCII characters, unique per mail you intend to send.

Responses

200 Sent again. The entry as it is now.

{
  "id": "cmgk3x9f20001abcd1234efgh",
  "email": "ada@example.com",
  "state": "invited",
  "createdAt": "2026-10-11T09:12:45.120Z",
  "confirmedAt": "2026-10-11T09:14:02.004Z",
  "invitedAt": "2026-10-12T08:00:00.000Z",
  "redeemedAt": null,
  "referralCode": "k4m9q2xh7d",
  "referrals": 0
}

400 invalid_idempotency_key: The Idempotency-Key must be 1 to 255 visible ASCII characters.

401 unauthorized: Missing, unknown or revoked key.

404 not_found: No such entry.

409 not_invited: The entry was not invited yet, so there is no invitation to send again. / already_redeemed: The entry has redeemed its invitation; there is nothing to send again. / idempotency_in_progress: A request with this Idempotency-Key is still running.

422 idempotency_key_reused: This Idempotency-Key was already used for a different request.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

502 mail_failed: The mail could not be handed over. Nothing was changed; try again.

Move an entry up the line

POST/api/v1/entries/{id}/move-upSecret key

Moves a waiting entry (confirmed, not invited yet) up the line by places, on top of what its referrals give it. Calls add up. Its place is computed anew from the order of confirmation, minus the places of its referrals and the places given here; drawing level, the one moved up goes first. No webhook goes out and no mail.

curl -X POST $NEARLYIN_URL/api/v1/entries/$ENTRY_ID/move-up \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" -H 'Content-Type: application/json' -d '{"places":10}'

Parameters

idpath · string · required: Id of the entry, as returned by the list.

Body

placesinteger · required: How many places up.

Responses

200 Moved. The entry as it is now.

{
  "id": "cmgk3x9f20001abcd1234efgh",
  "email": "ada@example.com",
  "state": "confirmed",
  "createdAt": "2026-10-11T09:12:45.120Z",
  "confirmedAt": "2026-10-11T09:14:02.004Z",
  "invitedAt": null,
  "redeemedAt": null,
  "referralCode": "k4m9q2xh7d",
  "referrals": 0
}

400 invalid_request: The request could not be read or is missing a required field.

401 unauthorized: Missing, unknown or revoked key.

404 not_found: No such entry.

409 not_confirmed: The entry has not confirmed its address yet and cannot be invited. / already_invited: The entry was already invited.