API Get Projects

Get Projects

Get a list of projects (entries) for a fair from our API. This includes project metadata, participants, mentors, tags, paperwork/project files, and form packet responses.

Request

fetch('/api/data/projects', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
            Body: {}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success the response looks like:

{
  Success: true,
  Message: null, // or an error message when Success is false
  Body: {
    projects: [{
      // Identity
      projectKey: "36-char-GUID",      // unique project key (GUID)
      projectId: "AB-123",             // display / fair project id
      id: 12345,                       // internal integer project id
      title: "Project Title",

      // Classification
      category: { id: 12, name: "Biology" },
      subCategory: { id: 34, name: "Microbiology" },
      division: "Junior",
      grade: 8,                        // team grade
      entryStatus: "Complete",
      entryTypeId: 2,
      EntryTypeName: "Research Entry",
      EntryTypePublicId: "9df61f13-474b-442f-ac1f-edca7348ef71",

      // Status / workflow
      status: "Active",
      statusSetAtUtc: "2024-03-15T18:22:00Z",
      paperworkReadyForReview: true,
      paperworkApprovedAtUtc: "2024-03-20T12:00:00Z",
      readyForJudging: true,
      readyForJudgingAtUtc: "2024-03-21T09:00:00Z",

      // Team / org
      teamProject: true,
      numberOfTeamMembers: 2,
      schools: ["24", "31"],           // school ids as strings
      districtId: 5,
      districtName: "Example District",
      teachers: ["Jane Smith"],
      tags: ["Review Needed", "Excellent"],
      projectLanguage: "Spanish",

      // Convenience participant summaries
      participantNames: ["Alice Example", "Bob Example"],
      participantIds: ["guid-1", "guid-2"],

      // Full participant records (same shape as /api/data/participants, scoped to this project)
      participants: [{
        id: "person-guid",
        idInt: 1001,
        firstName: "Alice",
        lastName: "Example",
        username: "alice.example",
        email: "alice@example.com",
        phone: "800-000-0000",
        address: "123 Main St",
        address2: "Apt 2",
        city: "Ogden",
        state: "UT",
        zip: "84401",
        countryName: "United States",
        projectId: "AB-123",
        projectKey: "36-char-GUID",
        title: "Project Title",
        studentId: "S-001",
        divisionName: "Junior",
        category: { Id: "12", Name: "Biology" },
        teamProject: true,
        school: { Id: "24", Name: "Example School" },
        teacher: { Id: "55", Name: "Jane Smith" },
        tags: ["VIP"],
        gender: "F",
        shirtSize: "M",
        holdHarmlessSigned: "2024-02-01T00:00:00Z",
        medialReleaseSigned: "2024-02-01T00:00:00Z",
        mediaRelease: true,
        permissionsAndWaiversSigned: "2024-02-01T00:00:00Z",
        feePaid: true
      }],

      mentors: [{
        id: 1,
        email: "mentor@example.com",
        firstName: "Sam",
        lastName: "Mentor",
        phone: "800-111-2222"
      }],

      // Paperwork uploads only (type is always "paperwork")
      paperworkFiles: [{
        name: "Form 1C",               // paperwork file type name
        type: "paperwork",
        createdAtUtc: "2024-03-01T10:00:00Z",
        fileUpdatedAtUtc: "2024-03-02T11:00:00Z",
        publicId: "file-guid",
        fileName: "form1c.pdf",
        path: "https://yoursite.zfairs.com/file/showfile/file-guid",
        paperworkFileTypeId: 123,      // from API Get Info → PaperworkFileTypes
        fileStatus: 1
      }],

      // All project files: uploaded assets PLUS paperwork files
      projectFiles: [{
        name: "myAwesomeFile.png",     // or paperwork type name for paperwork entries
        type: "image",                 // asset file type, or "paperwork"
        createdAtUtc: "2024-03-01T10:00:00Z",
        fileUpdatedAtUtc: "2024-03-01T10:00:00Z",
        publicId: "file-guid",
        fileName: "myAwesomeFile.png",
        path: "https://yoursite.zfairs.com/file/showfile/file-guid",
        paperworkFileTypeId: null,     // set for paperwork entries
        fileStatus: null               // set for paperwork entries
      }],

      // Form packet responses for this project
      packetResponses: [{
        packetName: "SRC Packet",
        formName: "Form 1B",
        comments: [{
          IsPrivate: false,
          Status: "Approved",
          Comment: "Looks good",
          AtUtc: "2024-03-10T15:00:00Z",
          ByName: "Reviewer Name",
          ByPublicId: "reviewer-guid",
          ById: 42,
          Id: "comment-guid",
          FormId: "form-guid"
        }],
        fileKey: "file-guid",
        fileKeyLastUpdate: "2024-03-10T15:00:00Z",
        status: "Approved",
        jsonDetails: "{...}",          // raw form detail JSON string
        path: "https://yoursite.zfairs.com/file/showfile/file-guid" // null when no fileKey
      }]
    }]
  }
}

Field notes

• projectKey – GUID used by other project APIs (update project, upload assets, set project id, tags, etc.).
• projectId – human-facing project / board id for the fair.
• id – internal integer id (used in some admin/internal contexts).
• schools – array of school id strings associated with the project.
• teachers – array of teacher display values from the project record.
• paperworkFiles – paperwork only. Use API Get Info for paperwork file type ids/names.
• projectFiles – uploaded project assets and paperwork files combined. Prefer paperworkFiles if you only need paperwork.
• path on files and packet responses – direct URL to download/view via /file/showfile/{publicId}.
• Dropped projects are not returned by this endpoint.
• On failure, Success is false and Message explains the issue (invalid API key, missing/invalid FairId, etc.).

Related APIs

• API Get participants – all participants for a fair
• API Get Info – category, entry type, and paperwork file type ids
• API Get Tags / API Set Tags – tag lists and assignment
• API Upload Project Assets – upload project images/paperwork
• API Add Project / API Update Project – create/update projects