Users

A user (path /users) represents a person in your Communal organization — a member, participant, or staff. The user record holds identity and contact information: name, email, address, phone number, and custom profile fields. Users are the people who hold memberships, register for programs, and receive membership cards.

The public API exposes a single update endpoint for users. You cannot list or create users through the API directly — users are created through the Communal platform.

Key attributes on a user:

• Name fields — first_name, last_name, middle_name, preferred_name
• Contact — email, telephone
• Address — profile_address, profile_city, profile_state, profile_zip, profile_country
• Custom data — organization-specific custom profile fields, exposed through dedicated read endpoints

How the pieces connect

Users sit at the center of the platform. They hold memberships, register for programs, and receive cards.

flowchart TD
  U["User
  Jane Doe"]
  U --> S["Subscription
  Gold Membership — Monthly"]
  U --> PS["Program signup
  Summer Camp — Session A"]
  U --> MC["Card delivery
  Apple Wallet + PDF sent"]

Key relationships when querying the API:

• User → memberships — users hold subscriptions to membership types (visible through membership type includes, not the user endpoint directly)
• User → program signups — filter signups with filter[user_id] on the program signups endpoint

Key concepts

Profile sync

The user update endpoint is designed for profile sync — pushing corrected or enriched data from an external system (CRM, membership database, school information system) into Communal. Required fields are first_name, last_name, and email. All other fields are optional and nullable.

Custom profile fields

Organizations can define custom profile fields beyond the standard identity, contact, and address fields. The API exposes these through two read-only endpoints: custom_profile_fields for the field definitions and custom_profile_field_values for the stored values, filterable by user. See Read custom profile fields for details.

Manager vs member access

API access to user data follows a manager/member permission model. Manager API keys can update any user and access sensitive fields like address and phone number. Non-manager keys are restricted to the authenticated user's own record.

API naming

Concept	API path	OpenAPI tag
User	/users	User
Custom profile field	/custom_profile_fields	Custom Profile Field
Custom profile field value	/custom_profile_field_values	Custom Profile Field Value

What's next

• Update user profiles — sync user data from external systems
• Read custom profile fields — list custom field definitions and a user's stored values