API Add Person
From zFairs Contest Management
Contents
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
Roleis applied after registration via role change.- For judges,
JudgesPreferencescategory ids and session ids must exist on the fair (API Get Info). - Special award judges with an
Employermay 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
