People API

Base URL: /api/v1/people/

Manage person records and their associated data (names, addresses, phones, emails, identifiers, demographics).

Endpoints Overview

Persons

Method	Endpoint	Description
GET	`/persons`	List all persons
POST	`/persons`	Create a new person
GET	`/persons/{id}`	Get person details
PATCH	`/persons/{id}`	Update person
DELETE	`/persons/{id}`	Delete person
GET	`/persons/search`	Search persons
GET	`/persons/{id}/demographics`	Get full demographics
GET	`/persons/{id}/roles`	Get all roles (student, teacher, etc.)
GET	`/persons/{id}/photo`	Get person's photo metadata
GET	`/persons/{id}/photo/file`	Get actual image file
POST	`/persons/{id}/photo`	Upload photo
DELETE	`/persons/{id}/photo`	Delete photo
POST	`/persons/merge`	Merge two person records

Person Names

Method	Endpoint	Description
GET	`/person-names`	List names
POST	`/person-names`	Create name
PATCH	`/person-names/{id}`	Update name
POST	`/person-names/{id}/end_date`	End-date a name
GET	`/person-names/history`	Get name history
GET	`/person-names/audit_log`	Get audit log

Other Person Data

Resource	Endpoint	Methods
Addresses	`/person-addresses`	GET, POST, PATCH, DELETE
Phones	`/person-phones`	GET, POST, PATCH, DELETE
Emails	`/person-emails`	GET, POST, PATCH, DELETE
Identifiers	`/person-identifiers`	GET, POST, GET/{id}, PATCH/{id}, DELETE/
Name Configs	`/person-name-configs`	GET, POST, PATCH, DELETE
Races	`/person-races`	GET, POST, DELETE, bulk_update
Visa Statuses	`/person-visa-statuses`	GET, POST, PATCH, DELETE

Institutional email addresses are identity, not contact data

An email is institutional when its type is SCHOOL or its address is at an active, protected institution_domains row (puc.edu, sda.edu, subdomains included) -- both halves count, because Colleague files some puc.edu addresses as personal. SSO links a login to a person by these addresses, so over HTTP only a caller acting as a superuser (a superuser whose active role grants it) may create, change or retire one: POST, PATCH and DELETE /person-emails answer 403 ("Institutional email addresses can only be added or changed by a system administrator") when either the row as it stands or the row as it would become is institutional.

The same rule covers people.primary_email on person create and update: setting it to an address at a protected domain needs a superuser, unless the person already holds that address as a current email. Email rows carry is_institutional so a client can show the field as locked, and GET /people/institutional-domains lists the protected domains so a form can warn before a save the server would refuse. The nightly Colleague import writes the tables directly and is exempt (people/institutional.go).

Person Test Scores

Method	Endpoint	Description
GET	`/person-test-scores`	List test scores
POST	`/person-test-scores`	Create test score
GET	`/person-test-scores/{id}`	Get test score details
PATCH	`/person-test-scores/{id}`	Update test score
DELETE	`/person-test-scores/{id}`	Delete test score

Person Activities

Method	Endpoint	Description
GET	`/person-activities`	List activities
POST	`/person-activities`	Create activity
GET	`/person-activities/{id}`	Get activity details
PATCH	`/person-activities/{id}`	Update activity
DELETE	`/person-activities/{id}`	Delete activity

Person Essays

Method	Endpoint	Description
GET	`/person-essays`	List essays
POST	`/person-essays`	Create essay
GET	`/person-essays/{id}`	Get essay details
PATCH	`/person-essays/{id}`	Update essay
DELETE	`/person-essays/{id}`	Delete essay

Person Recommendations

Method	Endpoint	Description
GET	`/person-recommendations`	List recommendations
POST	`/person-recommendations`	Create recommendation
GET	`/person-recommendations/{id}`	Get recommendation details
PATCH	`/person-recommendations/{id}`	Update recommendation
DELETE	`/person-recommendations/{id}`	Delete recommendation
POST	`/person-recommendations/{id}/resend_request`	Resend recommendation request

Person Honors

Method	Endpoint	Description
GET	`/person-honors`	List honors
POST	`/person-honors`	Create honor
GET	`/person-honors/{id}`	Get honor details
PATCH	`/person-honors/{id}`	Update honor
DELETE	`/person-honors/{id}`	Delete honor

Person Family Members

Method	Endpoint	Description
GET	`/person-family-members`	List family members
POST	`/person-family-members`	Create family member
GET	`/person-family-members/{id}`	Get family member details
PATCH	`/person-family-members/{id}`	Update family member
DELETE	`/person-family-members/{id}`	Delete family member

Photos

