API Add Person: Difference between revisions

From zFairs Contest Management
← Older edit

Trent (talk | contribs)

3 user groups
537 edits
No edit summary
Remove username/password API auth; ApiKey only
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Add Person==
== Add Person ==
You can use our api to add a teacher or judge 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 a person (teacher, judge, staff, admin, volunteer, or student placeholder) for the client/fair. Also supports judge preferences and optional roles.


=== 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/person', {
fetch('/api/data/person', {
     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: {
                        FirstName: 'Jane'
FirstName: "Jane",
,LastName: 'Doe'
LastName: "Smith",
,Prefix: 'Dr'
Email: "jsmith@example.edu",
,Email: 'jane@example.com'
Email1: "jsmith.alt@example.edu",
,Email1: 'Doe@example.com'
Phone: "801-555-0200",
,Phone: '800-000-0000'
Phone1: "801-555-0201",
,Phone1: '800-123-1324'
Address: "12 Oak St",
,Address: '1219 45th st'
Address2: "",
,Address2: 'APT 3B'
City: "Ogden",
,City: 'Ogden'
State: "UT",
,State: 'VA'
Zip: "84401",
,Zip: '65951'
Role: "Teacher",  // Teacher | Judge | Staff | Admin | Volunteer | Student
,SchoolsTeachesAt: [1] // int array of school ids
Username: "jsmith",       // optional
,Role: 'Teacher' // { Teacher, Judge, Staff, Admin, Volunteer}
Password: "temp-pass",    // optional
,JudgesPreferences:{
RequirePasswordChange: true,
  Category1: 123,
SchoolsTeachesAt: [24],  // school ids for teachers
  ...
Prefix: "Dr",
MiddleName: "A",
Gender: "F",
Race: "",
Ethnicity: "",
FullLegalName: "Jane A Smith",
DateOfBirth: null,
HighestLevelOfEducation: "MS",
JobTitle: "Science Teacher",
Employer: "Example School",
ExternalId: "HR-123",
IsSpecialAwardJudge: false,
IsInterpreter: false,
IsModerator: false,
Language: "Spanish",
JudgesPreferences: { // optional, for judges
Category1: 12,
Category2: 13,
Category3: null,
PreviouslyJudged: true,
JudgingSessions: [1, 2]
}
}
}
            }
         })
         })
})
})
Line 36: Line 84:
.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> echoes the person with assigned <code>Id</code> and <code>Username</code>:
<pre>
{
  Success: true,
  Message: null,
  Body: { Id: "person-guid", Username: "jsmith", FirstName: "Jane", ... }
}
</pre>
=== Field notes ===
* <code>Role</code> is applied after registration via role change.
* For judges, <code>JudgesPreferences</code> category ids and session ids must exist on the fair ([[API Get Info]]).
* Special award judges with an <code>Employer</code> may get a virtual room named after the employer.
* Students on projects are usually created via [[API Add Project]] participants rather than this endpoint.


</syntaxhighlight>


=== Related APIs ===
* [[API Get Teachers]] / [[API Get Judges]]
* [[API Get Info]]
* [[API Add Project]]
* [[API SSO]]


=== Additional Optional fields ===
All of these fields would be part of the body.


* '''Username''' (string max length 25)
<br/><br/>
**If this username is not available one will be assigned
[[Category: API]]
* '''Password''' (string max length 25)
* '''Middle Name'''
* '''Race'''
* '''Ethnicity'''
** African American
** Asian/Pacific Islander
** Caucasian
** Hispanic
** Indian/So. Asian
** Native American
** Unknown/Declined to state
* '''Gender'''
** F = Female
** M = Male
** O = Other
** N = Non-binary
** Z = Prefer not to answer
* '''HighestLevelOfEducation'''
**Less Than HS Graduate
**High School Diploma or Equivalent
**Some College
**Technical School
**2-Year College Degree
**4-Year College Degree
**Some Graduate School
**Master's Level Degree
**Doctorate (Academic)
**Doctorate (Professional)
**Not Indicated
*'''JobTitle'''
*'''Employer'''
*'''JudgesPreferences''' (object)
**this is an object, which can be added to body. like JudgesPreferences: { /* add the following optional parameters below */}
**you need to provide the category id's in the category1-3
**you need to provide judging Session id's for judgingSessions array
**See [[API_Get_Info]] to get these id's
***'''Category1''' (int)
***'''Category2''' (int)
***'''Category3''' (int)
***'''PreviouslyJudged''' (boolean true/false)
***'''JudgingSessions''' (int array)
****Not provided will not update sessions, empty array will clear out sessions for that judge.
****example [] or [1,2,...]

Latest revision as of 11:55, 25 July 2026

Add Person

Creates a person (teacher, judge, staff, admin, volunteer, or student placeholder) for the client/fair. Also supports judge preferences and optional roles.

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/person', {
    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: {
				FirstName: "Jane",
				LastName: "Smith",
				Email: "jsmith@example.edu",
				Email1: "jsmith.alt@example.edu",
				Phone: "801-555-0200",
				Phone1: "801-555-0201",
				Address: "12 Oak St",
				Address2: "",
				City: "Ogden",
				State: "UT",
				Zip: "84401",
				Role: "Teacher",  // Teacher | Judge | Staff | Admin | Volunteer | Student
				Username: "jsmith",       // optional
				Password: "temp-pass",    // optional
				RequirePasswordChange: true,
				SchoolsTeachesAt: [24],   // school ids for teachers
				Prefix: "Dr",
				MiddleName: "A",
				Gender: "F",
				Race: "",
				Ethnicity: "",
				FullLegalName: "Jane A Smith",
				DateOfBirth: null,
				HighestLevelOfEducation: "MS",
				JobTitle: "Science Teacher",
				Employer: "Example School",
				ExternalId: "HR-123",
				IsSpecialAwardJudge: false,
				IsInterpreter: false,
				IsModerator: false,
				Language: "Spanish",
				JudgesPreferences: {  // optional, for judges
					Category1: 12,
					Category2: 13,
					Category3: null,
					PreviouslyJudged: true,
					JudgingSessions: [1, 2]
				}
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success Body echoes the person with assigned Id and Username: 

{
  Success: true,
  Message: null,
  Body: { Id: "person-guid", Username: "jsmith", FirstName: "Jane", ... }
}


Field notes

  • Role is applied after registration via role change.
  • For judges, JudgesPreferences category ids and session ids must exist on the fair (API Get Info).
  • Special award judges with an Employer may get a virtual room named after the employer.
  • Students on projects are usually created via API Add Project participants rather than this endpoint.





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