Difference between revisions of "API Add Project"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
== Add Project==
+
== Add Project ==
−
You can use our api to add a project and it's participants To do this you need to POST a message to your site. Below is an example of what needs to be posted.
+
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 <code>POST</code> (unless noted) with JSON body:
 +
 +
{| class="wikitable"
 +
|-
 +
! Field !! Required !! Description
 +
|-
 +
| <code>ApiKey</code> || Yes || Private API key for your site.
 +
|-
 +
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
 +
|-
 +
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> 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:
 +
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,  // error text when Success is false
 +
  Body: { ... }    // endpoint-specific payload
 +
}
 +
</pre>
 +
 +
 +
=== Request ===
 
<syntaxhighlight lang="JavaScript" line>
 
<syntaxhighlight lang="JavaScript" line>
−
 
 
fetch('/api/data/project', {
 
fetch('/api/data/project', {
 
     method:'POST',
 
     method:'POST',
 
     headers:{'Content-Type': 'application/json'},
 
     headers:{'Content-Type': 'application/json'},
 
     body: JSON.stringify({
 
     body: JSON.stringify({
−
             Username:'admin username',
+
             ApiKey:'<Private key>',
−
            Password: 'password',
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
 
             Body: {
 
             Body: {
−
Title:'Project Title' //Required
+
Title: "Project Title",      // required
−
,CategoryId  //Required
+
CategoryId: 123,             // required
−
,Plan: 'Project Plan' // optional
+
SubCategoryId: 456,           // optional
−
,Abstract: 'Project Abstract'// optional
+
Plan: "Project plan",
−
,Description: 'Project Description'// optional
+
Abstract: "Abstract text",
−
,CategoryAwardId: 1 // optional
+
Description: "Description",
−
,SpeicalAwardIds: [1, 2] //optional
+
ProjectKey: null,            // optional GUID; generated if omitted
−
,Participants : [{
+
FixedProjectId: "AB-100",     // optional fixed display id
−
FirstName: 'Jane' //Required
+
EntryVideoLink: "https://...",
−
,LastName: 'Doe' //Required
+
EntryVideoLink2: "https://...",
−
,Grade: 6 //Required
+
CategoryAwardId: 1,
−
,TeacherId: '9df61f13-474b-442f-ac1f-edca7348ef71' //Required
+
SpecialAwardsIds: [10, 11],
−
,SchoolId: 24 //Required
+
EntryTypeId: 2,              // from Get Info
−
,Email: 'jane@example.com'
+
Language: "Spanish",
−
,Email1: 'Doe@example.com'
+
InPerson: "Yes",             // typically 'Yes' / 'No'
−
,Phone: '800-000-0000'
+
Approved: true,
−
,Phone1: '800-123-1324'
+
Participants: [{             // required, at least one
−
,Address: '1219 45th st'
+
FirstName: "Alice",      // required
−
,Address2: 'APT 3B'
+
LastName: "Example",      // required
−
,City: 'Ogden'
+
Grade: 8,                // required
−
,State: 'VA'
+
TeacherId: "teacher-guid",// required
−
,Zip: '65951'
+
SchoolId: 24,            // required
−
,Role: 'Student'
+
Email: "alice@example.com",
−
,ProfilePicture: { //Optional
+
Phone: "800-000-0000",
−
Base64String: 'base64 file string',
+
Address: "123 Main St",
−
"FileName": "myAwesomeFileDude.png",
+
City: "Ogden",
−
"Caption": "indescribable profile Pic"
+
State: "UT",
 +
Zip: "84401",
 +
Language: "Spanish",
 +
Id: null,                 // optional existing person GUID
 +
Username: null,
 +
Password: null,
 +
ProfilePicture: {
 +
Base64String: "iVBORw0KGgo...",
 +
FileName: "profile.png",
 +
Caption: "Portrait"
 
}
 
}
−
 
 
}],
 
}],
−
"Files": [{
+
CustomQuestions: [{ Id: 55, Value: "large" }],
−
          "Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...",
+
Files: [{
−
          "DownloadFromUrl":"http://yoursite.com/somefile.png" //optional can be used in stead of Base64String
+
Base64String: "iVBORw0KGgo...", // or DownloadFromUrl
−
          "FileName": "myAwesomeFile.png",
+
DownloadFromUrl: null,
−
          "Caption": "indescribable"
+
FileName: "board.png",
−
          },
+
Caption: "Display board",
−
          {
+
PaperworkFileType: null    // set for paperwork PDFs; id from Get Info
−
          "Base64String" : "file String Here",
+
}]
−
          "FileName": "myAwesomeFile2.png",
 
−
          "Caption": "indescribable also"
 
−
          },
 
−
          {
 
−
          "Base64String" : "file string here",
 
−
          "FileName": "myAwesomething.pdf",
 
−
          "Caption": "indescribable pdf"
 
−
          }]
 
 
}
 
}
 
         })
 
         })
Line 64: Line 92:
 
.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:
 +
 +
<pre>
 +
{
 +
  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 */ ],
 +
    ...
 +
  }
 +
}
 +
</pre>
 +
 +
 +
=== Field notes ===
 +
* Participant is required — empty <code>Participants</code> returns 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 <code>ProjectKey</code>).
 +
* File uploads accept Base64 or <code>DownloadFromUrl</code>. Paperwork should be PDF with <code>PaperworkFileType</code> from [[API Get Info]].
 +
* Lookup ids (category, awards, entry type, custom questions, paperwork types) come from [[API Get Info]].
 +
  
−
</syntaxhighlight>
+
=== Related APIs ===
 +
* [[API Update Project]]
 +
* [[API Get Projects]]
 +
* [[API Get Info]]
 +
* [[API Upload Project Assets]]
 +
* [[API Set Project Id]]
  
−
== Where to get values ==
 
−
Various fields need id values such as '''CategoryId''', '''CategoryAwardId''', and '''SpecialAwardIds'''. You can get these values from our API. Check out [[API Get Info]]
 
  
−
=== Additional Optional fields of Participants ===
+
<br/><br/>
−
A participant record is very similar to a teacher record see [[API Add Person]] for optional fields of participants.
+
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

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 Participants returns 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 with PaperworkFileType from API Get Info.
  • Lookup ids (category, awards, entry type, custom questions, paperwork types) come from API Get Info.


Related APIs




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