API Get Projects

From zFairs Contest Management

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",
        email: "alice@example.com",
        phone: "800-000-0000"
        // ... additional participant fields
      }],

      // Flattened fields for the first 5 participants (null when that slot has no participant)
      // Useful for spreadsheets / systems that cannot consume nested arrays easily
      participant1FirstName: "Alice",
      participant1LastName: "Example",
      participant1Email: "alice@example.com",
      participant1Phone: "800-000-0000",
      participant1Username: "alice.example",
      participant1Id: "person-guid",
      participant1IdInt: 1001,

      participant2FirstName: "Bob",
      participant2LastName: "Example",
      participant2Email: "bob@example.com",
      participant2Phone: "800-000-0001",
      participant2Username: "bob.example",
      participant2Id: "person-guid-2",
      participant2IdInt: 1002,

      participant3FirstName: null,
      participant3LastName: null,
      participant3Email: null,
      participant3Phone: null,
      participant3Username: null,
      participant3Id: null,
      participant3IdInt: null,

      participant4FirstName: null,
      participant4LastName: null,
      participant4Email: null,
      participant4Phone: null,
      participant4Username: null,
      participant4Id: null,
      participant4IdInt: null,

      participant5FirstName: null,
      participant5LastName: null,
      participant5Email: null,
      participant5Phone: null,
      participant5Username: null,
      participant5Id: null,
      participant5IdInt: null,

      // Set only when the project has more than 5 participants; otherwise null
      moreThanFiveParticipantsWarning: null,
      // Example when over the limit:
      // moreThanFiveParticipantsWarning: "This project has 7 participants; only the first 5 are included in the participantN* fields. See the participants array for the full list."

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

      paperworkFiles: [{
        name: "Form 1C",
        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,
        fileStatus: 1,                 // 100=new, 200=needsWork, 300=pending, 500=accepted, etc.
        notes: "Please revise section 2", // latest notes string on the uploaded file
        lastReviewedDateUtc: "2024-03-10T15:00:00Z",
        // Reviewer comment chain for this paperwork file type (newest first)
        comments: [{
          id: 501,
          publicId: "comment-guid",
          fromName: "Reviewer Name",
          header: "Comment On: Form 1C",
          comment: "File Status: Needs Work\n\nPlease revise section 2",
          linkId: "123",               // paperwork file type id as string
          createdAtUtc: "2024-03-10T15:00:00Z"
        }]
      }],

      // All project files: uploaded assets PLUS paperwork files
      projectFiles: [{
        name: "myAwesomeFile.png",
        type: "image",
        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"
      }],

      packetResponses: [{
        packetName: "SRC Packet",
        formName: "Form 1B",
        comments: [],
        fileKey: "file-guid",
        fileKeyLastUpdate: "2024-03-10T15:00:00Z",
        status: "Approved",
        jsonDetails: "{...}",
        path: "https://yoursite.zfairs.com/file/showfile/file-guid"
      }]
    }]
  }
}

Flattened participants

For integrations that need columns instead of nested arrays, the first 5 participants are also exposed as top-level fields:

Field pattern Description
participantNFirstName First name (N = 1..5)
participantNLastName Last name
participantNEmail Email
participantNPhone Phone
participantNUsername Username
participantNId Person public GUID
participantNIdInt Internal integer person id
  • Slots without a participant are returned as null.
  • The full participants array is always included and is not limited to 5.
  • If a project has more than 5 participants, moreThanFiveParticipantsWarning is a string describing the limit; otherwise it is null.

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.
  • paperworkFiles.notes – latest reviewer notes string stored on the uploaded file.
  • paperworkFiles.comments – reviewer comment chain for that paperwork file type (same history shown in paperwork review UI). Ordered newest first. linkId matches paperworkFileTypeId.
  • paperworkFiles.lastReviewedDateUtc – when the file was last reviewed/status-updated.
  • 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





Retrieved from "https://wiki.zFairs.com/index.php?title=API_Get_Projects&oldid=971"