Difference between revisions of "API Get participants"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Get Participants ==
 
== Get Participants ==
−
Get a list of participants from our API.
+
Returns all student/participant records for a fair, including project links, school/teacher, tags, waivers, and fee status when fees are tracked.
  
 +
=== 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/participants', {
 
fetch('/api/data/participants', {
 
     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: {
 +
    participants: [{
 +
      id: "person-guid",
 +
      idInt: 1001,
 +
      firstName: "Alice",
 +
      lastName: "Example",
 +
      username: "alice.example",
 +
      email: "alice@example.com",
 +
      phone: "800-000-0000",
 +
      address: "123 Main St",
 +
      address2: "Apt 2",
 +
      city: "Ogden",
 +
      state: "UT",
 +
      zip: "84401",
 +
      countryName: "United States",
 +
      projectId: "AB-123",          // display project id
 +
      projectKey: "36-char-GUID",  // project GUID
 +
      title: "Project Title",
 +
      studentId: "S-001",
 +
      divisionName: "Junior",
 +
      category: { Id: "12", Name: "Biology" },
 +
      teamProject: true,
 +
      school: { Id: "24", Name: "Example School" },
 +
      teacher: { Id: "55", Name: "Jane Smith" },
 +
      tags: ["VIP"],
 +
      gender: "F",
 +
      shirtSize: "M",
 +
      holdHarmlessSigned: "2024-02-01T00:00:00Z",
 +
      medialReleaseSigned: "2024-02-01T00:00:00Z",  // note: field name is medialReleaseSigned
 +
      mediaRelease: true,
 +
      permissionsAndWaiversSigned: "2024-02-01T00:00:00Z",
 +
      feePaid: true  // null when the fair does not track registration fees
 +
    }]
 +
  }
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
 +
=== Field notes ===
 +
* <code>feePaid</code> is only populated when the fair has a registration fee type configured; otherwise it is <code>null</code>.
 +
* Fee tracking can be by person or by project depending on fair settings.
 +
* <code>category</code>, <code>school</code>, and <code>teacher</code> use <code>{ Id, Name }</code>.
 +
* For project-scoped participants with flattened columns, see [[API Get Projects]].
 +
 +
 +
=== Related APIs ===
 +
* [[API Get Projects]]
 +
* [[API Add Person]] / [[API Add Project]]
 +
* [[API Get Teachers]] / [[API Get Schools]]
 +
* [[API Get Tags]] / [[API Set Tags]]
  
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

Get Participants

Returns all student/participant records for a fair, including project links, school/teacher, tags, waivers, and fee status when fees are tracked.

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/participants', {
    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: {
    participants: [{
      id: "person-guid",
      idInt: 1001,
      firstName: "Alice",
      lastName: "Example",
      username: "alice.example",
      email: "alice@example.com",
      phone: "800-000-0000",
      address: "123 Main St",
      address2: "Apt 2",
      city: "Ogden",
      state: "UT",
      zip: "84401",
      countryName: "United States",
      projectId: "AB-123",          // display project id
      projectKey: "36-char-GUID",   // project GUID
      title: "Project Title",
      studentId: "S-001",
      divisionName: "Junior",
      category: { Id: "12", Name: "Biology" },
      teamProject: true,
      school: { Id: "24", Name: "Example School" },
      teacher: { Id: "55", Name: "Jane Smith" },
      tags: ["VIP"],
      gender: "F",
      shirtSize: "M",
      holdHarmlessSigned: "2024-02-01T00:00:00Z",
      medialReleaseSigned: "2024-02-01T00:00:00Z",  // note: field name is medialReleaseSigned
      mediaRelease: true,
      permissionsAndWaiversSigned: "2024-02-01T00:00:00Z",
      feePaid: true   // null when the fair does not track registration fees
    }]
  }
}


Field notes

  • feePaid is only populated when the fair has a registration fee type configured; otherwise it is null.
  • Fee tracking can be by person or by project depending on fair settings.
  • category, school, and teacher use { Id, Name }.
  • For project-scoped participants with flattened columns, see API Get Projects.


Related APIs




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