Create person

Create a new person or business profile. Identify lookups such as gender, marital status and record type by their property-value codes. Set custom field responses in fields, each with the field's id and its response value. Set business to true to create a business profile, in which case a name is required. For business profiles, the required permission is a financial one (Limited Write Contributions or Full Write Accounting) rather than the people permission shown above. A manager or relationship partner of the family named in family may add to it without that permission when their own organization, else the one organization names, else the default organization, lets heads of household add family members; when that organization refuses and they lack the permission, the call returns a 400 with people_settings_household_edit_refused_desc. Anyone else whose campus or organization limits bind needs Limited Write People at a campus of the family's members, or at the organization of a member holding no campus, to name it in family, else a 403. Naming a family never renames it.

Required permission: Create People

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
int32

The organization the request is made for; the mobile app sends the organization it is showing. It decides a head of household's add when they have no organization of their own, and sets the new person's privacy defaults when their campuses name no organization. Missing, unknown or archived means the default organization, and it is ignored while the account has one organization.

Body Params

The details of the new person.

fields
array of objects | null

Custom fields for this object

fields
boolean | null

True when the record is a business profile rather than an individual.

string | null

Honorific title (e.g. Mr., Dr.) from the person's name.

string | null

First (given) name. Saved with the capitalization sent; the server does not title-case it.

string | null

Middle name.

string | null

Last (family) name. Saved with the capitalization sent, so a lowercase particle (van, de, du) is kept.

string | null

Name suffix (e.g. Jr., III).

aliases
array of objects | null

The person's aliases, split from the stored comma-separated list into individual tags.

aliases
former
array of objects | null

The person's former names, split from the stored comma-separated list into individual tags. Null on the member view (directory true) while multi-campus is on, or while multi-org is on for a caller with an organization limit.

former
string | null

Free-text description of the person or business. Null on the member view (directory true) while multi-campus is on, or while multi-org is on for a caller with an organization limit.

businessAliases
array of objects | null

Business trade names, split from the stored comma-separated list into tags; populated only for business records.

businessAliases
familyPosition
object | null

The person's role within their household (e.g. Adult, Child), with code and name.

emails
array of objects | null

All of the person's email addresses, including merged family emails, each with opt-in status. While multi-campus is on, the merged family emails are in clear when the caller reads any member of the household; the member view still screens them.

emails
phones
array of objects | null

All of the person's phone numbers, including merged family phones; mobile numbers carry text-message opt-in status. While multi-campus is on, the merged family phones are in clear when the caller reads any member of the household; the member view still screens them.

phones
addresses
array of objects | null

All of the person's addresses, including merged family addresses, with the effective one flagged and sorted first. While multi-campus is on, the merged family addresses are in clear when the caller reads any member of the household; the member view still screens them.

addresses
family
object | null

The person's family, including members, contacts, and check-in authorized people. On a save, a name renames the family only when id is the person's own family; any other id changes nothing. On a create, id names the family to join, which keeps its name.

string | null

The person's check-in/giving barcode identifier. Null when the caller does not read the person in full (people read).

contactPreference
object | null

The person's preferred contact method, with the enum id and its description as the name. Populated on a read, where a person who has never set one is reported as id 0, "No Preference", except on the member view (directory true) while multi-campus is on, or while multi-org is on for a caller with an organization limit, where it is null. On a save, omitting it or sending null stores "No Preference".

envelopes
array of objects | null

The person's giving envelope numbers, each as a tag. Null when the caller does not read the person in full (people read).

envelopes
defaultDesignation
object | null

The person's default giving designation. Populated only when the caller has the Limited Read Contributions or Full Read Accounting permission, and never on the member view (directory true) while multi-campus is on, or while multi-org is on for a caller with an organization limit.

gender
object | null

The person's gender, with code and name.

maritalStatus
object | null

The person's marital status, with code and name.

occupation
object | null

The person's occupation, with code and name.

language
object | null

The person's preferred language, with code and name.

race
object | null

The person's race, with code and name.

ethnicity
object | null

The person's ethnicity, with code and name.

string | null

Free-text medical notes for the person. Null when the caller does not read the person in full (people read).

birthday
object | null

The person's birthday (month, day, year) with computed age.

anniversary
object | null

The person's anniversary (month, day, year) with computed years elapsed.

location
object | null

The campus attended, with the organization it belongs to (read-only; ignored on writes). For a person in specific campuses, always one of them; for a person in whole organizations, optional and one of those organizations' campuses; while multi-org is on, a campus of another organization adds that organization, under the same checks as adding it to organizations. For a person in specific campuses it is filled when omitted, and a changed campus sent with the unchanged campuses the person was read with becomes the primary: a person at one campus or none moves to it and a person at several keeps the others. For a person in whole organizations, omitting it or sending null clears it. Without campuses, for a person at campuses or none it stands in for them as a one-campus set, and a campus-limited caller keeps the campuses outside their access. Setting a new one needs an active campus; a campus-limited caller also needs it inside their access and Limited Write People there (Create People for a new person). Sending back the stored one, or a campus the person is already at, skips those checks; a stored one whose organization the person no longer holds is cleared. While multi-campus is off the location sent is ignored.

campuses
array of objects | null

The campuses the person belongs to, ordered by name; empty when the person has no campus. On writes, send the ids
to set the campus set (an empty list means no campus); omit the property and, for a person at campuses or none,
location stands in for it as a one-campus set with the same checks. A campus-limited caller adds, removes and clears campuses inside their
own access only; campuses outside it are kept, and a new person still needs a campus. Placing an existing person at a campus needs Limited Write People at that campus; a new person needs Create People there.
Ignored while multi-campus is off.

campuses
organizations
array of objects | null

The organizations this record is scoped to, all their campuses now and in the future, in name order; empty
unless the record is organization-scoped (then campuses is empty). Honoured only while multi-org is
on. Omit to keep the current organizations.

organizations
primaryOrganization
object | null

The organization of the campus attended, or the chosen organization when it has no campuses; only set for two or
more organizations. One of organizations; null when the person is at campuses or none. With no
campus attended, its time zone gives the person's personal times (such as serving blockouts); with none chosen the
organization with the lowest id gives the zone, and an archived one's zone is ignored (the account zone applies).
On writes a campus attended decides it; otherwise the value sent is taken when it is one of the organizations, and
omitting it or sending null keeps the current one while it stays one of them. A value that is not one of them is
refused while the organizations are in different time zones and ignored otherwise. Honoured only while multi-org is
on; null while it is off.

type
object | null

The person's record type, with code and name.

events
array of objects | null

Milestone events recorded for the person, ordered most recent first, each with an elapsed-time string.

events
contact
object | null

The person's emergency contact, when one is set. While multi-campus is on, a person the caller cannot read in full shows only what they share with the church, and on the member view (directory true) such a contact is left out (null) when they are not listed in the member directory, unless the contact is the caller or a business. On a save, a new contact must be someone the caller may add by id, else a 403; the person's saved contact is not rechecked.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

401

Authentication is required, or the Ocs-Api-Key header is missing or invalid.

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
text/plain
application/json
text/json