The WPResidence real estate CRM has a simple but effective permission model. This article explains the three roles, what each can see and do, and how data is scoped for agents.

The Three Roles

Administrator

Full access to the entire CRM. Administrators see every contact, every deal, every task, every activity — regardless of who created or owns the record. They can configure settings, manage automations, and use CSV import/export.

Agent (wpresidence_agent / wpresidence_agent_role)

Scoped access. Agents see:

• Contacts they created OR contacts where they are the assigned agent.
• Deals, tasks, and activities linked to those contacts.
• CSV export of their own records (no import).

Agents cannot see: the Automations section, CRM Settings, or other agents’ private records.

Author (and other WP roles)

Minimal access. Authors see only records they personally created. They cannot use CSV import/export, cannot see Automations or Settings.

The Permission Matrix

Module	Admin	Agent	Author
Contacts	All	Own	Own
Deals	All	Own	Own
Tasks	All	Own	Own
Activities	All	Own	Own
Automations	All	—	—
Settings	All	—	—
Import / Export	All	Own (export only)	—

How “Own” Is Defined

A record is considered “own” if either:

• The user is the creator (user_id on the record).
• The user is the assigned agent (assigned_agent_id on the record, where applicable).

This is why reassigning a contact to a different agent effectively hands visibility over: the new assignee sees the record, the old one loses it (unless they created it in the first place).

What Permissions Do NOT Control

• Email visibility. Notifications sent to the assigned agent are email messages — once received, forwarding is outside the CRM’s control.
• Notes. Notes on a record are visible to everyone who can see the record. Use the contact’s Private Note field for information you want scoped to yourself.
• Custom fields. Currently there is no per-field permission control.

Adjusting Permissions

The permissions matrix is defined in code and seeded to the database on activation. There is no admin UI for changing per-role permissions in the current release. If you need custom permission structures, see the developer version of this article for how to override them.

Handing Off a Portfolio

When an agent leaves:

1. An administrator selects all the leaving agent’s contacts in the Contacts list.
2. Uses the bulk Assign Agent action to reassign to the replacement.
3. Deals and tasks linked to those contacts remain linked but are now visible to the replacement.

Multi-Brand or Multi-Office Setups

The CRM does not have a built-in concept of offices or brands. If you need that separation, you can use the tags field on contacts and filter by tag. For stricter separation, custom development is needed to layer on top of the existing permissions.

Best Practices

• Make the assigned agent field mandatory. Unassigned contacts are invisible to agents.
• Rotate reviews. Have an administrator audit unassigned records monthly.
• Don’t bypass the model. If a user asks for “admin just for one day”, rethink — the agent role should cover 99% of daily work.