Implementation guide for agents and clients

Overview

This guide covers how to create and manage agents and clients using the Repliers API. This will allow you to have a working agent and client set up, ready to use with saved searches, favorites, and messaging.

If you haven't read the article on how agents and clients work in Repliers, start with Agents and Clients in Repliers.

Step 1: Create an Agent

Every client must be assigned to an agent, so you'll need to create at least one agent first. The agent's name and contact details are used as the sender in all client communications.

POST /agents

{
  "fname": "Sarah",
  "lname": "Chen",
  "phone": "16471234567",
  "email": "sarah.chen@example-brokerage.com",
  "brokerage": "Example Realty Inc.",
  "designation": "Sales Representative"
}

The fields fname, lname, phone, email, brokerage, and designation are all required. The phone field must be 11 digits and start with the country code (e.g. 16471234567 for a Toronto number).

After the agent is created, note the agentId from the response — you'll need it in the next step.

You can optionally include:

avatar — a URL to a profile photo for the agent
location — a latitude and longitude for the agent's service area
externalId — an identifier from your CRM or external system for easy cross-referencing
status — defaults to true; set to false to disable the agent

Step 2: Create a Client

Once you have an agent, you can create clients and assign them to that agent.

POST /clients

{
  "agentId": 12345,
  "fname": "James",
  "lname": "Okafor",
  "email": "james.okafor@email.com",
  "phone": "14165550198",
  "preferences": {
    "email": true,
    "sms": false,
    "unsubscribe": false
  },
  "tags": ["buyer", "toronto", "condo"]
}

Replace 12345 with the agentId from Step 1. Note the clientId returned in the response — you'll use it when creating saved searches, favorites, and messages for this client.

The only required field is agentId. However, to use messaging features you'll also need to provide email (for email delivery) and/or phone (for SMS delivery).

Additional optional fields include:

tags — one or more strings to categorize the client, useful for filtering (e.g. ["buyer", "toronto"])
externalId — an identifier from your CRM or external system
status — defaults to true; set to false to suspend all activity for the client without deleting their data

Note: If you try to create a client with an email that already exists under the same agent, the API will return a 409 error. You can use GET /clients?email=... to check for an existing record first.

Step 3: Retrieve a Client

To look up a specific client, use their clientId:

GET /clients/{clientId}

To search across all your clients, use query parameters:

GET /clients?email=james.okafor@email.com

You can filter by fname, lname, email, phone, agentId, status, tags, and externalId. Two additional parameters control how filters are applied:

condition — use EXACT (default) for exact matches or CONTAINS for partial string matches
operator — use OR (default) to match any filter, or AND to require all filters to match

For example, to find clients whose first name contains "james":

GET /clients?fname=james&condition=CONTAINS

Results are paginated. Use pageNum and resultsPerPage (default: 100) to navigate large result sets. If you don't need saved search data in the response, set showSavedSearches=false for faster responses.

Step 4: Update a Client or Agent

Use a PATCH request to update any fields on an existing client or agent. You only need to include the fields you want to change.

To update a client's tags and reassign them to a different agent:

PATCH /clients/{clientId}

{
  "agentId": 67890,
  "tags": ["buyer", "north-york"]
}

To unsubscribe a client from all communications:

PATCH /clients/{clientId}

{
  "preferences": {
    "unsubscribe": true
  }
}

Transferring an Agent's Clients

If you need to move all clients from one agent to another — for example, when offboarding a team member — use the transfer endpoint:

POST /agents/{agentId}/transfer

{
  "newAgentId": 67890
}

Replace {agentId} with the source agent and 67890 with the destination agent. This transfers all clients at once.

Note: You must transfer or individually reassign all of an agent's clients before you can delete that agent.

Deleting an Agent or Client

DELETE /clients/{clientId}

DELETE /agents/{agentId}

If you want to temporarily disable a client without losing their saved searches and history, set status: false via a PATCH request instead of deleting the record.

Using Tags

Tags let you categorize clients for filtering and segmentation. You can assign multiple tags when creating or updating a client.

To get a list of all tags currently in use across your clients:

GET /clients/tags

To rename a tag globally (this updates it on every client that has it):

PATCH /clients/tags/{tag}

{
  "label": "north-york-toronto"
}

To filter clients by tag, pass a comma-separated list to GET /clients. This returns clients that have any of the specified tags:

GET /clients?tags=buyer,investor

Next Steps

Now that you have agents and clients set up, you can:

Create saved searches and assign them to clients
Add property favorites for clients
Send messages between agents and clients using the Messages API
Set up automated listing alerts and monthly property value updates

What questions does this article answer?

How do I create an agent using the Repliers API?
What fields are required when creating an agent or client?
How do I assign a client to an agent?
How do I search and filter clients?
How do I transfer all clients from one agent to another?
How do I delete an agent or client?
How do I use tags to organize clients?
What's the correct order of operations for setting up agents and clients?

Updated on: 02/04/2026

Was this article helpful?

Thank you!