API Add Project
From zFairs Contest Management
Contents
Add Project
Creates a project (entry) and its participants. At least one participant is required. Optionally attach awards, custom question answers, and files.
Authentication
All data API calls are POST (unless noted) with JSON body:
| Field | Required | Description |
|---|---|---|
ApiKey |
Yes | Private API key for your site. |
FairId |
Yes | Fair GUID from the site URL (f query parameter).
|
Body |
Depends | Request payload. Use {} when no body fields are needed.
|
Calls must be run server-side — do not expose your API key in a browser.
Response envelope
Most endpoints return:
{
Success: true,
Message: null, // error text when Success is false
Body: { ... } // endpoint-specific payload
}
Request
fetch('/api/data/project', {
method:'POST',
headers:{'Content-Type': 'application/json'},
body: JSON.stringify({
ApiKey:'<Private key>',
FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
Body: {
Title: "Project Title", // required
CategoryId: 123, // required
SubCategoryId: 456, // optional
Plan: "Project plan",
Abstract: "Abstract text",
Description: "Description",
ProjectKey: null, // optional GUID; generated if omitted
FixedProjectId: "AB-100", // optional fixed display id
EntryVideoLink: "https://...",
EntryVideoLink2: "https://...",
CategoryAwardId: 1,
SpecialAwardsIds: [10, 11],
EntryTypeId: 2, // from Get Info
Language: "Spanish",
InPerson: "Yes", // typically 'Yes' / 'No'
Approved: true,
Participants: [{ // required, at least one
FirstName: "Alice", // required
LastName: "Example", // required
Grade: 8, // required
TeacherId: "teacher-guid",// required
SchoolId: 24, // required
Email: "alice@example.com",
Phone: "800-000-0000",
Address: "123 Main St",
City: "Ogden",
State: "UT",
Zip: "84401",
Language: "Spanish",
Id: null, // optional existing person GUID
Username: null,
Password: null,
ProfilePicture: {
Base64String: "iVBORw0KGgo...",
FileName: "profile.png",
Caption: "Portrait"
}
}],
CustomQuestions: [{ Id: 55, Value: "large" }],
Files: [{
Base64String: "iVBORw0KGgo...", // or DownloadFromUrl
DownloadFromUrl: null,
FileName: "board.png",
Caption: "Display board",
PaperworkFileType: null // set for paperwork PDFs; id from Get Info
}]
}
})
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});Response
On success:
{
Success: true,
Message: null, // may include award/file warnings
Body: {
ProjectKey: "generated-or-provided-guid",
ProjectId: "AB-100",
InterviewRoomUrl: "https://yoursite/app/video/...", // when virtual interviews enabled
Title: "Project Title",
Participants: [ /* with assigned Id/Username */ ],
...
}
}
Field notes
- Participant is required — empty
Participantsreturns an error. - Team project flag is set automatically when there is more than one participant.
- Prefer API Update Project to change an existing project (requires
ProjectKey). - File uploads accept Base64 or
DownloadFromUrl. Paperwork should be PDF withPaperworkFileTypefrom API Get Info. - Lookup ids (category, awards, entry type, custom questions, paperwork types) come from API Get Info.
Related APIs
