API Get Schools: Difference between revisions

From zFairs Contest Management
← Older edit

Trent (talk | contribs)

3 user groups
537 edits
Michael (talk | contribs)
303 edits
No edit summary
Remove username/password API auth; ApiKey only
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Get Schools ==
== Get Schools ==
Get a list of schools from our API.
Returns schools for the client associated with the fair. Optionally include preloaded/system schools.


=== 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/schools', {
fetch('/api/data/schools', {
     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: {}
includePreloadedSchools: false  // optional, default false
}
         })
         })
})
})
Line 17: Line 47:
.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 <code>Body</code> looks like:


<syntaxhighlight lang="JavaScript">
{
  Success: true,
  Message: null,
  Body: {
    schools: [{
      id: 24,
      name: "Example School",
      address: "100 School Rd",
      address2: null,
      city: "Ogden",
      state: "UT",
      zip: "84401",
      phone: "801-555-0100",
      SchoolType: "Public School",
      PrincipalName: "Pat Principal",
      PrincipalPhone: "801-555-0101",
      PrincipalEmail: "principal@example.edu",
      DistrictName: "Example District",
      DistrictId: 5
    }]
  }
}
</syntaxhighlight>
</syntaxhighlight>


=== Field notes ===
* Set <code>Body.includePreloadedSchools</code> to <code>true</code> to include preloaded schools in addition to client schools.
* School <code>id</code> values are used when adding projects/participants (<code>SchoolId</code>).
* To create or update a school, see [[API Add School]].
=== Related APIs ===
* [[API Add School]]
* [[API Get Teachers]]
* [[API Add Project]] / [[API Get Projects]]




<br/><br/><br/><br/>
<br/><br/>
[[Category: API]]
[[Category: API]]

Latest revision as of 11:55, 25 July 2026

Get Schools

Returns schools for the client associated with the fair. Optionally include preloaded/system schools.

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/schools', {
    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: {
				includePreloadedSchools: false  // optional, default false
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success Body looks like: 

{
  Success: true,
  Message: null,
  Body: {
    schools: [{
      id: 24,
      name: "Example School",
      address: "100 School Rd",
      address2: null,
      city: "Ogden",
      state: "UT",
      zip: "84401",
      phone: "801-555-0100",
      SchoolType: "Public School",
      PrincipalName: "Pat Principal",
      PrincipalPhone: "801-555-0101",
      PrincipalEmail: "principal@example.edu",
      DistrictName: "Example District",
      DistrictId: 5
    }]
  }
}


Field notes

  • Set Body.includePreloadedSchools to true to include preloaded schools in addition to client schools.
  • School id values are used when adding projects/participants (SchoolId).
  • To create or update a school, see API Add School.





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