> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # 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](https://help.repliers.com/en/article/agents-and-clients-in-repliers-1cl1bav/). --- ## 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 ``` ```json { "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 ``` ```json { "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:** An agent and a client can not have the same email address. If you try to create an agent or a client and the email address is in use by another client or agent, the API will return a `409` error. You can use `GET /clients?email=...` / `GET /agents?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} ``` ```json { "agentId": 67890, "tags": ["buyer", "north-york"] } ``` To unsubscribe a client from all communications: ``` PATCH /clients/{clientId} ``` ```json { "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 ``` ```json { "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} ``` ```json { "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](https://help.repliers.com/en/article/how-to-send-your-first-message-using-repliers-f93kbg/) * 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?