---
title: "Element <membership>"
source: https://dev.pageseeder.com/api/elements/element_membership.html
description: "API Element reference for <membership>"
last_updated: 2026-08-07T17:09:54+10:00
tokens: ~2170
---

# \<membership\>

## Summary

The group XML output is used to represent PageSeeder [group](../../reference/glossary/group.md) membership associating a [member](../../reference/glossary/member.md) with a group or [project](../../reference/glossary/project.md).

A group membership always involves both a member and a group or project and this is reflected in the model with `<member>,` `<group>` or `<project>` and optional `<details>` as child elements:

```lang-xml
<!-- single membership with member and group -->
<membership>
  <member/>
  <group/>
  <details/>
</membership>
```

However, in cases when we list the memberships for a single member or a single group, we don’t repeat the same element. In the following example, the member is indicated once and is the same for all the following memberships:

```lang-xml
<!-- list of memberships for a single member -->
<memberships>
  <!-- member for whom the following memberships are listed -->
  <member/>
  <membership>
    <group/>
  </membership>
  <membership>
    <group/>
  </membership>
  ...
</memberships>
```

## Usage context

| Permitted content | `<member>` `<group>` `<details>` |
| --- | --- |
| Permitted parent | `<invitations>` `<memberships>` `<membership-creation>` `<membership-modification>` `<unsubscribe>` |

## Attributes

This element includes the following attributes.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| created | `xs:dateTime` | no | When the member joined or was invited to the group |
| deleted | `xs:boolean` | no | If the member was removed from the group |
| email-listed | `xs:boolean` | yes | Whether the member discloses its email address |
| id | `xs:long` | no | The ID of the membership in PageSeeder |
| notification  | `enum` | yes | [Notification](../../reference/glossary/notification.md) preference for the member |
| override | `list` | no | Which attributes from [subgroups](../../reference/glossary/subgroup.md) are overridden (i.e. not inherited) |
| role | `enum` | no | The role of the member in the group or project |
| status | `enum` | yes | The status of the membership |
| subgroups | `xs:string` | no | Comma-separated list of subgroups |

### `@deleted`

An optional boolean attribute set to `true` when a member has been removed from a group.

### `@email-listed`

This boolean attribute indicates whether the member agrees to disclose their email address to other group members.

### `@id`

The PageSeeder database identifier for the group. It is always an immutable positive long value that is unique on a specific PageSeeder server within the set all memberships.

> **Warning:** Memberships acquired through a subgroup do not have a membership ID. When you parse `<membership>` elements that include such memberships, ensure that your code can cope without an ID.

> **Tip:** While membership identifiers are immutable, if members join and leave a group several times, they might have a different membership identifier, so they are not the best key for cached objects based on memberships. Consider using the member and group identifiers or names instead.

### `@notification`

The notification settings for the member in the group. Use one of the following:

- `immediate` (also displayed as “Normal”)
- `essential`
- `daily`
- `weekly`
- `none` (also displayed as “Announcements only”)

### `@override`

This attribute lists which attributes of the membership from subgroups are overridden (not inherited from the subgroup or subgroups). The value is a comma-separated list of the following:

- `listed`
- `notification`
- `role`

For example `override="listed,notification"`. It only appears if the membership is acquired through a subgroup (the `@subgroup` attribute must have a value).

> **Warning:** By default, members inherit the `@email-listed`, `@notification`, and `@role` values from the subgroup, but this attribute is only specified when it is not the case.

### `@role`

The role of the member in the group. Use one of the following:

- `guest`
- `reviewer`
- `contributor`
- `manager`
- `moderator`
- `approver`
- `moderator-and-approver`

### `@status`

The status of the membership. Use one of the following:

- `normal`
- `invited`
- `self_invited`
- `moderated`
- `disabled`
- `unknown`

### `@subgroups`

This attribute returns a comma-separated list of subgroups through which the member is part of the group.

This attribute is only specified if the member is a member by virtue of belonging to a subgroup. If this attribute is specified, the `@override` attribute can also be specified.

> **Note:** The value is a comma-separated list to cater for the rare case when the member obtains membership to a group through multiple subgroups.

## Examples

### Group membership with details

```lang-xml

<membership id="123"
            email-listed="true"
            notification="immediate"
            status="normal"
            role="manager">
    <member id="123"
            firstname="Joan"
            surname="Smith" 
            username="jsmith"
            status="activated">
        <fullname>Joan Smith</fullname>
    </member>
    <group id="4" name="acme-asia" description="Demo group for Asia"/>
    <details>
        <field position="1"
               name="organization"
               title="Organization"
               editable="true">ACME Asia
        </field>
        <field position="2"
               name="telephone"
               title="Telephone"
               editable="true">12345678
        </field>
        <field position="3"
               name="notes"
               title="Notes" 
               editable="true">Follow up
        </field>
    </details>
</membership>
```

## Schema

### XML Schema

```lang-xml

<xs:element name="membership" type="membership"/>

<xs:complexType name="membership">
  <xs:all>
    <xs:element name="member"   type="member-basic" minOccurs="0"/>
    <xs:element name="group"    type="group-basic"  minOccurs="0"/>
    <xs:element name="details"  type="details"      minOccurs="0"/>
  </xs:all>
  <xs:attribute name="created"      type="xs:dateTime"/>
  <xs:attribute name="deleted"      type="boolean"/>
  <xs:attribute name="email-listed" type="boolean" use="required"/>
  <xs:attribute name="id"           type="id"/>
  <xs:attribute name="notification" type="notification"/>
  <xs:attribute name="override"     type="membership-override"/>
  <xs:attribute name="role"         type="membership-role"/>
  <xs:attribute name="status"  
                type="membership-status"
                use="required"/>
  <xs:attribute name="subgroups"    type="xs:string"/>
</xs:complexType>
```

#### Membership attribute types

```lang-xml

<xs:simpleType name="membership-override">
  <xs:restriction base="xs:string">
    <xs:pattern value="((listed|notification|role),?)*"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="membership-role">
  <xs:restriction base="xs:string">
    <xs:enumeration value="guest" />
    <xs:enumeration value="reviewer" />
    <xs:enumeration value="contributor" />
    <xs:enumeration value="manager" />
    <xs:enumeration value="moderator" />
    <xs:enumeration value="approver" />
    <xs:enumeration value="moderator-and-approver" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="membership-status">
  <xs:restriction base="xs:string">
    <xs:enumeration value="normal" />
    <xs:enumeration value="invited" />
    <xs:enumeration value="self-invited" />
    <xs:enumeration value="moderated" />
    <xs:enumeration value="disabled" />
    <xs:enumeration value="unknown" />
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="notification">
  <xs:restriction base="xs:string"> 
    <xs:enumeration value="daily" />
    <xs:enumeration value="essential" />
    <xs:enumeration value="immediate" />
    <xs:enumeration value="none" />
    <xs:enumeration value="weekly" />
  </xs:restriction>
</xs:simpleType>
```

### Relax Schema

```lang-relax

element membership {
   attribute created       { xs:dateTime }?,
   attribute email-listed  { xs:boolean },
   attribute id            { xs:long }?,
   attribute notification  { "none" | "daily" | "immediate" },
   attribute override      { xs:string }?,
   attribute role          { "guest" | "reviewer" | "contributor"
                           | "manager" | "moderator" | "approver"
                           | "moderator-and-approver" }?,
   attribute status        { "normal" | "invited" | "self-invited"
                           | "moderated" | "disabled" | "unknown" },
   attribute subgroups    { text }?
   element group?,
   element member?
}
```

## Compatibility

No change since initial API release.