Method	Endpoint	Description
GET	`/persons/{personID}/photo/file?size=thumb\|display\|original`	The image itself; `display` by default. Use `thumb` in lists
GET	`/photo-approvals`	List pending photo approvals
POST	`/photo-approvals/{photoID}/review`	Approve or reject a photo
GET	`/photo-approvals/{photoID}/file?size=`	Queue preview, addressed by photo id
GET	`/photo-submissions`	Approved uploads awaiting hand-off to the official repository
POST	`/photo-submissions/mark-submitted`	Record that uploads were put through the external form
GET	`/photo-sync`	Official repository sync status and run history
POST	`/photo-sync/runs`	Start a sync (202; runs in the background)

See Photo Repository for the precedence rules and the sweep's safety guards.

Persons

List Persons

GET /api/v1/people/persons

Returns a paginated list of persons.

Query Parameters

Parameter	Type	Description
`is_active`	boolean	Filter by active status
`gender_id`	integer	Filter by gender lookup ID
`nationality_country_code`	string	Filter by nationality (ISO code)
`role`	string	Filter by role: `student`, `teacher`, `advisor`, `applicant`
`search`	string	Search in email, first_name, last_name
`ordering`	string	Sort by: `created_at`, `updated_at`, `primary_email`

Example Request

bash

curl -X GET "http://localhost:8000/api/v1/people/persons?role=student&search=smith" \
  -b cookies.txt

Success Response (200 OK)

json

