Difference between revisions of "API Get Judges"

From zFairs Contest Management
(Document judges list response for assignments/scores)
Line 1: Line 1:
 
== Get Judges ==
 
== Get Judges ==
−
Get a list of judges from our API.
+
Returns judges for the fair, including contact info, category preferences, assigned category, sessions, and check-in time.
  
 +
=== 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/judges', {
 
fetch('/api/data/judges', {
 
     method:'POST',
 
     method:'POST',
Line 9: 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: {}
 
         })
 
         })
Line 16: Line 48:
 
.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: {
 +
    judges: [{
 +
      id: "judge-public-guid",  // use this as JudgeId in assignment/score APIs
 +
      idInt: 9001,
 +
      firstName: "Sam",
 +
      lastName: "Judge",
 +
      username: "sjudge",
 +
      email: "sam@example.com",
 +
      phone: "801-555-0300",
 +
      address: "5 Court St",
 +
      address2: null,
 +
      city: "Ogden",
 +
      state: "UT",
 +
      zip: "84401",
 +
      tags: ["Experienced"],
 +
      categoryPreference1: 12,
 +
      categoryPreferenceName1: "Biology",
 +
      categoryPreference2: 13,
 +
      categoryPreferenceName2: "Chemistry",
 +
      categoryPreference3: null,
 +
      categoryPreferenceName3: null,
 +
      happToJudgeAnyCategory: true,
 +
      roamingJudgeWilling: false,
 +
      judgeCaptainWilling: true,
 +
      highestLvlOfEducation: "PhD",
 +
      AssignedCategory: 12,
 +
      AssignedCategoryName: "Biology",
 +
      sessions: [1, 2],          // judging session ids
 +
      checkInAtUtc: "2024-03-15T14:00:00Z"
 +
    }]
 +
  }
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
 +
=== Field notes ===
 +
* <code>id</code> is the judge public GUID — required by [[API Set Judging Assignments]] and [[API Judging Scores]] / [[API Upload Judging Score]].
 +
* Category preference ids come from [[API Get Info]] <code>Categories</code>.
 +
* Session ids come from [[API Get Info]] <code>JudgingSessions</code>.
 +
* Judges without a matching person record are omitted from the list.
 +
 +
 +
=== Related APIs ===
 +
* [[API Get Info]]
 +
* [[API Add Person]] (Role: Judge)
 +
* [[API Set Judging Assignments]]
 +
* [[API Judging Scores]] / [[API Upload Judging Score]]
  
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Revision as of 12:49, 25 July 2026

Get Judges

Returns judges for the fair, including contact info, category preferences, assigned category, sessions, and check-in time.

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/judges', {
    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: {}
        })
})
.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: {
    judges: [{
      id: "judge-public-guid",   // use this as JudgeId in assignment/score APIs
      idInt: 9001,
      firstName: "Sam",
      lastName: "Judge",
      username: "sjudge",
      email: "sam@example.com",
      phone: "801-555-0300",
      address: "5 Court St",
      address2: null,
      city: "Ogden",
      state: "UT",
      zip: "84401",
      tags: ["Experienced"],
      categoryPreference1: 12,
      categoryPreferenceName1: "Biology",
      categoryPreference2: 13,
      categoryPreferenceName2: "Chemistry",
      categoryPreference3: null,
      categoryPreferenceName3: null,
      happToJudgeAnyCategory: true,
      roamingJudgeWilling: false,
      judgeCaptainWilling: true,
      highestLvlOfEducation: "PhD",
      AssignedCategory: 12,
      AssignedCategoryName: "Biology",
      sessions: [1, 2],           // judging session ids
      checkInAtUtc: "2024-03-15T14:00:00Z"
    }]
  }
}


Field notes


Related APIs




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