Difference between revisions of "API Add Person"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(3 intermediate revisions by 2 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: "Smith",
−
,LastName: 'Doe'
+
Email: "jsmith@example.edu",
−
,Prefix: 'Dr'
+
Email1: "jsmith.alt@example.edu",
−
,Email: 'jane@example.com'
+
Phone: "801-555-0200",
−
,Email1: 'Doe@example.com'
+
Phone1: "801-555-0201",
−
,Phone: '800-000-0000'
+
Address: "12 Oak St",
−
,Phone1: '800-123-1324'
+
Address2: "",
−
,Address: '1219 45th st'
+
City: "Ogden",
−
,Address2: 'APT 3B'
+
State: "UT",
−
,City: 'Ogden'
+
Zip: "84401",
−
,State: 'VA'
+
Role: "Teacher",  // Teacher | Judge | Staff | Admin | Volunteer | Student
−
,Zip: '65951'
+
Username: "jsmith",       // optional
−
,SchoolsTeachesAt: [1] // int array of school ids
+
Password: "temp-pass",    // optional
−
,Role: 'Teacher' // { Teacher, Judge, Staff, Admin, Volunteer}
+
RequirePasswordChange: true,
−
,Language:'Spanish' //optional - interpreter need for this language
+
SchoolsTeachesAt: [24],  // school ids for teachers
−
,JudgesPreferences:{ //optional
+
Prefix: "Dr",
−
  Category1: 123,
+
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 37: 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>
 
</syntaxhighlight>
  
 +
=== Response ===
 +
On success <code>Body</code> echoes the person with assigned <code>Id</code> and <code>Username</code>:
  
−
=== Additional Optional fields ===
+
<pre>
−
All of these fields would be part of the body.
+
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: { Id: "person-guid", Username: "jsmith", FirstName: "Jane", ... }
 +
}
 +
</pre>
  
−
* '''Username''' (string max length 25)
 
−
**If this username is not available one will be assigned
 
−
* '''Password''' (string max length 25)
 
−
* '''Middle Name'''
 
−
* '''ExternalId''' (string: can be used to match to your records)
 
−
* '''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'''
 
−
*'''DateOfBirth''' (yyyy-mm-dd)
 
−
*'''FullLegalName'''
 
−
*'''BackgroundcheckAtUtc''' (yyyy-mm-dd)
 
−
*'''BackgroundCheckStatus'''
 
−
*'''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,...]
 
−
*'''IsSpecialAwardJudge''' (boolean true/false)
 
−
*'''IsModerator''' (boolean true/false)
 
−
*'''IsInterpreter''' (boolean true/false)
 
  
 +
=== 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.
  
−
=== Notes ===
 
  
−
When you call the /person API you can set the username, if the username you provided is not available we add a number to the end of it. Spaces are removed from the username. 
+
=== Related APIs ===
 +
* [[API Get Teachers]] / [[API Get Judges]]
 +
* [[API Get Info]]
 +
* [[API Add Project]]
 +
* [[API SSO]]
  
−
If you do not provide a password when you call the /person api then none is set and the account will need to have a password set before you can login with this person. A user can use their name and email to reset the password.
 
  
−
<br/><br/><br/><br/>
+
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Latest revision as of 12: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.


Related APIs




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