Creates or updates a user

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

User data

string | null

A new user needs phone_number or email, unless require_contact_info is false. You can send both.

string | null

Must be a valid, deliverable address. A non-blank email that fails validation (subaddressing like user+tag@, disposable domains, domains without MX records) returns a 422. Blank values are ignored. A new user needs phone_number or email, unless require_contact_info is false.

string | null
string | null
string | null

Alternate name (nickname, community name, or alternate romanization). Searchable. Blank values are ignored; an existing alternate name cannot be cleared via the API.

string
string | null

Older single value field. Use secondary_languages instead. Saved as a one item secondary_languages list. When sent together with secondary_languages, it is stored in the older second_language field as sent.

secondary_languages
array of strings | null

Language codes the person also speaks, for example ["es", "fr"]. Codes are saved in lowercase.

secondary_languages
integer | null

Primary chapter ID. Required for new users unless chapter_ids is provided.

chapter_ids
array of integers | null

Array of chapter IDs for multi-chapter membership. First element becomes primary if chapter_id not provided. For a new person, more than one chapter requires the multi-chapter feature. When the request matches an existing person, this replaces their chapter list, keeps their primary chapter, and requires the multi-chapter feature even for one chapter.

chapter_ids
add_chapter_ids
array of integers | null

Array of chapter IDs to add. Requires multi-chapter feature. Applies when the request matches an existing person (POST is an upsert). Ignored when creating a new person; new people require chapter_id or chapter_ids.

add_chapter_ids
remove_chapter_ids
array of integers | null

Array of chapter IDs to remove (cannot remove primary chapter). Requires multi-chapter feature. Applies when the request matches an existing person (POST is an upsert). Ignored when creating a new person.

remove_chapter_ids
integer | null
custom_user_properties
object | null

Custom property values keyed by internal_name. Use a string for single-value fields (text, number, radio, dropdown, single checkbox). Use an array of strings for Multiple Checkboxes fields (e.g. ["Option A", "Option B"]). Comma-separated strings are also accepted for Multiple Checkboxes (e.g. "Option A, Option B"). For Multiple Checkboxes, see append_custom_user_properties to control whether values are merged with or replace existing values. For an Object property, send the title or value of an existing record (GET /custom_user_properties/{custom_user_property_id}/records), not its sub-values. Sub-values live on the record: create records and set their data with POST /custom_user_properties/{custom_user_property_id}/records. When the property has Limit to One Selection on (object_schema limit_to_one), send one title, which replaces the current selection; otherwise send an array of titles. Send an array when a record title contains a comma. Values that match no record are ignored.

boolean | null

Controls how Multiple Checkboxes custom properties are written. Defaults to true (union new values with existing values, the long-standing API behavior). Set to false to overwrite existing values, mirroring bulk update REPLACE mode. Has no effect on non-array field types. Object properties without Limit to One Selection follow the same rule.

add_tags
array of strings | null

Tags to add to the person. A name that does not exist yet creates the tag. Names match exactly and are case sensitive.

add_tags
remove_tags
array of strings | null

Tags to remove from the person. Names match exactly and are case sensitive. When a name is in both add_tags and remove_tags, the tag is removed.

remove_tags
donation_charge
object | null

Optional external donation charge to create

address
object | null

Optional address to create. We will attempt to geocode the address if latitude and longitude are not provided.

string | null

Assessment status key to set on the user

boolean | null
boolean | null
boolean | null
string | null

IANA timezone identifier (e.g., "America/New_York", "Europe/London")

boolean | null

Whether to require phone_number or email for user creation. Defaults to true.

boolean | null

Whether to validate that phone number is textable. Defaults to true.

string | null

Custom property key (internal_name) to use for user lookup/deduplication. Value is read from custom_user_properties[lookup_key]. Allows matching existing users by external IDs stored in custom properties.

boolean | null

Use with lookup_key. Defaults to false. When no user holds the lookup_key value, the API still falls back to phone_number, then email. With strict_lookup_key true, it skips a fallback match that holds a different value for lookup_key and has a different first_name, and creates a new user instead (for example, two members of one household who share a phone). A phone_number or email that another user holds as primary is saved in other_phone_numbers or other_emails instead.

Responses

403

new user only: more than one chapter without the multi-chapter feature, or a chapter outside the API key scope

422

invalid request: invalid email, missing or empty chapter list, invalid lookup_key, failed save, or invalid chapter operation on an existing user

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