Difference between revisions of "API Add Project"

From zFairs Contest Management
(Document add project payload and response)
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.
  
−
If you only want to update a project see [[API Update Project]]
+
=== 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. Prefer this over username/password.
 +
|-
 +
| <code>Username</code> / <code>Password</code> || Yes* || Alternate auth if not using ApiKey.
 +
|-
 +
| <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.
 +
|}
 +
 +
* Provide '''either''' <code>ApiKey</code> '''or''' <code>Username</code>+<code>Password</code>.
 +
 +
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',
Line 11: Line 41:
 
     body: JSON.stringify({
 
     body: JSON.stringify({
 
             ApiKey:'<Private key>',
 
             ApiKey:'<Private key>',
−
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
+
             FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
 
             Body: {
 
             Body: {
−
Title:'Project Title' //Required
+
Title: "Project Title",      // required
−
,CategoryId: 123 //Required
+
CategoryId: 123,              // required
−
,SubCategoryId: 123 //optional
+
SubCategoryId: 456,          // optional
−
,Plan: 'Project Plan' // optional
+
Plan: "Project plan",
−
,Abstract: 'Project Abstract'// optional
+
Abstract: "Abstract text",
−
,Description: 'Project Description'// optional
+
Description: "Description",
−
,ProjectKey: ’36 char GUID’//optional
+
ProjectKey: null,            // optional GUID; generated if omitted
−
,EntryVideoLink: ‘video Link’ //optional
+
FixedProjectId: "AB-100",     // optional fixed display id
−
,EntryVideoLink2: ‘video Link’ //optional
+
EntryVideoLink: "https://...",
−
,CategoryAwardId: 1 // optional
+
EntryVideoLink2: "https://...",
−
,SpecialAwardsIds: [1, 2] //optional
+
CategoryAwardId: 1,
−
,EntryTypeId: 2 //optional value come from info api
+
SpecialAwardsIds: [10, 11],
−
,Language:'Spanish' //optional - interpreter need for this language
+
EntryTypeId: 2,              // from Get Info
−
,InPerson:'Yes' //optional - 'yes' or 'no'
+
Language: "Spanish",
−
,Participants : [{
+
InPerson: "Yes",              // typically 'Yes' / 'No'
−
FirstName: 'Jane' //Required
+
Approved: true,
−
,LastName: 'Doe' //Required
+
Participants: [{             // required, at least one
−
,Grade: 6 //Required
+
FirstName: "Alice",      // required
−
,TeacherId: '9df61f13-474b-442f-ac1f-edca7348ef71' //Required
+
LastName: "Example",      // required
−
,SchoolId: 24 //Required
+
Grade: 8,                // required
−
,Email: 'jane@example.com'
+
TeacherId: "teacher-guid",// required
−
,Email1: 'Doe@example.com'
+
SchoolId: 24,            // required
−
,Phone: '800-000-0000'
+
Email: "alice@example.com",
−
,Phone1: '800-123-1324'
+
Phone: "800-000-0000",
−
,Address: '1219 45th st'
+
Address: "123 Main St",
−
,Address2: 'APT 3B'
+
City: "Ogden",
−
,City: 'Ogden'
+
State: "UT",
−
,State: 'VA'
+
Zip: "84401",
−
,Zip: '65951'
+
Language: "Spanish",
−
,Role: 'Student'
+
Id: null,                 // optional existing person GUID
−
                                        ,ID:  'Student GUID ID' //optional
+
Username: null,
−
                                        ,Username: 'Student User Name' //optional
+
Password: null,
−
                                        ,Password: 'Student Password' //optional
+
ProfilePicture: {
−
,Language:'Spanish' //optional - interpreter need for this language
+
Base64String: "iVBORw0KGgo...",
−
,ProfilePicture: { //Optional
+
FileName: "profile.png",
−
Base64String: 'base64 file string',
+
Caption: "Portrait"
−
"FileName": "myAwesomeFileDude.png",
 
−
"Caption": "indescribable profile Pic"
 
 
}
 
}
−
 
 
}],
 
}],
−
"CustomQuestions" : //optional
+
CustomQuestions: [{ Id: 55, Value: "large" }],
−
[{
+
Files: [{
−
"Id": 123,
+
Base64String: "iVBORw0KGgo...", // or DownloadFromUrl
−
"Value": "This is my answer"
+
DownloadFromUrl: null,
−
},...]
+
FileName: "board.png",
−
"Files": //optional
+
Caption: "Display board",
−
[{  
+
PaperworkFileType: null    // set for paperwork PDFs; id from Get Info
−
          "Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...", //not required if you use DownloadFromUrl
+
}]
−
          "DownloadFromUrl":"http://yoursite.com/somefile.png",//optional can be used in stead of Base64String
 
−
          "FileName": "myAwesomeFile.png",
 
−
          "Caption": "indescribable"
 
−
          },
 
−
          {
 
−
          "Base64String" : "iVBORw0KGgoAAAANSUhEUgAAAQIAA...",
 
−
          "FileName": "myAwesomeFile2.png",
 
−
          "Caption": "indescribable also"
 
−
          },
 
−
          {
 
−
          "DownloadFromUrl":"http://yoursite.com/somefile.png",
 
−
          "FileName": "myAwesomething.pdf",
 
−
          "Caption": "indescribable pdf"
 
−
          }]
 
 
}
 
}
 
         })
 
         })
Line 82: Line 95:
 
.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>
  
−
</syntaxhighlight>
+
=== Response ===
 +
On success:
  
−
== Where to get values ==
+
<pre>
−
Various fields need id values such as '''CategoryId''', '''CustomQuestion Ids''', '''CategoryAwardId''', and '''SpecialAwardIds'''. You can get these values from our API. Check out [[API Get Info]]
+
{
 +
  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>
  
−
A participant record is very similar to a teacher record see [[API Add Person]] for optional fields of participants.
 
  
 +
=== 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]].
  
−
You can also add '''FixedProjectId''', this allows you to upload the project Id you want to be used for your uploaded project.
 
  
 +
=== Related APIs ===
 +
* [[API Update Project]]
 +
* [[API Get Projects]]
 +
* [[API Get Info]]
 +
* [[API Upload Project Assets]]
 +
* [[API Set Project Id]]
  
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Revision as of 12:49, 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. Prefer this over username/password.
Username / Password Yes* Alternate auth if not using ApiKey.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.
  • Provide either ApiKey or Username+Password.

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=943"