API Get Projects: Difference between revisions
From zFairs Contest Management
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
== Get Projects == | == Get Projects == | ||
Get a list of projects from our API. | 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 === | |||
<syntaxhighlight lang="JavaScript" line> | <syntaxhighlight lang="JavaScript" line> | ||
fetch('/api/data/projects', { | fetch('/api/data/projects', { | ||
method:'POST', | method:'POST', | ||
| Line 16: | Line 16: | ||
.then(data=>{console.log('Success: ',data);}) | .then(data=>{console.log('Success: ',data);}) | ||
.catch((error)=>{console.log('Error: ', error);}); | .catch((error)=>{console.log('Error: ', error);}); | ||
</syntaxhighlight> | |||
=== Response === | |||
On success the response looks like: | |||
<syntaxhighlight lang="JavaScript"> | |||
{ | |||
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 | |||
}] | |||
}] | |||
} | |||
} | |||
</syntaxhighlight> | </syntaxhighlight> | ||
=== 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 <code>/file/showfile/{publicId}</code>. | |||
* Dropped projects are not returned by this endpoint. | |||
* On failure, <code>Success</code> is <code>false</code> and <code>Message</code> 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 | |||
<br/><br/><br/><br/> | <br/><br/><br/><br/> | ||
[[Category: API]] | [[Category: API]] | ||
Revision as of 11:29, 25 July 2026
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,
SuccessisfalseandMessageexplains 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