{
  "count": 150,
  "next": "http://localhost:8000/api/v1/people/persons?page=2",
  "previous": null,
  "results": [
    {
      "person_id": "550e8400-e29b-41d4-a716-446655440000",
      "person_id_number": "STU001234",
      "primary_email": "john.smith@university.edu",
      "display_name": "John Smith",
      "date_of_birth": "2000-05-15",
      "is_active": true,
      "is_student": true,
      "is_teacher": false,
      "is_advisor": false,
      "is_applicant": false,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

TypeScript Types

typescript

interface Person {
  person_id: string
  person_id_number?: string
  primary_email: string | null
  display_name: string
  date_of_birth: string | null
  gender_id?: number | null
  gender_display: string | null
  ethnicity_id?: number | null
  ethnicity_code?: string | null
  ethnicity_display?: string | null
  religion_id?: number | null
  religion_code?: string | null
  religion_display?: string | null
  country_of_birth_id?: number | null
  country_of_birth_name?: string | null
  citizenship_country_id?: number | null
  citizenship_country_name?: string | null
  nationality_country_code: string | null
  citizenship_country_code: string | null
  is_active: boolean
  is_student?: boolean
  is_teacher?: boolean
  is_advisor?: boolean
  is_applicant?: boolean
  names?: PersonName[]
  addresses?: PersonAddress[]
  phones?: PersonPhone[]
  emails?: PersonEmail[]
  races?: PersonRace[]
  created_at: string
  updated_at: string
}

Get Person Details

GET /api/v1/people/persons/{id}

Get full details for a person including all related data.

Path Parameters

Parameter	Type	Description
`id`	UUID	Person ID

Success Response (200 OK)

json

{
  "person_id": "550e8400-e29b-41d4-a716-446655440000",
  "person_id_number": "STU001234",
  "primary_email": "john.smith@university.edu",
  "display_name": "John Smith",
  "date_of_birth": "2000-05-15",
  "gender_id": 20,
  "gender_display": "Male",
  "ethnicity_id": 30,
  "ethnicity_code": "WHITE",
  "ethnicity_display": "White",
  "religion_id": null,
  "religion_code": null,
  "religion_display": null,
  "country_of_birth_id": 1,
  "country_of_birth_name": "United States",
  "citizenship_country_id": 1,
  "citizenship_country_name": "United States",
  "is_active": true,
  "names": [
    {
      "person_name_id": 1,
      "name_type_code": "LEGAL_PRIMARY",
      "name_type_display": "Legal Primary Name",
      "first_name": "John",
      "middle_name": "Robert",
      "last_name": "Smith",
      "suffix": null,
      "full_name": "John Robert Smith",
      "effective_date": "2000-05-15",
      "end_date": null,
      "is_current": true
    }
  ],
  "addresses": [
    {
      "address_id": 1,
      "address_type_code": "HOME",
      "address_type_display": "Home Address",
      "address_line_1": "123 Main St",
      "address_line_2": "Apt 4B",
      "city": "Anytown",
      "state_province": "NY",
      "postal_code": "12345",
      "country_code": "US",
      "full_address": "123 Main St, Apt 4B, Anytown, NY 12345, US",
      "is_current": true,
      "is_primary": true
    }
  ],
  "phones": [
    {
      "phone_id": 1,
      "phone_type_code": "MOBILE",
      "phone_type_display": "Mobile Phone",
      "country_code": "1",
      "phone_number": "5551234567",
      "extension": null,
      "formatted_number": "+1 5551234567",
      "is_current": true,
      "is_primary": true
    }
  ],
  "emails": [
    {
      "email_id": 1,
      "email_type_code": "INSTITUTIONAL",
      "email_type_display": "Institutional Email",
      "email_address": "john.smith@university.edu",
      "is_current": true,
      "is_primary": true
    }
  ],
  "races": [
    {
      "person_race_id": 1,
      "race_id": 5,
      "race_code": "WHITE",
      "race_display": "White"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

Create Person

POST /api/v1/people/persons

Create a new person record.

Request Body

Field	Type	Required	Description
`primary_email`	string	No	Primary email address
`date_of_birth`	date	No	Date of birth (YYYY-MM-DD)
`gender_id`	integer	No	Gender lookup value ID
`ethnicity_id`	integer	No	Ethnicity lookup value ID
`religion_id`	integer	No	Religion lookup value ID
`country_of_birth_id`	integer	No	Country of birth ID
`citizenship_country_id`	integer	No	Citizenship country ID
`nationality_country_code`	string	No	Nationality ISO code
`is_active`	boolean	No	Active status (default: true)

Example Request

bash

curl -X POST http://localhost:8000/api/v1/people/persons \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "primary_email": "new.student@university.edu",
    "date_of_birth": "2005-03-20",
    "gender_id": 20,
    "citizenship_country_id": 1
  }'

Update Person

PATCH /api/v1/people/persons/{id}

Update a person's demographic information.

Request Body

Field	Type	Description
`date_of_birth`	date	Date of birth
`gender_id`	integer	Gender lookup value ID
`ethnicity_id`	integer	Ethnicity lookup value ID
`religion_id`	integer	Religion lookup value ID
`country_of_birth_id`	integer	Country of birth ID
`citizenship_country_id`	integer	Citizenship country ID
`nationality_country_code`	string	Nationality ISO code
`primary_email`	string	Primary email
`is_active`	boolean	Active status

Search Persons

GET /api/v1/people/persons/search?q={query}

Search persons by name or email.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (min 2 characters)

Success Response (200 OK)

Returns up to 20 matching persons in list format.

Get Demographics

GET /api/v1/people/persons/{id}/demographics

Get full demographic information including races and visa statuses.

Success Response (200 OK)

json

{
  "success": true,
  "data": {
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "John Smith",
    "date_of_birth": "2000-05-15",
    "gender_id": 20,
    "gender_display": "Male",
    "ethnicity_id": 30,
    "ethnicity_code": "WHITE",
    "ethnicity_display": "White",
    "races": [
      {
        "person_race_id": 1,
        "race_code": "WHITE",
        "race_display": "White"
      }
    ],
    "visa_statuses": [
      {
        "visa_status_id": 1,
        "visa_type_code": "F1",
        "visa_type_display": "F-1 Student Visa",
        "visa_expiry_date": "2026-05-15",
        "sevis_id": "N0001234567",
        "is_current": true
      }
    ]
  }
}

Get Person Roles

GET /api/v1/people/persons/{id}/roles

Get all roles associated with a person (student, teacher, advisor, applicant).

Success Response (200 OK)

json

{
  "success": true,
  "data": {
    "person_id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "John Smith",
    "is_student": true,
    "student": {
      "student_id": 1001,
      "student_number": "STU001234",
      "initial_term_code": "FA2024",
      "student_status_display": "Active",
      "programs": [...]
    },
    "is_teacher": false,
    "teacher": null,
    "is_advisor": false,
    "advisors": [],
    "is_applicant": true,
    "applications": [
      {
        "applicant_id": 500,
        "application_term_code": "FA2024",
        "application_status_display": "Admitted"
      }
    ],
    "authorization_roles": [
      {
        "role_code": "STUDENT",
        "role_name": "Student",
        "is_currently_active": true
      }
    ]
  }
}

TypeScript Types

typescript

interface PersonRoles {
  person_id: string
  display_name: string
  is_student: boolean
  student: Student | null
  is_teacher: boolean
  teacher: Teacher | null
  is_advisor: boolean
  advisors: Advisor[]
  is_applicant: boolean
  applications: Applicant[]
  authorization_roles: AuthorizationRole[]
}

Photo Management

Get Photo Metadata

GET /api/v1/people/persons/{id}/photo

Returns metadata about the person's photo (status, approval state, URLs).

Get Photo File

GET /api/v1/people/persons/{id}/photo/file

Returns the actual image file (JPG or PNG) or a default placeholder.

Response: Image file (JPG or PNG)

Upload Photo

POST /api/v1/people/persons/{id}/photo

Upload a photo for a person.

Content-Type: multipart/form-data

Field	Type	Description
`photo`	file	JPG or PNG image (max 2MB)

Delete Photo

DELETE /api/v1/people/persons/{id}/photo

Delete a person's photo.

Photo Approvals

Manage photo approval workflow for uploaded person photos.

List Pending Approvals

GET /api/v1/people/photo-approvals

Returns a list of photos pending approval.

Review Photo

POST /api/v1/people/photo-approvals/{photoID}/review

Approve or reject a pending photo.

Request Body

Field	Type	Required	Description
`action`	string	Yes	`approve` or `reject`
`reason`	string	No	Reason for rejection

Person Merge

Merge Persons

POST /api/v1/people/persons/merge

Merge two person records into one. The source person's data is merged into the target person, and the source person is deactivated.

Request Body

Field	Type	Required	Description
`source_person_id`	UUID	Yes	Person to merge from (will be deactivated)
`target_person_id`	UUID	Yes	Person to merge into (will be kept)

Person Names

Names support full audit logging and historical tracking.

Create Name

POST /api/v1/people/person-names

Request Body

Field	Type	Required	Description
`person_id`	UUID	Yes	Person ID
`name_type_id`	integer	Yes	Name type (LEGAL_PRIMARY, PREFERRED, MAIDEN, etc.)
`first_name`	string	Yes	First name
`last_name`	string	Yes	Last name
`middle_name`	string	No	Middle name
`suffix`	string	No	Suffix (Jr., III, etc.)
`effective_date`	date	No	When name became effective
`change_reason`	string	No	Reason for change (for audit)

TypeScript Types

typescript

interface PersonName {
  person_name_id: number
  person_id: string
  name_type_id?: number
  name_type_code: string
  name_type_display: string
  first_name: string | null
  middle_name: string | null
  last_name: string | null
  suffix: string | null
  full_name: string
  effective_date: string
  end_date: string | null
  is_current: boolean
}

End-Date Name

POST /api/v1/people/person-names/{id}/end_date

Mark a name record as no longer current.

Request Body

Field	Type	Required	Description
`end_date`	date	No	End date (defaults to today)
`change_reason`	string	No	Reason for ending

Get Name History

GET /api/v1/people/person-names/history?person_id={person_id}

Get all name records for a person, including historical names.

Get Audit Log

GET /api/v1/people/person-names/audit_log?person_id={person_id}

Get audit log entries for name changes.

Success Response (200 OK)

json

{
  "success": true,
  "data": [
    {
      "audit_id": 1,
      "person_name_id": 5,
      "action": "UPDATE",
      "action_display": "Updated",
      "changed_by": "admin@example.com",
      "changed_at": "2024-06-20T14:45:00Z",
      "field_name": "last_name",
      "old_value": "Smith",
      "new_value": "Smith-Jones",
      "change_reason": "Marriage"
    }
  ]
}

Other Person Data

Addresses, Phones, Emails

All follow the same CRUD pattern with filtering by person_id.

Common Fields

Addresses:

address_type_id - Type (HOME, MAILING, PERMANENT, etc.)
address_line_1, address_line_2, address_line_3
city, state_province, postal_code, country_code
is_current, is_primary

Phones:

phone_type_id - Type (MOBILE, HOME, WORK, etc.)
country_code, phone_number, extension
is_current, is_primary

Emails:

email_type_id - Type (PERSONAL, WORK, INSTITUTIONAL)
email_address
is_current, is_primary

Person Identifiers

Full CRUD operations for person identifier records (SSN, passport, driver's license, etc.).

Method	Endpoint	Description
GET	`/person-identifiers`	List identifiers (filter by person_id)
POST	`/person-identifiers`	Create identifier
GET	`/person-identifiers/{id}`	Get identifier details
PATCH	`/person-identifiers/{id}`	Update identifier
DELETE	`/person-identifiers/{id}`	Delete identifier

Races (Multi-Select)

Bulk Update Races

POST /api/v1/people/person-races/bulk_update

Replace all races for a person.

Request Body

json

{
  "person_id": "550e8400-e29b-41d4-a716-446655440000",
  "race_ids": [1, 3, 5]
}

Visa Statuses

Track immigration status for international people (migration 281). A person is international when a citizenship is on file and none of their citizenships -- the primary citizenship_country_id or any additional citizenship -- is the HOME_COUNTRY setting. The server decides it and returns it on the person detail as is_international, with home_country_code; clients must not recompute it.

Create Visa Status

POST /api/v1/people/person-visa-statuses

Refused with 409 for a person who is not international, so records the UI would hide cannot accumulate. PATCH /person-visa-statuses/{visaStatusID} takes the same fields, all optional.

Request Body

Field	Type	Required	Description
`person_id`	UUID	Yes	Person ID
`visa_type_id`	integer	Yes	`VISA_TYPE` lookup: `STUDENT`, `RESIDENT`, `H1B`, `F1`, `J1`, `M1`, `DEPENDENT`, `REFUGEE`, `OTHER`
`visa_expiry_date`	date	No	Visa expiration date
`sevis_id`	string	No	SEVIS ID (max 20)
`effective_date`	date	No	When the status became effective
`is_current`	boolean	No	Is this the current status
`notes`	string	No	Additional notes (max 500)
`status`	string	No	`PENDING`, `ACTIVE` (default), `EXPIRED` or `TERMINATED`
`document_issue_date`, `program_start_date`, `program_end_date`	date	No	Program end may not precede its start
`entry_date`, `port_of_entry`	date, string	No	Most recent entry
`orientation_date`	date	No
`sponsor`, `financial_support_source`, `financial_support_amount`	string	No	Amount is a decimal string
`health_insurance_end_date`	date	No
`work_auth_type`	string	No	`CPT`, `OPT`, `STEM_OPT`, `ON_CAMPUS` or `OTHER`
`work_auth_start_date`, `work_auth_end_date`	date	No	End may not precede start
`sevis_status`	string	No	US only: `INITIAL`, `ACTIVE`, `TERMINATED` or `COMPLETED`
`form_type`	string	No	US only: `I20` or `DS2019`

sevis_status and form_type are accepted in any deployment; the UI shows them only when home_country_code is US. Document numbers (passport, I-94, EAD, I-20 / DS-2019) are not fields here: they are person identifiers, so they inherit encryption, audited reveal and retention.

TypeScript Types

typescript

interface PersonVisaStatus {
  visa_status_id: number
  person_id: string
  visa_type_id: number
  visa_type_display?: string
  visa_expiry_date?: string
  sevis_id?: string
  is_current: boolean
  effective_date?: string
  notes?: string
  status?: 'PENDING' | 'ACTIVE' | 'EXPIRED' | 'TERMINATED'
  // ...plus the immigration fields in the table above
}

Additional Citizenships

core.person_citizenships (migration 281) holds citizenships beyond the single citizenship_country_id on the person. Gated like the other person sub-records (PEOPLE.VIEW to read, PEOPLE.EDIT to write).

Method	Endpoint	Description
GET	`/person-citizenships?person_id=`	List a person's additional citizenships (`person_id` required)
POST	`/person-citizenships`	Add one: `{ "person_id": "...", "country_id": 840 }`. 409 if already recorded; a validation error for an unknown country
DELETE	`/person-citizenships/{citizenshipID}`	Remove one

Each row is { person_citizenship_id, person_id, country_id, country_name, country_code }.

Person Test Scores

Manage standardized test scores (SAT, ACT, GRE, etc.) for persons.

Method	Endpoint	Description
GET	`/person-test-scores`	List test scores (filter by person_id)
POST	`/person-test-scores`	Create test score
GET	`/person-test-scores/{id}`	Get test score details
PATCH	`/person-test-scores/{id}`	Update test score
DELETE	`/person-test-scores/{id}`	Delete test score

Person Activities

Manage extracurricular activities and involvement records for persons.

Method	Endpoint	Description
GET	`/person-activities`	List activities (filter by person_id)
POST	`/person-activities`	Create activity
GET	`/person-activities/{id}`	Get activity details
PATCH	`/person-activities/{id}`	Update activity
DELETE	`/person-activities/{id}`	Delete activity

Person Essays

Manage essay submissions for persons (typically for admissions).

Method	Endpoint	Description
GET	`/person-essays`	List essays (filter by person_id)
POST	`/person-essays`	Create essay
GET	`/person-essays/{id}`	Get essay details
PATCH	`/person-essays/{id}`	Update essay
DELETE	`/person-essays/{id}`	Delete essay

Person Recommendations

Manage recommendation requests and submissions for persons.

Method	Endpoint	Description
GET	`/person-recommendations`	List recommendations (filter by person_id)
POST	`/person-recommendations`	Create recommendation
GET	`/person-recommendations/{id}`	Get recommendation details
PATCH	`/person-recommendations/{id}`	Update recommendation
DELETE	`/person-recommendations/{id}`	Delete recommendation
POST	`/person-recommendations/{id}/resend_request`	Resend recommendation request email

Person Honors

Manage academic honors and awards for persons.

Method	Endpoint	Description
GET	`/person-honors`	List honors (filter by person_id)
POST	`/person-honors`	Create honor
GET	`/person-honors/{id}`	Get honor details
PATCH	`/person-honors/{id}`	Update honor
DELETE	`/person-honors/{id}`	Delete honor

Person Family Members

Manage family member records linked to persons (parents, guardians, siblings, etc.).

Method	Endpoint	Description
GET	`/person-family-members`	List family members (filter by person_id)
POST	`/person-family-members`	Create family member
GET	`/person-family-members/{id}`	Get family member details
PATCH	`/person-family-members/{id}`	Update family member
DELETE	`/person-family-members/{id}`	Delete family member

Complete endpoint reference

Every route this domain registers, with the permission node that gates it. Generated from the route table, so it is complete by construction — the sections above explain behaviour, this one guarantees nothing is missing.

Paths are relative to /api/v1/people. A node in italics is an exemption rather than a grant: selfservice acts only on the caller's own record, public needs no session at all, and custom carries its own wrapper.

Method	Endpoint	Permission node	Description
GET	`/identifier-access-log`	`PEOPLE.IDENTIFIER.ACCESS_LOG`	Get identifier access log
GET	`/identifier-types`	selfservice	List identifier types
POST	`/identifier-types`	`ADMIN.IDENTIFIER_TYPES`	Create an identifier type
DELETE	`/identifier-types/{identifierTypeID}`	`ADMIN.IDENTIFIER_TYPES`	Delete an identifier type
GET	`/identifier-types/{identifierTypeID}`	selfservice	Get one identifier type
PATCH	`/identifier-types/{identifierTypeID}`	`ADMIN.IDENTIFIER_TYPES`	Update an identifier type
GET	`/institutional-domains`	selfservice	List protected institution domains
GET	`/me`	selfservice	Get the caller's own person record
POST	`/me/addresses`	selfservice	Add an address to the caller's record
PATCH	`/me/addresses/{addressID}`	selfservice	Update one of the caller's addresses
POST	`/me/emails`	selfservice	Add an email to the caller's record
PATCH	`/me/emails/{emailID}`	selfservice	Update one of the caller's emails
POST	`/me/phones`	selfservice	Add a phone to the caller's record
PATCH	`/me/phones/{phoneID}`	selfservice	Update one of the caller's phones
GET	`/me/relationships`	selfservice	List the caller's relationships
GET	`/me/relationships/types`	selfservice	List relationship types
GET	`/person-activities`	`PEOPLE.VIEW`	List person activities
POST	`/person-activities`	`PEOPLE.EDIT`	Create a person activity
DELETE	`/person-activities/{activityID}`	`PEOPLE.EDIT`	Delete a person activity
GET	`/person-activities/{activityID}`	`PEOPLE.VIEW`	Get one person activity
PATCH	`/person-activities/{activityID}`	`PEOPLE.EDIT`	Update a person activity
GET	`/person-addresses`	`PEOPLE.VIEW`	List person addresses
POST	`/person-addresses`	`PEOPLE.EDIT`	Create a person address
DELETE	`/person-addresses/{addressID}`	`PEOPLE.EDIT`	Delete a person address
GET	`/person-addresses/{addressID}`	`PEOPLE.VIEW`	Get one person address
PATCH	`/person-addresses/{addressID}`	`PEOPLE.EDIT`	Update a person address
GET	`/person-citizenships`	`PEOPLE.VIEW`	List a person's additional citizenships
POST	`/person-citizenships`	`PEOPLE.EDIT`	Add a citizenship
DELETE	`/person-citizenships/{citizenshipID}`	`PEOPLE.EDIT`	Remove a citizenship
GET	`/person-emails`	`PEOPLE.VIEW`	List person emails
POST	`/person-emails`	`PEOPLE.EDIT`	Create a person email
DELETE	`/person-emails/{emailID}`	`PEOPLE.EDIT`	Delete a person email
GET	`/person-emails/{emailID}`	`PEOPLE.VIEW`	Get one person email
PATCH	`/person-emails/{emailID}`	`PEOPLE.EDIT`	Update a person email
GET	`/person-essays`	`PEOPLE.VIEW`	List person essays
POST	`/person-essays`	`PEOPLE.EDIT`	Create a person essay
DELETE	`/person-essays/{essayID}`	`PEOPLE.EDIT`	Delete a person essay
GET	`/person-essays/{essayID}`	`PEOPLE.VIEW`	Get one person essay
PATCH	`/person-essays/{essayID}`	`PEOPLE.EDIT`	Update a person essay
GET	`/person-family-members`	`PEOPLE.VIEW`	List person family members
POST	`/person-family-members`	`PEOPLE.EDIT`	Create a person family member
DELETE	`/person-family-members/{familyMemberID}`	`PEOPLE.EDIT`	Delete a person family member
GET	`/person-family-members/{familyMemberID}`	`PEOPLE.VIEW`	Get one person family member
PATCH	`/person-family-members/{familyMemberID}`	`PEOPLE.EDIT`	Update a person family member
GET	`/person-honors`	`PEOPLE.VIEW`	List person honors
POST	`/person-honors`	`PEOPLE.EDIT`	Create a person honor
DELETE	`/person-honors/{honorID}`	`PEOPLE.EDIT`	Delete a person honor
GET	`/person-honors/{honorID}`	`PEOPLE.VIEW`	Get one person honor
PATCH	`/person-honors/{honorID}`	`PEOPLE.EDIT`	Update a person honor
GET	`/person-identifiers`	`PEOPLE.VIEW`	List person identifiers
POST	`/person-identifiers`	`PEOPLE.EDIT`	Create a person identifier
DELETE	`/person-identifiers/{identifierID}`	`PEOPLE.EDIT`	Delete a person identifier
GET	`/person-identifiers/{identifierID}`	`PEOPLE.VIEW`	Get one person identifier
PATCH	`/person-identifiers/{identifierID}`	`PEOPLE.EDIT`	Update a person identifier
POST	`/person-identifiers/{identifierID}/reveal`	selfservice	Add reveal to a person identifier
GET	`/person-name-configs`	`PEOPLE.VIEW`	List person name configs
POST	`/person-name-configs`	`PEOPLE.EDIT`	Create a person name config
DELETE	`/person-name-configs/{configID}`	`PEOPLE.EDIT`	Delete a person name config
GET	`/person-name-configs/{configID}`	`PEOPLE.VIEW`	Get one person name config
GET	`/person-names`	`PEOPLE.VIEW`	List person names
POST	`/person-names`	`PEOPLE.EDIT`	Create a person name
GET	`/person-names/audit_log`	`PEOPLE.VIEW`	Get audit log
GET	`/person-names/history`	`PEOPLE.VIEW`	Get history
DELETE	`/person-names/{nameID}`	`PEOPLE.EDIT`	Delete a person name
GET	`/person-names/{nameID}`	`PEOPLE.VIEW`	Get one person name
PATCH	`/person-names/{nameID}`	`PEOPLE.EDIT`	Update a person name
GET	`/person-names/{nameID}/audit-log`	`PEOPLE.VIEW`	Get the person name's audit log
POST	`/person-names/{nameID}/end_date`	`PEOPLE.EDIT`	Add end date to a person name
GET	`/person-phones`	`PEOPLE.VIEW`	List person phones
POST	`/person-phones`	`PEOPLE.EDIT`	Create a person phone
DELETE	`/person-phones/{phoneID}`	`PEOPLE.EDIT`	Delete a person phone
GET	`/person-phones/{phoneID}`	`PEOPLE.VIEW`	Get one person phone
PATCH	`/person-phones/{phoneID}`	`PEOPLE.EDIT`	Update a person phone
GET	`/person-races`	`PEOPLE.VIEW`	List person races
POST	`/person-races`	`PEOPLE.EDIT`	Create a person race
POST	`/person-races/bulk_update`	`PEOPLE.EDIT`	Bulk update
DELETE	`/person-races/{raceID}`	`PEOPLE.EDIT`	Delete a person race
GET	`/person-recommendations`	`PEOPLE.VIEW`	List person recommendations
POST	`/person-recommendations`	`PEOPLE.EDIT`	Create a person recommendation
DELETE	`/person-recommendations/{recommendationID}`	`PEOPLE.EDIT`	Delete a person recommendation
GET	`/person-recommendations/{recommendationID}`	`PEOPLE.VIEW`	Get one person recommendation
PATCH	`/person-recommendations/{recommendationID}`	`PEOPLE.EDIT`	Update a person recommendation
POST	`/person-recommendations/{recommendationID}/resend_request`	`PEOPLE.EDIT`	Add resend request to a person recommendation
GET	`/person-relationships`	`PEOPLE.TAB.RELATIONSHIPS`	List person relationships
POST	`/person-relationships`	`PEOPLE.TAB.RELATIONSHIPS`	Create a person relationship
GET	`/person-relationships/types`	`PEOPLE.TAB.RELATIONSHIPS`	List types
DELETE	`/person-relationships/{relationshipID}`	`PEOPLE.TAB.RELATIONSHIPS`	Delete a person relationship
GET	`/person-relationships/{relationshipID}`	`PEOPLE.TAB.RELATIONSHIPS`	Get one person relationship
PATCH	`/person-relationships/{relationshipID}`	`PEOPLE.TAB.RELATIONSHIPS`	Update a person relationship
GET	`/person-test-scores`	`PEOPLE.VIEW`	List person test scores
POST	`/person-test-scores`	`PEOPLE.EDIT`	Create a person test score
DELETE	`/person-test-scores/{scoreID}`	`PEOPLE.EDIT`	Delete a person test score
GET	`/person-test-scores/{scoreID}`	`PEOPLE.VIEW`	Get one person test score
PATCH	`/person-test-scores/{scoreID}`	`PEOPLE.EDIT`	Update a person test score
GET	`/person-visa-statuses`	`PEOPLE.VIEW`	List person visa statuses
POST	`/person-visa-statuses`	`PEOPLE.EDIT`	Create a person visa status
DELETE	`/person-visa-statuses/{visaStatusID}`	`PEOPLE.EDIT`	Delete a person visa status
GET	`/person-visa-statuses/{visaStatusID}`	`PEOPLE.VIEW`	Get one person visa status
PATCH	`/person-visa-statuses/{visaStatusID}`	`PEOPLE.EDIT`	Update a person visa status
GET	`/persons`	`PEOPLE.VIEW`	List persons
POST	`/persons`	`PEOPLE.EDIT`	Create a person
POST	`/persons/merge`	`PEOPLE.EDIT`	Merge
GET	`/persons/search`	`PEOPLE.SEARCH`	Search
DELETE	`/persons/{personID}`	`PEOPLE.EDIT`	Delete a person
GET	`/persons/{personID}`	`PEOPLE.VIEW`	Get one person
PATCH	`/persons/{personID}`	`PEOPLE.EDIT`	Update a person
GET	`/persons/{personID}/demographics`	`PEOPLE.TAB.DEMOGRAPHICS`	List the person's demographics
GET	`/persons/{personID}/ferpa-history`	`PEOPLE.FERPA_OPT_OUT`	Get FERPA opt-out history
PUT	`/persons/{personID}/ferpa-opt-out`	`PEOPLE.FERPA_OPT_OUT`	Set FERPA opt-out
DELETE	`/persons/{personID}/photo`	selfservice	Remove photo from a person
GET	`/persons/{personID}/photo`	selfservice	Get the person's photo
POST	`/persons/{personID}/photo`	selfservice	Add photo to a person
GET	`/persons/{personID}/photo/file`	selfservice	Get file
GET	`/persons/{personID}/roles`	`PEOPLE.VIEW`	List the person's roles
GET	`/persons/{personID}/superscore/{testTypeID}`	`STUDENTS.TAB.TEST_SCORES`	Get one superscore
GET	`/persons/{personID}/test-scores`	`STUDENTS.TAB.TEST_SCORES`	List the person's test scores
POST	`/persons/{personID}/test-scores`	`STUDENTS.SCORES.EDIT`	Add test scores to a person
GET	`/photo-approvals`	`PEOPLE.PHOTO_APPROVAL_QUEUE`	List photo approvals
GET	`/photo-approvals/{photoID}/file`	`PEOPLE.PHOTO_APPROVAL_QUEUE`	Queue image, by photo id
POST	`/photo-approvals/{photoID}/review`	`PEOPLE.PHOTO_APPROVAL_QUEUE`	Add review to a photo approval
GET	`/photo-submissions`	`PEOPLE.PHOTO_SUBMISSION_QUEUE`	Uploads awaiting submission
POST	`/photo-submissions/mark-submitted`	`PEOPLE.PHOTO_SUBMISSION_QUEUE`	Mark uploads submitted
GET	`/photo-sync`	`PEOPLE.PHOTO_SYNC`	Sync status and history
POST	`/photo-sync/runs`	`PEOPLE.PHOTO_SYNC`	Start a sync

People API ​

Endpoints Overview ​

Persons ​

Person Names ​

Other Person Data ​

Person Test Scores ​

Person Activities ​

Person Essays ​

Person Recommendations ​

Person Honors ​

Person Family Members ​

Photos ​

Persons ​

List Persons ​

Query Parameters ​

Example Request ​

Success Response (200 OK) ​

TypeScript Types ​

Get Person Details ​

Path Parameters ​

Success Response (200 OK) ​

Create Person ​

Request Body ​

Example Request ​

Update Person ​

Request Body ​

Search Persons ​

Query Parameters ​

Success Response (200 OK) ​

Get Demographics ​

Success Response (200 OK) ​

Get Person Roles ​

Success Response (200 OK) ​

TypeScript Types ​

Photo Management ​

Get Photo Metadata ​

Get Photo File ​

Upload Photo ​

Delete Photo ​

Photo Approvals ​

List Pending Approvals ​

Review Photo ​

Request Body ​

Person Merge ​

Merge Persons ​

Request Body ​

Person Names ​

Create Name ​

Request Body ​

TypeScript Types ​

End-Date Name ​

Request Body ​

Get Name History ​

Get Audit Log ​

Success Response (200 OK) ​

Other Person Data ​

Addresses, Phones, Emails ​

Common Fields ​

Person Identifiers ​

Races (Multi-Select) ​

Bulk Update Races ​

Request Body ​

Visa Statuses ​

Create Visa Status ​

Request Body ​

TypeScript Types ​

Additional Citizenships ​

Person Test Scores ​

Person Activities ​

Person Essays ​

Person Recommendations ​

Person Honors ​

Person Family Members ​

Complete endpoint reference ​

People API

Endpoints Overview

Persons

Person Names

Other Person Data

Person Test Scores

Person Activities

Person Essays

Person Recommendations

Person Honors

Person Family Members

Photos

Persons

List Persons

Query Parameters

Example Request

Success Response (200 OK)

TypeScript Types

Get Person Details

Path Parameters

Success Response (200 OK)

Create Person

Request Body

Example Request

Update Person

Request Body

Search Persons

Query Parameters

Success Response (200 OK)

Get Demographics

Success Response (200 OK)

Get Person Roles

Success Response (200 OK)

TypeScript Types

Photo Management

Get Photo Metadata

Get Photo File

Upload Photo

Delete Photo

Photo Approvals

List Pending Approvals

Review Photo

Request Body

Person Merge

Merge Persons

Request Body

Person Names

Create Name

Request Body

TypeScript Types

End-Date Name

Request Body

Get Name History

Get Audit Log

Success Response (200 OK)

Other Person Data

Addresses, Phones, Emails

Common Fields

Person Identifiers

Races (Multi-Select)

Bulk Update Races

Request Body

Visa Statuses

Create Visa Status

Request Body

TypeScript Types

Additional Citizenships

Person Test Scores

Person Activities

Person Essays

Person Recommendations

Person Honors

Person Family Members

Complete endpoint reference