API Paperwork Reminders

From zFairs Contest Management
Revision as of 17:14, 19 November 2026 by Trent (talk | contribs) (Created page with "== Paperwork reminders == Preview the paperwork '''Send reminders''' email for a fair. This is a dry run. It does not send mail. The lines where <code>needsReminder</code> is true are the lines that email would list. Send reminders uses this same list. Call it on the fair's site: <code>POST /api/data/paperwork/reminders</code> === Request === <code>Body</code> is required. Use <code>{}</code> to preview every entry. <code>projectId</code> is the integer project id (...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Paperwork reminders

Preview the paperwork Send reminders email for a fair. This is a dry run. It does not send mail.

The lines where needsReminder is true are the lines that email would list. Send reminders uses this same list.

Call it on the fair's site:

POST /api/data/paperwork/reminders

Request

Body is required. Use {} to preview every entry.

projectId is the integer project id (id from API Get Projects). projectCode is the project code (projectId from API Get Projects). A projectId of 0 or less is ignored. When either filter is set and no entry matches, the call fails.

fetch('/api/data/paperwork/reminders', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        ApiKey: '<Private key>',
        FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // f= in the fair URL
        Body: {
            projectId: 12345,      // optional integer id
            projectCode: 'AB-123'  // optional project code
        }
    })
})
.then(response => response.json())
.then(data => { console.log('Success: ', data); })
.catch((error) => { console.log('Error: ', error); });

Username and Password may be sent instead of ApiKey. That account must be an admin. Send the call from your server. Do not put the key in a browser page.

Response

Property names are camelCase.

{
    success: true,
    message: null,
    body: {
        usePaperwork: true,   // fair paperwork setting
        packetsInUse: true,   // fair form-packet setting
        entries: [{
            projectId: "AB-123",
            projectIntId: 12345,
            projectKey: "36-char-GUID",
            title: "Project Title",
            entryTypeId: 2,
            divisionId: 4,     // division chosen from the entry grade
            grade: 8,
            categoryId: 12,
            category: "Biology",
            usesPaperwork: true,  // entry type can turn paperwork off
            wouldSend: true,
            recipients: [{
                personId: 1001,
                firstName: "Alice",
                lastName: "Example",
                email: "alice@example.com"
            }],
            items: [{
                kind: "Paperwork",          // Paperwork, PacketForm, or PacketWizard
                name: "Form 1C",            // exact email line
                packetName: null,
                formName: null,
                fileTypeId: 123,
                formId: null,
                packetId: null,
                needsReminder: true,
                reason: "Missing"
            }, {
                kind: "PacketForm",
                name: "SRC Packet - \"Form 1B\" - Alice Example",
                packetName: "SRC Packet",
                formName: "Form 1B",
                fileTypeId: null,
                formId: 88,
                packetId: 7,
                needsReminder: false,
                reason: "Complete"
            }],
            skippedPackets: [{
                packetId: 9,
                name: "Senior Packet",
                reason: "Does not apply to this division"
            }]
        }]
    }
}

What is included

  • Dropped entries and admin accounts are left out.
  • Only current team members are recipients. Former members are not emailed.
  • recipients is filled only when at least one item has needsReminder: true.
  • wouldSend is true only when a reminder is needed and there is at least one current member. A missing file with no current member stays on items and is not emailed.
  • items lists files and forms that were checked, including ones that do not need a reminder.
  • Removed or deleted uploads, file types, forms, and packets are not used.
  • When paperwork is off for the entry, paperwork files are not reminded. Reason: Paperwork is not used.
  • When form packets are off for the fair, packetsInUse is false and there are no packet items or skipped packets.

Paperwork files

A file type is omitted when its entry type or division does not match. Blank or 0 means all entry types or all divisions.

A matching file is still not reminded when it is not required, forced not required, the division does not upload paperwork, or it is an ISEF file and ISEF forms do not apply to the division.

  • Per team member: each current member gets a row. The email line is the file name, a hyphen, and the member name. It is reminded when that member has no file, or the file is not Accepted.
  • Project file: any non-removed upload counts as done. Reason is Uploaded, including Needs Work, Pending, and Rejected. No upload is Missing.

Packets and forms

A packet is skipped, and its forms are left out of the email, unless the entry matches its division, category, and entry type lists. A blank list means all. A missing division, category, or entry type is 0 and does not match a restricted list. The division is the one for the entry's grade.

A packet is also skipped when it is not in use, or the division opts out of it. The reason is on skippedPackets.

Reason Meaning
Packet is not in use Packet is turned off
This division opts out of this packet Division opt-out
Does not apply to this entry type Entry type is not on the packet or form list
Does not apply to this category Category is not on the list
Does not apply to this division Division is not on the list

Forms inside a matching packet use the same three lists. A form that does not match stays on items with needsReminder: false.

A required form is reminded when it is missing, Needs Work, or Rejected. Accepted, Approved, Under Review, Pending, Not Needed, an upload, or saved answers stay out. New is the owner's submit and stays out. Form 1B stays in until it has a signature or an upload.

A per-person form is one row per current participant. The email line is Packet - "Form" - Person Name. Packet questions are a PacketWizard row named Packet - packet questions.

Errors

success is false and message explains the failure.

  • request is null
  • request body is null
  • API key is not valid
  • FairId is null or empty.
  • FairId '...' is not valid. The message lists the fairs this key can use.
  • No entry was found for that project.
  • Could not load entries for this fair.
  • Error occured during processing.
  • API Get Projects — id is projectId here, and projectId is projectCode here
  • API Get Info — category, entry type, and paperwork file type ids