Difference between revisions of "API Get Judges"

From zFairs Contest Management
(Created page with "== Get Info== Some of our api calls will require you to have additional information such as category ids or judging session ids. This api call will provide that information. T...")
 
(Remove username/password API auth; ApiKey only)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
== Get Info==
+
== Get Judges ==
−
Some of our api calls will require you to have additional information such as category ids or judging session ids. This api call will provide that information. The results of this api call will grow as our api expands.  
+
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.
 +
|-
 +
| <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/judges', {
 
fetch('/api/data/judges', {
 
     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: {}
 
         })
 
         })
Line 17: Line 45:
 
.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/>
 +
[[Category: API]]

Latest revision as of 12:55, 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.
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/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=957"