Difference between revisions of "API Add School"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
−
== Add Schools ==
+
== Add School ==
−
You can use our api to add schools to your contest. To do this you need to POST a message to your site. Below is an example of what needs to be posted.
+
Creates or updates a school on the client. If <code>Id</code> is set to an existing school id, the school is updated; otherwise a new school is created.
  
−
fetch('/api/data/school', {
+
=== Authentication ===
−
method:'POST',
+
All data API calls are <code>POST</code> (unless noted) with JSON body:
−
headers:{'Content-Type': 'application/json'},
 
−
body: JSON.stringify({
 
−
ApiKey:'<Private key>',
 
−
Body: {
 
−
Name: '_ A Test School'
 
−
,Address: '1219 34th State' //optional
 
−
,Address2: 'Apt 3'          //optional
 
−
,City: 'Ogden'              //optional
 
−
,State: 'Ut'                //optional
 
−
,Zip: '84403'              //optional
 
−
,County: 'Weber'            //optional
 
−
,Phone: '801-252-0903'      //optional
 
−
,WebsiteUrl: 'zfairs.com'  //optional
 
−
,SchoolType: 'Public'      //{ Public, Private, Charter, Home}  //optional
 
−
,PrincipalName: 'Mrs Bell'                //optional
 
−
,PrincipalPhone: '801-252-0000'            //optional
 
−
,PrincipalEmail: 'MrsBell@zfairs.com'      //optional
 
−
,ContactFirstName: 'Joe'                  //optional
 
−
,ContactLastName: 'Homes'                  //optional
 
−
,ContactPhone: '801-252-0001'              //optional
 
−
,ContactEmail: 'jh@zfairs.com'            //optional
 
−
,GradeLow: '0'                            //pre-k = -1, k = 0        //optional
 
−
,GradeHigh: '12'                          //optional
 
−
,Fax: '801-252-0003'                      //optional
 
−
,SchoolPaysFees: false,                    //optional values are true/false
 
−
,Id: 1234                                  //optional id of school, this will trigger an updated of that school
 
−
,SchoolCode: '123'                        //optional
 
−
,Affiliated: true                          //optional
 
−
}
 
−
})
 
−
})
 
−
.then(response => response.json())
 
−
.then(data=>{console.log('Success: ',data);})
 
−
.catch((error)=>{console.log('Error: ', error);});
 
  
 +
{| 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.
 +
|}
  
  
−
<br/><br/><br/><br/>
+
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>
 +
fetch('/api/data/school', {
 +
    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: {
 +
Id: 0,  // 0 or omit for new; existing id to update
 +
Name: "Example School",
 +
Address: "100 School Rd",
 +
Address2: "",
 +
City: "Ogden",
 +
State: "UT",
 +
Zip: "84401",
 +
County: "Weber",
 +
Phone: "801-555-0100",
 +
WebsiteUrl: "https://example.edu",
 +
SchoolType: "Public",  // Public | Private | Charter | Home
 +
PrincipalName: "Pat Principal",
 +
PrincipalPhone: "801-555-0101",
 +
PrincipalEmail: "principal@example.edu",
 +
ContactFirstName: "Casey",
 +
ContactLastName: "Contact",
 +
ContactPhone: "801-555-0102",
 +
ContactEmail: "contact@example.edu",
 +
GradeLow: 6,
 +
GradeHigh: 12,
 +
Fax: "",
 +
SchoolPaysFees: false,
 +
IsFeeWaiverSchool: false,
 +
SchoolCode: "EX001",
 +
Active: true,
 +
Affiliated: true,
 +
RegionName: "North",
 +
EducationAgencyName: "North Agency"
 +
}
 +
        })
 +
})
 +
.then(response => response.json())
 +
.then(data=>{console.log('Success: ',data);})
 +
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
 +
 
 +
=== Response ===
 +
On success <code>Body</code> is the school object with <code>Id</code> populated:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { Id: 24, Name: "Example School", ... }
 +
}
 +
</pre>
 +
 
 +
 
 +
=== Field notes ===
 +
* <code>SchoolType</code> maps to: Public → "Public School", Private → "Private School", Charter → "Charter School", Home → "Home School". Unknown defaults to Public School.
 +
* Returned <code>Id</code> should be stored for use as <code>SchoolId</code> on projects/participants.
 +
 
 +
 
 +
=== Related APIs ===
 +
* [[API Get Schools]]
 +
* [[API Add Project]] / [[API Add Person]]
 +
 
 +
 
 +
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Add School

Creates or updates a school on the client. If Id is set to an existing school id, the school is updated; otherwise a new school is created.

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/school', {
    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: {
				Id: 0,  // 0 or omit for new; existing id to update
				Name: "Example School",
				Address: "100 School Rd",
				Address2: "",
				City: "Ogden",
				State: "UT",
				Zip: "84401",
				County: "Weber",
				Phone: "801-555-0100",
				WebsiteUrl: "https://example.edu",
				SchoolType: "Public",  // Public | Private | Charter | Home
				PrincipalName: "Pat Principal",
				PrincipalPhone: "801-555-0101",
				PrincipalEmail: "principal@example.edu",
				ContactFirstName: "Casey",
				ContactLastName: "Contact",
				ContactPhone: "801-555-0102",
				ContactEmail: "contact@example.edu",
				GradeLow: 6,
				GradeHigh: 12,
				Fax: "",
				SchoolPaysFees: false,
				IsFeeWaiverSchool: false,
				SchoolCode: "EX001",
				Active: true,
				Affiliated: true,
				RegionName: "North",
				EducationAgencyName: "North Agency"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success Body is the school object with Id populated: 

{
  Success: true,
  Message: null,
  Body: { Id: 24, Name: "Example School", ... }
}


Field notes

  • SchoolType maps to: Public → "Public School", Private → "Private School", Charter → "Charter School", Home → "Home School". Unknown defaults to Public School.
  • Returned Id should be stored for use as SchoolId on projects/participants.


Related APIs




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