{ "openapi": "3.1.0", "info": { "title": "RealScout Agent API", "version": "1.0.0", "description": "Read and write an agent's contacts and their activity. Authenticate with a bearer token from the Integrations page; every call is scoped and rate limited per credential. Timestamps are ISO-8601 in UTC." }, "servers": [ { "url": "https://www.realscout.com/api/agent/v1" } ], "security": [ { "bearerAuth": [ ] } ], "tags": [ { "name": "Account" }, { "name": "Contacts" }, { "name": "Activity" }, { "name": "Conversations" }, { "name": "Listing Alerts" }, { "name": "Listing Links" }, { "name": "Search Links" }, { "name": "Market Alerts" }, { "name": "Home Value Alerts" } ], "x-topics": [ { "title": "Keeping your token safe", "content": "Your API token can do everything its scopes allow with your RealScout account: read your contacts, their activity and your conversations, and, with `contacts:write`, change them. Treat it like a password.\n\n## Never paste it into an AI chat\n\nDon't paste your token into Claude, ChatGPT or any other chat. The token is kept in the chat's history and can't be taken back out. Don't put it in an email, a shared doc, a support ticket or a screenshot either.\n\nIf a token ever ends up somewhere it shouldn't, revoke it on the API Tokens page and create a new one. Revoking takes effect immediately.\n\n## Store it in an environment variable\n\nAI coding tools such as Claude Code, Cursor and Codex can read your token from an environment variable named `REALSCOUT_API_TOKEN`, so you never have to type it into the tool.\n\n### Mac\n\n1. Open Terminal and run `open -e ~/.zshrc`. If it says the file doesn't exist, run `touch ~/.zshrc` first.\n2. Add this line, with your token in place of `your-token`:\n\n ```bash\n export REALSCOUT_API_TOKEN=\"your-token\"\n ```\n\n3. Save the file, then quit and reopen Terminal and your AI tool.\n4. To check it worked, run `[ -n \"$REALSCOUT_API_TOKEN\" ] && echo set`. It prints `set` without showing the token.\n\n### Windows\n\n1. Open the Start menu and search for **Edit environment variables for your account**.\n2. Under **User variables**, click **New...**.\n3. Enter `REALSCOUT_API_TOKEN` as the name and your token as the value, then click **OK**.\n4. Quit and reopen your AI tool.\n5. To check it worked, open PowerShell and run `if ($env:REALSCOUT_API_TOKEN) { 'set' }`.\n\n### Claude Code only\n\nClaude Code can also take the variable from its own settings file, so no other program sees it. Add this to `~/.claude/settings.json` (on Windows, `%USERPROFILE%\\.claude\\settings.json`):\n\n```json\n{ \"env\": { \"REALSCOUT_API_TOKEN\": \"your-token\" } }\n```\n\nEach of these stores the token as plain text that only your user account can read. That keeps it out of chats, but anything running as you can still read it.\n\n## Give each tool its own token\n\nCreate a separate token for each tool or script, and grant only the scopes it needs. A tool that only reads your contacts doesn't need `contacts:write`. Separate tokens mean you can revoke one without breaking the others, and every call is recorded against the token that made it." }, { "title": "Using RealScout with AI tools", "content": "## What works today\n\nThe API works with AI coding tools that run on your computer and can make web requests: **Claude Code**, **Cursor** and **Codex**. They read your token from the `REALSCOUT_API_TOKEN` environment variable (see *Keeping your token safe*) and call the API for you.\n\nThe API doesn't yet work with **Claude.ai** or **ChatGPT** chat. Those apps have no way to accept a token safely, and pasting it into the chat isn't safe.\n\n## Getting started\n\nCopy the starter prompt beside this guide into your AI tool. It tells the tool where this reference is, the base URL, and to read your token from `REALSCOUT_API_TOKEN`. Finish the last line with what you want, for example:\n\n- \"List my contacts with the highest Scout Score.\"\n- \"Which of my contacts were active this week?\"\n- \"Tag everyone who viewed a listing in Henderson with `Henderson`.\"\n\nYour tool should call `GET /me` first. That confirms the token works and shows which scopes it has.\n\n## Before you let a tool make changes\n\nA token with `contacts:write` lets the tool edit, tag and archive your contacts. Ask the tool to show you what it plans to change before it runs, and start with a read-only token until you trust the workflow.", "example": "```text\nI want to use the RealScout API to work with my own RealScout data.\n\nRead the API reference first: https://bump.sh/realscout/doc/realscout-api/llms.txt\n\n- Base URL: https://www.realscout.com/api/agent/v1\n- Authenticate with the header \"Authorization: Bearer \". My token is in the REALSCOUT_API_TOKEN environment variable. Read it from there; never print it, log it, or ask me to paste it.\n- Start by calling GET /me to confirm the token works and to see which scopes it has.\n\nThen help me with: \n```" }, { "title": "Limits, paging and errors", "content": "## Rate limits\n\nEach token gets a per-minute budget, by kind of call:\n\n- **Lists** (any endpoint that returns a page of rows): 60 calls a minute\n- **Single reads**: 300 calls a minute\n- **Writes**: 120 calls a minute\n\nYour account as a whole gets three times each budget across all its tokens. Creating more tokens doesn't raise the limit.\n\nGoing over returns `429` with a `Retry-After` header giving the number of seconds to wait. Wait that long before trying again; retrying right away won't help.\n\n## Paging\n\nList endpoints return 25 rows by default. Send `limit` for between 1 and 100. Each page carries `has_more` and `next_cursor`. To get the next page, send `next_cursor` back as `cursor` with the same filters. `next_cursor` is `null` on the last page.\n\n## Errors\n\nEvery error has the same body:\n\n```json\n{ \"code\": \"invalid_request\", \"message\": \"limit must be between 1 and 100.\", \"field\": \"limit\", \"request_id\": \"9b2f4c1e-...\" }\n```\n\n- **400 `invalid_request`**: something in the request is wrong. `field` names it when there's one to name. An unknown query parameter is refused too, so a typo doesn't get silently ignored.\n- **401 `unauthorized`**: the token is missing, wrong, revoked or expired.\n- **403 `missing_scope`**: the token works but wasn't granted the scope this call needs. Create a token with that scope.\n- **404 `not_found`**: there's no such record, or it belongs to another agent. The API doesn't tell these apart.\n- **429 `rate_limited`**: see *Rate limits*.\n- **500 `internal_error`**: something broke on our side.\n\nIf you contact support about a failed call, include its `request_id`. It's in every error body and in every response's `X-Request-Id` header, and it lets us find that exact call." }, { "title": "Building a contact sync", "content": "This guide covers keeping your CRM's contacts and your RealScout contacts in step: a first full import, then regular runs that pick up only what changed.\n\n## Before you start: check for a built-in integration\n\nRealScout already syncs natively with Follow Up Boss, Cloze, kvCORE, MoxiWorks and Rechat. If you use one of those, turn on that integration from the Integrations page instead of building your own.\n\nDon't run both against the same CRM. The two would be importing and updating the same contacts, so changes get applied twice or passed back and forth in a loop.\n\n## Using the API alongside a built-in integration\n\nYou can use the API and a built-in integration at the same time, as long as the API doesn't do the integration's job. Each contact has one owner, and that owner decides where the contact's details come from.\n\n- **Contacts the integration brought in belong to your CRM.** Each time your CRM sends an update, RealScout copies these fields from it, replacing what's in RealScout:\n - name, phones, street, city, state and zip\n - additional email, and lead source\n - email, for a contact who hasn't signed in yet\n\n Changes you make to these fields through the API aren't sent to your CRM, and they're replaced on the next update. Make those changes in your CRM. Use the API for what your CRM doesn't send: favorite, agreements, alert preferences, your own tags, archive and Auto Nurture.\n- **Contacts you create through the API belong to the API.** RealScout never sends them to your CRM. The integration also never takes them over, even if the same person (same email) is added to your CRM later.\n\nThat second rule is deliberate. The API is how you bring contacts into RealScout from systems you run yourself. If RealScout passed those contacts on to your CRM, a sync that reads from your CRM and writes to RealScout would send every contact straight back where it came from, as a duplicate or in a loop. If the integration could take over a contact your tool created, your CRM's next update would quietly undo your tool's edits. With one owner per contact, neither can happen.\n\nSo if a person belongs in your CRM, add them in your CRM and let the integration bring them into RealScout. Create a contact through the API only when your CRM isn't involved.\n\n## Keep a map of ids\n\nEvery RealScout contact has an `id`. Store it next to your CRM's id for the same person, and match on that pair from then on.\n\nDon't match on names. Email works for the first import (see below), but people change their email, and the pair of ids won't change.\n\nYou can also set `external_user_key` to your own id when you create a contact, and look a contact up with the `external_user_key` filter. Two limits: it can only be set at creation, so contacts created in RealScout never have one, and it isn't enforced unique. Treat it as a convenience, not your map.\n\n## The first run: pull everything\n\nPage through `GET /contacts` with `limit=100` until `next_cursor` is `null`. Store each contact's `id`, plus whatever fields you sync.\n\nTo match existing CRM records to these contacts, use email. A RealScout email is unique per agent, so `GET /contacts?email=...` returns at most one contact.\n\n## Later runs: only what changed\n\nUse `updated_after` to fetch only the contacts changed since your last run:\n\n1. **Note the time before you start**, not after you finish.\n2. Page through `GET /contacts?updated_after=&limit=100`.\n3. Apply each contact to your CRM, keyed by `id`.\n4. Save this run's start time for next time.\n\nUsing the start time means a contact changed while your run was going still gets picked up next time. Subtract a minute for clock drift. `updated_after` includes contacts changed at exactly that time, so you'll see a few contacts twice. That's harmless as long as applying a contact is safe to repeat.\n\nWhat updates a contact's `updated_at`: edits to its fields, archiving and unarchiving, Auto Nurture changes, and tags added or removed by the agent or through the API. RealScout's automatic tags (`realscout_tags`) and tags synced from another CRM (`external_tags`) don't update it.\n\n## Writing back to RealScout\n\n- **Creating:** `POST /contacts`. If a contact already has that email, you get `400 invalid_request` with `field: \"email\"`. Look the contact up by email and store its `id` instead of retrying. If the contact at that email was deleted, creating brings them back.\n- **Updating:** `PATCH /contacts/{id}`. Fields you leave out stay as they are, and a field sent as `null` is cleared. Send only the fields your CRM owns, so you don't wipe out what the agent entered in RealScout.\n- **Tags:** `POST /contacts/tags/add` and `/remove`. Each takes up to 100 contact ids at a time, and both are safe to repeat.\n\n## Archived and deleted contacts\n\nAn archived contact stays in the list with `status.value` set to `ARCHIVED`. Use `?status=ARCHIVED` to list only those. Archive and unarchive with `POST /contacts/archive` and `/unarchive`.\n\nA contact the agent deletes disappears from the list, and `updated_after` never reports the deletion. To find deletions, run a full sweep now and then, for example nightly or weekly. Collect every `id` from `GET /contacts` and compare against your map. An id missing from the sweep has been deleted in RealScout.\n\n## Avoiding a write loop\n\nIf your sync writes to RealScout and reads changes back, each write you make shows up in your next `updated_after` run. Before writing a contact back to your CRM, compare it with what you last sent. Only write fields that actually changed, so the two systems settle instead of passing the same contact back and forth.\n\n## Staying inside the limits\n\nA sync is mostly list calls: 60 a minute per token, 100 contacts per page. That's up to 6,000 contacts a minute. Make one token just for the sync, so it can't use up the budget your other tools need. When you get a `429`, wait the number of seconds in `Retry-After`. See *Limits, paging and errors*." } ], "paths": { "/contacts/tags/add": { "post": { "operationId": "add_contact_tags", "tags": [ "Contacts" ], "summary": "Add contact tags", "description": "Add up to 20 tags to up to 100 contacts. A tag a contact already has is left alone, so a retry is safe, and a name no contact has carried before becomes a new tag. contacts holds the agent's live contacts among the ids, with their tags after the call; any other id is left out and nothing about it changes.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead", "Buyer" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/tags/add.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A AddUserTagsInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddUserTagsInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\"],\"tags\":[\"Buyer\"]}' https://www.realscout.com/api/agent/v1/contacts/tags/add" } ] } }, "/contacts/archive": { "post": { "operationId": "archive_contacts", "tags": [ "Contacts" ], "summary": "Archive contacts", "description": "Archive up to 100 contacts. contacts holds the ones this call archived; an id already archived, or not one of the agent's live contacts, is left out and nothing about it changes, so a retry is safe.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "ARCHIVED", "reasons": null }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": "2026-08-19T02:11:00Z", "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/archive.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A ArchiveUsersInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveUsersInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\",\"VXNlci05OTk=\"]}' https://www.realscout.com/api/agent/v1/contacts/archive" } ] } }, "/contacts": { "post": { "operationId": "create_contact", "tags": [ "Contacts" ], "summary": "Create contact", "description": "Create a contact attached to the calling agent. The body is a CreateUserInput; any of its arguments may be sent. An email a live contact already has is refused on email; a contact deleted at that email comes back.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } }, "required": [ "contact" ] }, "example": { "contact": { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": null, "email": "nora@example.com", "primary_mobile_phone": null, "lead_source": null, "external_user_key": null, "tags": [ ], "external_tags": [ ], "realscout_tags": [ ], "favorite": false, "emailable": true, "email_issue": null, "status": { "value": "UNDESIGNATED", "reasons": null }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-20T14:05:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": null, "last_login_at": null, "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": null, "scout_score_change_7d": null, "scout_score_change_30d": null, "scout_score_calculated_on": null, "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": null, "scout_score_summary_30d": null } } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "email is required.", "field": "email", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A CreateUserInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"email\":\"nora@example.com\",\"first_name\":\"Nora\"}' https://www.realscout.com/api/agent/v1/contacts" } ] }, "get": { "operationId": "list_contacts", "tags": [ "Contacts" ], "summary": "List contacts", "description": "The calling agent's contacts, filterable and sortable, each row carrying its Scout Score and trend, with alert counts and activity counts on request.\n\nRequires the `contacts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Only contacts whose first or last name contains this substring (case-insensitive).", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Only the contact at exactly this address, ignoring case — the key create_contact matches on, so this is the one to ask \"do I already have them?\" with.", "schema": { "type": "string" } }, { "name": "external_user_key", "in": "query", "required": false, "description": "The caller's own id for the contact, exact match; not enforced unique, so a page may hold more than one match.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Only contacts carrying this tag (case-insensitive exact match).", "schema": { "type": "string" } }, { "name": "emailable", "in": "query", "required": false, "description": "Only contacts RealScout can (true) or cannot (false) email.", "schema": { "type": "boolean" } }, { "name": "status", "in": "query", "required": false, "description": "Only contacts with this status.", "schema": { "type": "string", "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED" ] } }, { "name": "created_after", "in": "query", "required": false, "description": "Only contacts created at or after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Only contacts created at or before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_after", "in": "query", "required": false, "description": "Only contacts changed at or after this ISO-8601 timestamp — the filter a CRM sync pages on.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_before", "in": "query", "required": false, "description": "Only contacts changed at or before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_active_after", "in": "query", "required": false, "description": "Only contacts last active at or after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_active_before", "in": "query", "required": false, "description": "Only contacts last active at or before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "group", "in": "query", "required": false, "description": "Restrict to one of the Dashboard highlight groupings: most_engaged, recently_reengaged, or slipping_away. Composes with every filter above, and implies scout_score ordering.", "schema": { "type": "string", "enum": [ "most_engaged", "recently_reengaged", "slipping_away" ] } }, { "name": "sort", "in": "query", "required": false, "description": "created_at (default), last_active_at, or scout_score; contacts with no value sort last.", "schema": { "type": "string", "enum": [ "created_at", "last_active_at", "scout_score" ], "default": "created_at" } }, { "name": "order", "in": "query", "required": false, "description": "DESC (default) or ASC.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" } }, { "name": "include", "in": "query", "required": false, "description": "Comma-separated: alerts adds alerts, a summary per alert family with how many are still scheduled to send and when that family last sent; activity adds activity, the window's action counts. Both are the same shape get_contact returns for the same names. The Scout Score and its trend are on every row and need no include.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "alerts", "activity" ] } }, "style": "form", "explode": false }, { "name": "window_days", "in": "query", "required": false, "description": "Look-back window in days for the activity counts and the group thresholds, 1 to 90.", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] }, "alerts": { "type": "object", "properties": { "listing_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] }, "market_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] }, "home_value_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] } }, "required": [ "listing_alerts", "market_alerts", "home_value_alerts" ], "description": "Present when include contains alerts." }, "activity": { "type": [ "object", "null" ], "properties": { "listing_views": { "type": "integer" }, "listing_saves": { "type": "integer" }, "open_house_views": { "type": "integer" }, "alert_opens": { "type": "integer" }, "alert_clicks": { "type": "integer" }, "emails_received": { "type": "integer" }, "home_value_views": { "type": "integer" }, "market_activity_views": { "type": "integer" } }, "required": [ "listing_views", "listing_saves", "open_house_views", "alert_opens", "alert_clicks", "emails_received", "home_value_views", "market_activity_views" ], "description": "Present when include contains activity." } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 62, "scout_score_change_7d": 21, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert.", "alerts": { "listing_alerts": { "scheduled_count": 3, "inactive_count": 0, "last_sent_at": "2026-08-18T13:00:00Z" }, "market_alerts": { "scheduled_count": 1, "inactive_count": 0, "last_sent_at": "2026-08-01T12:00:00Z" }, "home_value_alerts": { "scheduled_count": 0, "inactive_count": 1, "last_sent_at": "2026-07-30T00:00:00Z" } }, "activity": { "listing_views": 16, "listing_saves": 6, "open_house_views": 0, "alert_opens": 4, "alert_clicks": 0, "emails_received": 6, "home_value_views": 0, "market_activity_views": 0 } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "status must be one of: UNDESIGNATED, NURTURED, OVERAGE, ARCHIVED.", "field": "status", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/contacts.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/contacts?group=slipping_away&include=alerts,activity&limit=25\"" } ] } }, "/contacts/auto-nurture/disable": { "post": { "operationId": "disable_auto_nurture", "tags": [ "Contacts" ], "summary": "Disable auto nurture", "description": "Turn Auto Nurture off for up to 100 contacts. Each keeps its status, so a NURTURED contact stays NURTURED, and keeps auto_nurture.first_enabled_at. contacts holds the ones this call turned off; a contact already off, or not one of the agent's live contacts, is left out and nothing about it changes.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": "2026-08-01T17:00:00Z" }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/auto-nurture/disable.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A DisableUsersAutoNurtureInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableUsersAutoNurtureInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\",\"VXNlci05OTk=\"]}' https://www.realscout.com/api/agent/v1/contacts/auto-nurture/disable" } ] } }, "/contacts/auto-nurture/enable": { "post": { "operationId": "enable_auto_nurture", "tags": [ "Contacts" ], "summary": "Enable auto nurture", "description": "Turn Auto Nurture on for up to 100 contacts. Contacts the agent has no nurture seat left for stay off, so read auto_nurture.enabled on each contact rather than assuming it took. Refused only when the agent has no MLS access. contacts holds the ones this call acted on; a contact already on, or not one of the agent's live contacts, is left out and nothing about it changes.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": true, "first_enabled_at": "2026-08-19T02:11:00Z" }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/auto-nurture/enable.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A EnableUsersAutoNurtureInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableUsersAutoNurtureInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\",\"VXNlci05OTk=\"]}' https://www.realscout.com/api/agent/v1/contacts/auto-nurture/enable" } ] } }, "/contacts/{id}": { "get": { "operationId": "get_contact", "tags": [ "Contacts" ], "summary": "Get contact", "description": "The complete picture of one contact: details, tags, nurture, emailability and why, Scout Score and its trend, alert preferences, alert families, saved profile and activity counts.\n\nRequires the `contacts:read` scope. Rate budget: 300 calls per 1 minute per credential (the `read` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string" } }, { "name": "window_days", "in": "query", "required": false, "description": "Look-back window in days for the activity counts, 1 to 90.", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] }, "first_email_received_at": { "type": [ "string", "null" ], "format": "date-time" }, "alerts": { "type": "object", "properties": { "listing_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] }, "market_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] }, "home_value_alerts": { "type": "object", "properties": { "scheduled_count": { "type": "integer" }, "inactive_count": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "scheduled_count", "inactive_count", "last_sent_at" ] } }, "required": [ "listing_alerts", "market_alerts", "home_value_alerts" ] }, "activity": { "type": [ "object", "null" ], "properties": { "listing_views": { "type": "integer" }, "listing_saves": { "type": "integer" }, "open_house_views": { "type": "integer" }, "alert_opens": { "type": "integer" }, "alert_clicks": { "type": "integer" }, "emails_received": { "type": "integer" }, "home_value_views": { "type": "integer" }, "market_activity_views": { "type": "integer" } }, "required": [ "listing_views", "listing_saves", "open_house_views", "alert_opens", "alert_clicks", "emails_received", "home_value_views", "market_activity_views" ] }, "commutes": { "type": [ "object", "null" ], "properties": { "nodes": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "properties": { "address": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } }, "required": [ "address", "type", "lat", "lng" ] } } }, "required": [ "nodes" ] }, "feature_preferences": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ], "enum": [ "like", "dislike", "neutral", null ] } }, "required": [ "name", "sentiment" ] } }, "notes": { "type": [ "object", "null" ], "properties": { "nodes": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "agent": { "type": [ "object", "null" ], "properties": { "full_name": { "type": [ "string", "null" ] } }, "required": [ "full_name" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "body", "agent", "created_at", "updated_at" ] } } }, "required": [ "nodes" ] }, "buying_timeline": { "type": [ "object", "null" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "key", "label", "updated_at" ] }, "selling_timeline": { "type": [ "object", "null" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "key", "label", "updated_at" ] }, "residence": { "type": [ "object", "null" ], "properties": { "own_rent": { "type": [ "string", "null" ] }, "length_of_residence": { "type": [ "string", "null" ] }, "last_confirmed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "own_rent", "length_of_residence", "last_confirmed_at" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d", "first_email_received_at", "alerts", "activity", "commutes", "feature_preferences", "notes", "buying_timeline", "selling_timeline", "residence" ] }, "example": { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": false, "email_issue": "EMAIL_BOUNCED", "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert.", "first_email_received_at": "2026-08-02T17:05:00Z", "alerts": { "listing_alerts": { "scheduled_count": 3, "inactive_count": 0, "last_sent_at": "2026-08-18T13:00:00Z" }, "market_alerts": { "scheduled_count": 1, "inactive_count": 0, "last_sent_at": "2026-08-01T12:00:00Z" }, "home_value_alerts": { "scheduled_count": 0, "inactive_count": 1, "last_sent_at": "2026-07-30T00:00:00Z" } }, "activity": { "listing_views": 16, "listing_saves": 6, "open_house_views": 0, "alert_opens": 4, "alert_clicks": 0, "emails_received": 6, "home_value_views": 0, "market_activity_views": 0 }, "commutes": { "nodes": [ { "address": "500 Market St, San Francisco, CA", "type": "DRIVE", "lat": 37.7897, "lng": -122.4001 } ] }, "feature_preferences": [ { "name": "Pool", "sentiment": "like" } ], "notes": { "nodes": [ { "id": "Tm90ZS03NzA=", "body": "Wants to be in the school district.", "agent": { "full_name": "Dana Agent" }, "created_at": "2026-08-05T16:00:00Z", "updated_at": "2026-08-05T16:00:00Z" } ] }, "buying_timeline": { "key": "THREE_TO_SIX_MONTHS", "label": "3-6 months", "updated_at": "2026-08-04T18:00:00Z" }, "selling_timeline": null, "residence": { "own_rent": "Own", "length_of_residence": "7 years", "last_confirmed_at": "2026-07-30T00:00:00Z" } } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "window_days must be an integer.", "field": "window_days", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No contact with id VXNlci0xMjM= for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/contacts/VXNlci0xMjM=\"" } ] }, "patch": { "operationId": "update_contact", "tags": [ "Contacts" ], "summary": "Update contact", "description": "Update a contact. The body is an UpdateUserInput; any of its arguments may be sent. A field left out is untouched; one sent as null is cleared.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } }, "required": [ "contact" ] }, "example": { "contact": { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0111", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "contact_type must be one of: BUYER, BUYER_SELLER, SELLER, OTHER.", "field": "contact_type", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No contact with id VXNlci0xMjM= for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A UpdateUserInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X PATCH -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"primary_mobile_phone\":\"555-0111\"}' https://www.realscout.com/api/agent/v1/contacts/VXNlci0xMjM=" } ] } }, "/home-value-alerts/{id}": { "get": { "operationId": "get_home_value_alert", "tags": [ "Home Value Alerts" ], "summary": "Get home value alert", "description": "One home value alert: who it is for, the home it values, any valuation the agent gave, how often it sends, and whether it is paused.\n\nRequires the `home_value_alerts:read` scope. Rate budget: 300 calls per 1 minute per credential (the `read` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The home value alert id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "agent_valuation": { "type": [ "integer", "null" ] }, "agent_value_low": { "type": [ "integer", "null" ] }, "agent_value_high": { "type": [ "integer", "null" ] }, "agent_valuation_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "type": [ "string", "null" ] }, "disabled": { "type": [ "boolean", "null" ] }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "contact", "address", "city", "state", "zipcode", "agent_valuation", "agent_value_low", "agent_value_high", "agent_valuation_updated_at", "schedule", "disabled", "last_sent_at", "next_send_at", "created_at", "updated_at", "realscout_url" ] }, "example": { "id": "SG9tZVJlcG9ydC03ODk=", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "address": "456 Oak Ave", "city": "San Jose", "state": "CA", "zipcode": "95112", "agent_valuation": 1150000, "agent_value_low": 1100000, "agent_value_high": 1200000, "agent_valuation_updated_at": "2026-07-15T18:00:00Z", "schedule": "MONTHLY", "disabled": false, "last_sent_at": "2026-08-01T12:00:00Z", "next_send_at": "2026-09-01T12:00:00Z", "created_at": "2026-06-01T17:00:00Z", "updated_at": "2026-08-01T12:00:00Z", "realscout_url": "https://www.realscout.com/agent/users/123/home-reports/SG9tZVJlcG9ydC03ODk=" } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "unknown is not a field this endpoint takes.", "field": "unknown", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the home_value_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No home value alert with id SG9tZVJlcG9ydC03ODk= for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" https://www.realscout.com/api/agent/v1/home-value-alerts/SG9tZVJlcG9ydC03ODk=" } ] } }, "/listing-alerts/{id}": { "get": { "operationId": "get_listing_alert", "tags": [ "Listing Alerts" ], "summary": "Get listing alert", "description": "One listing alert: who it is for, its type, its email_settings (mode and schedule, with the settings of whichever mode it is in), its criteria as the sentence the agent app shows, and how many of its results sit in each of the agent app's tabs (unsent, sent, trashed).\n\nRequires the `listing_alerts:read` scope. Rate budget: 300 calls per 1 minute per credential (the `read` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The listing alert id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "search_type": { "type": [ "string", "null" ], "enum": [ "BASIC", "EXCLUSIVES", "ADVANCED", "AI", null ] }, "email_settings": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "automated", "handpicked", "disabled" ] }, "schedule": { "type": "string", "enum": [ "ASAP", "DAILY", "WEEKLY", "MONTHLY", "DISABLED" ] }, "automated_settings": { "type": [ "object", "null" ], "properties": { "day_schedule": { "type": [ "array", "null" ], "items": { "type": "string" } }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "send_to_agent": { "type": "boolean" }, "send_oh_reminder": { "type": "boolean" } }, "required": [ "day_schedule", "next_send_at", "send_to_agent", "send_oh_reminder" ] }, "handpicked_settings": { "type": [ "object", "null" ], "properties": { "needs_review": { "type": "boolean" }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "needs_review", "last_reviewed_at" ] } }, "required": [ "mode", "schedule", "automated_settings", "handpicked_settings" ] }, "last_ran_at": { "type": [ "string", "null" ], "format": "date-time" }, "sunset": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" }, "description": { "type": [ "string", "null" ] }, "criteria_summary": { "type": [ "string", "null" ] }, "results": { "type": [ "object", "null" ], "properties": { "unsent": { "type": "integer" }, "sent": { "type": "integer" }, "trashed": { "type": "integer" } }, "required": [ "unsent", "sent", "trashed" ] } }, "required": [ "id", "name", "contact", "search_type", "email_settings", "last_ran_at", "sunset", "source", "created_at", "updated_at", "realscout_url", "description", "criteria_summary", "results" ] }, "examples": { "automated": { "value": { "id": "U2F2ZWRTZWFyY2gtOTk=", "name": "Sunnyvale 3BR", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "automated", "schedule": "DAILY", "automated_settings": { "day_schedule": [ "0_AM", "1_AM", "2_AM", "3_AM", "4_AM", "5_AM", "6_AM" ], "next_send_at": "2026-09-02T03:00:00Z", "send_to_agent": false, "send_oh_reminder": true }, "handpicked_settings": null }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": false, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtOTk=", "description": "Basic Search", "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+", "results": { "unsent": 12, "sent": 48, "trashed": 3 } } }, "handpicked": { "value": { "id": "U2F2ZWRTZWFyY2gtMTAw", "name": "Palo Alto picks", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "handpicked", "schedule": "DAILY", "automated_settings": null, "handpicked_settings": { "needs_review": true, "last_reviewed_at": "2026-08-17T16:00:00Z" } }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": false, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAw", "description": "Basic Search", "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+", "results": { "unsent": 12, "sent": 48, "trashed": 3 } } }, "disabled": { "value": { "id": "U2F2ZWRTZWFyY2gtMTAx", "name": "Old Mountain View search", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "disabled", "schedule": "DISABLED", "automated_settings": null, "handpicked_settings": null }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": true, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAx", "description": "Basic Search", "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+", "results": { "unsent": 12, "sent": 48, "trashed": 3 } } } } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "unknown is not a field this endpoint takes.", "field": "unknown", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the listing_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No listing alert with id U2F2ZWRTZWFyY2gtOTk= for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" https://www.realscout.com/api/agent/v1/listing-alerts/U2F2ZWRTZWFyY2gtOTk=" } ] } }, "/market-alerts/{id}": { "get": { "operationId": "get_market_alert", "tags": [ "Market Alerts" ], "summary": "Get market alert", "description": "One market alert: who it is for, the area it covers, its price band and filters, how often it sends, and whether it is paused.\n\nRequires the `market_alerts:read` scope. Rate budget: 300 calls per 1 minute per credential (the `read` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The market alert id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "contact": { "type": "object", "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "schedule": { "type": "string", "enum": [ "BIWEEKLY", "MONTHLY", "QUARTERLY", "MANUAL" ] }, "disabled": { "type": "boolean" }, "queued": { "type": "boolean" }, "price_min": { "type": [ "integer", "null" ] }, "price_max": { "type": [ "integer", "null" ] }, "beds_min": { "type": [ "integer", "null" ] }, "beds_max": { "type": [ "integer", "null" ] }, "baths_min": { "type": [ "number", "null" ] }, "baths_max": { "type": [ "number", "null" ] }, "sqft_min": { "type": [ "integer", "null" ] }, "sqft_max": { "type": [ "integer", "null" ] }, "property_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "APARTMENT", "COMM", "LAL", "MF", "MOBILE", "OTHER", "SFR", "TC", "TOWNHOUSE", "CONDO", "COOP", "CONDOP" ] } }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "name", "contact", "schedule", "disabled", "queued", "price_min", "price_max", "beds_min", "beds_max", "baths_min", "baths_max", "sqft_min", "sqft_max", "property_types", "last_sent_at", "next_send_at", "created_at", "updated_at", "realscout_url" ] }, "example": { "id": "TWFya2V0QWxlcnQtNzc=", "name": "Palo Alto", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "schedule": "MONTHLY", "disabled": false, "queued": false, "price_min": 500000, "price_max": 900000, "beds_min": 3, "beds_max": null, "baths_min": null, "baths_max": null, "sqft_min": null, "sqft_max": null, "property_types": [ "SFR" ], "last_sent_at": "2026-08-01T12:00:00Z", "next_send_at": "2026-09-01T12:00:00Z", "created_at": "2026-06-01T17:00:00Z", "updated_at": "2026-08-01T12:00:00Z", "realscout_url": "https://www.realscout.com/agent/users/VXNlci0xMjM=/market-activity-alerts/TWFya2V0QWxlcnQtNzc=" } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "unknown is not a field this endpoint takes.", "field": "unknown", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the market_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No market alert with id TWFya2V0QWxlcnQtNzc= for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" https://www.realscout.com/api/agent/v1/market-alerts/TWFya2V0QWxlcnQtNzc=" } ] } }, "/me": { "get": { "operationId": "get_me", "tags": [ "Account" ], "summary": "Get me", "description": "The calling agent's account as the Account page shows it: profile, brokerage and licensing, web presence, MLS memberships, contact-book and nurture settings, and the scopes this credential carries.\n\nRequires the `account:read` scope. Rate budget: 300 calls per 1 minute per credential (the `read` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "secondary_email": { "type": [ "string", "null" ] }, "phone_number": { "type": [ "string", "null" ] }, "secondary_phone_number": { "type": [ "string", "null" ] }, "sms_phone_number": { "type": [ "string", "null" ] }, "photo_url": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "accepted_tos": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "brokerage_name": { "type": [ "string", "null" ] }, "enterprise_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "office_name": { "type": [ "string", "null" ] }, "office_address": { "type": [ "string", "null" ] }, "brokerage_license_number": { "type": [ "string", "null" ] }, "license": { "type": [ "string", "null" ] }, "licenses": { "type": [ "array", "null" ], "items": { "type": "string" } }, "team": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] } }, "required": [ "name" ] }, "subdomain": { "type": [ "string", "null" ] }, "search_page_url": { "type": [ "string", "null" ] }, "landing_page_url": { "type": [ "string", "null" ] }, "realscout_url": { "type": "string", "format": "uri" }, "website_link": { "type": [ "string", "null" ] }, "facebook_link": { "type": [ "string", "null" ] }, "instagram_link": { "type": [ "string", "null" ] }, "twitter_link": { "type": [ "string", "null" ] }, "yelp_link": { "type": [ "string", "null" ] }, "welcome_message": { "type": [ "string", "null" ] }, "mls_memberships": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "mls_name": { "type": "string" }, "display_name": { "type": "string" }, "status": { "type": "string", "enum": [ "APPROVED", "TEMPORARILY_APPROVED", "SUBMITTED", "SIGNATURES_NEEDED", "DISABLED", "REQUESTED", "PENDING_VERIFICATION", "ACCESS_REQUESTED_AWAITING_AGENT_INFO", "PENDING_AGREEMENT_INITIATION", "AGREEMENT_SENT_AWAITING_AGENT_SIGNATURE", "AGREEMENT_SENT_AWAITING_BROKER_SIGNATURE", "AGREEMENT_SIGNED_AWAITING_RS_PROCESSING" ] }, "has_access": { "type": "boolean" } }, "required": [ "mls_name", "display_name", "status", "has_access" ] } }, "auto_engage_new_clients": { "type": [ "boolean", "null" ] }, "auto_engagement_type": { "type": [ "string", "null" ], "enum": [ "all", "tagged", null ] }, "nurtured_client_count": { "type": [ "integer", "null" ] }, "nurtured_client_limit": { "type": [ "integer", "null" ] }, "nurtured_clients_amount_over_limit": { "type": [ "integer", "null" ] }, "cached_client_count": { "type": [ "integer", "null" ] }, "cached_archived_contact_count": { "type": [ "integer", "null" ] }, "default_cc_on_alerts": { "type": [ "boolean", "null" ] }, "daily_client_activity_notifications": { "type": [ "boolean", "null" ] }, "weekly_client_activity_notifications": { "type": [ "boolean", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "first_name", "last_name", "full_name", "email", "secondary_email", "phone_number", "secondary_phone_number", "sms_phone_number", "photo_url", "timezone", "accepted_tos", "created_at", "brokerage_name", "enterprise_name", "company_name", "office_name", "office_address", "brokerage_license_number", "license", "licenses", "team", "subdomain", "search_page_url", "landing_page_url", "realscout_url", "website_link", "facebook_link", "instagram_link", "twitter_link", "yelp_link", "welcome_message", "mls_memberships", "auto_engage_new_clients", "auto_engagement_type", "nurtured_client_count", "nurtured_client_limit", "nurtured_clients_amount_over_limit", "cached_client_count", "cached_archived_contact_count", "default_cc_on_alerts", "daily_client_activity_notifications", "weekly_client_activity_notifications", "scopes" ] }, "example": { "id": "QWdlbnQtNDI=", "first_name": "Dana", "last_name": "Agent", "full_name": "Dana Agent", "email": "dana@example.com", "secondary_email": null, "phone_number": "555-0100", "secondary_phone_number": null, "sms_phone_number": "555-0100", "photo_url": "https://cdn.realscout.com/agents/42/photo.jpg", "timezone": "America/Los_Angeles", "accepted_tos": true, "created_at": "2024-08-01T00:00:00Z", "brokerage_name": "Example Realty", "enterprise_name": "Example Realty Group", "company_name": "Example Realty", "office_name": "Sunnyvale", "office_address": "456 Market St, Sunnyvale, CA 94086", "brokerage_license_number": "01234567", "license": "DRE 02012345", "licenses": [ "DRE 02012345" ], "team": { "name": "Dana Agent Team" }, "subdomain": "danaagent", "search_page_url": "https://danaagent.realscout.com", "landing_page_url": "https://danaagent.realscout.me", "realscout_url": "https://www.realscout.com/agent/account/profile", "website_link": "https://danaagent.example.com", "facebook_link": null, "instagram_link": null, "twitter_link": null, "yelp_link": null, "welcome_message": "Welcome! Let me know how I can help.", "mls_memberships": [ { "mls_name": "MLSLISTINGS", "display_name": "MLSListings", "status": "APPROVED", "has_access": true } ], "auto_engage_new_clients": true, "auto_engagement_type": "all", "nurtured_client_count": 240, "nurtured_client_limit": 500, "nurtured_clients_amount_over_limit": 0, "cached_client_count": 312, "cached_archived_contact_count": 18, "default_cc_on_alerts": false, "daily_client_activity_notifications": true, "weekly_client_activity_notifications": true, "scopes": [ "account:read", "contacts:read" ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "unknown is not a field this endpoint takes.", "field": "unknown", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the account:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/me.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" https://www.realscout.com/api/agent/v1/me" } ] } }, "/activity": { "get": { "operationId": "list_contact_activity", "tags": [ "Activity" ], "summary": "List contact activity", "description": "What the calling agent's contacts have done, newest first: listing views, saves, ratings, comments, showing requests and report views, each with the contact and what it was about: a listing, home value report, market report or CMA, told apart by its `type`.\n\nRequires the `contacts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact's activity; omit for the whole book. An id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "actions", "in": "query", "required": false, "description": "Comma-separated action types (e.g. view,save); defaults to the full published set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "view", "save", "unsave", "hide", "unhide", "rated", "comment", "request_showing", "open_house_view", "home_report_view", "market_alert_view", "cma_view" ] }, "default": [ "view", "save", "unsave", "hide", "unhide", "rated", "comment", "request_showing", "open_house_view", "home_report_view", "market_alert_view", "cma_view" ] }, "style": "form", "explode": false }, { "name": "from", "in": "query", "required": false, "description": "Only activity at or after this ISO-8601 timestamp; defaults to one year ago.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "description": "Only activity at or before this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "rating": { "type": [ "integer", "null" ] }, "view_count": { "type": [ "integer", "null" ] }, "actionable": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/ActionableProperty" }, { "$ref": "#/components/schemas/ActionableHomeReport" }, { "$ref": "#/components/schemas/ActionableMarketAlert" }, { "$ref": "#/components/schemas/ActionableCmaReport" } ], "discriminator": { "propertyName": "type", "mapping": { "Property": "#/components/schemas/ActionableProperty", "HomeReport": "#/components/schemas/ActionableHomeReport", "MarketAlert": "#/components/schemas/ActionableMarketAlert", "CmaReport": "#/components/schemas/ActionableCmaReport" } } }, { "type": "null" } ] } }, "required": [ "id", "action", "created_at", "contact", "rating", "view_count", "actionable" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDE=", "action": "view", "created_at": "2026-08-19T02:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": 3, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDI=", "action": "save", "created_at": "2026-08-19T01:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDM=", "action": "unsave", "created_at": "2026-08-19T00:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDQ=", "action": "hide", "created_at": "2026-08-18T23:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDU=", "action": "unhide", "created_at": "2026-08-18T22:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDY=", "action": "rated", "created_at": "2026-08-18T21:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": 4, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDc=", "action": "comment", "created_at": "2026-08-18T20:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDg=", "action": "request_showing", "created_at": "2026-08-18T19:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMDk=", "action": "open_house_view", "created_at": "2026-08-18T18:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "Property", "id": "UHJvcGVydHktNDU2", "mls_number": "ML81234567", "address": "123 Main St", "city": "San Jose", "state": "CA", "zipcode": "95112", "price": 1250000, "status": "active", "beds": 3, "baths": 2.0, "realscout_url": "https://www.realscout.com/agent/ls/123-main-st-san-jose-ca-95112", "realscout_client_url": "https://danaagent.realscout.com/homesearch/listings/123-main-st-san-jose-ca-95112" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMTA=", "action": "home_report_view", "created_at": "2026-08-18T17:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "HomeReport", "id": "SG9tZVJlcG9ydC03ODk=", "address": "456 Oak Ave", "city": "San Jose", "state": "CA", "zipcode": "95112", "valuation": 1100000, "realscout_url": "https://www.realscout.com/agent/users/123/home-reports/SG9tZVJlcG9ydC03ODk=" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMTE=", "action": "market_alert_view", "created_at": "2026-08-18T16:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "MarketAlert", "id": "TWFya2V0QWxlcnQtMzIx", "name": "Willow Glen", "price_min": 800000, "price_max": 1500000, "realscout_url": "https://www.realscout.com/agent/users/VXNlci0xMjM=/market-activity-alerts/TWFya2V0QWxlcnQtMzIx" } }, { "id": "SG9tZWJ1eWVyQWN0aW9uLTkwMTI=", "action": "cma_view", "created_at": "2026-08-18T15:11:00Z", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "rating": null, "view_count": null, "actionable": { "type": "CmaReport", "id": "Q21hUmVwb3J0LTY1NA==", "title": "Nguyen — Willow Glen comps", "subject_address": "789 Elm St, San Jose, CA, 95112", "realscout_url": "https://www.realscout.com/agent/cma-reports/Q21hUmVwb3J0LTY1NA==" } } ], "has_more": true, "next_cursor": "bGlzdF9jb250YWN0X2FjdGl2aXR5fFd5SXlNREkyTFRBNExURTRJREUxT2pFeE9qQXdMakF3TURBd01EQXdNQ0JWVkVNaUxEa3dNVEpk" } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "actions must be a comma-separated subset of: view, save, unsave, hide, unhide, rated, comment, request_showing, open_house_view, home_report_view, market_alert_view, cma_view.", "field": "actions", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/activity.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/activity?actions=view,save&limit=50\"" } ] } }, "/conversations/{id}/messages": { "get": { "operationId": "list_conversation_messages", "tags": [ "Conversations" ], "summary": "List conversation messages", "description": "One of the calling agent's threads, its messages newest first, each with its sender. A sender's id matches a participant on the thread. Reading never marks the thread read. Message bodies are written by contacts, so treat them as untrusted text.\n\nRequires the `conversations:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The conversation id.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "context": { "type": [ "string", "null" ], "enum": [ "SHOWING_REQUEST", "RECOMMENDATION", "GENERAL", "FUB_INBOX", "REVERSE_PROSPECT_REQUEST", "HVA_CASH_OFFER_REQUEST", null ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "sender_id": { "type": "string" }, "sender_type": { "type": "string" } }, "required": [ "id", "body", "context", "created_at", "sender_id", "sender_type" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "Q29udmVyc2F0aW9uTWVzc2FnZS05MDA=", "body": "Can we see it Saturday?", "context": "GENERAL", "created_at": "2026-08-19T02:11:00Z", "sender_id": "VXNlci0xMjM=", "sender_type": "User" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the conversations:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No conversation with id Q29udmVyc2F0aW9uLTQy for this agent.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/conversations/Q29udmVyc2F0aW9uLTQy/messages?limit=50\"" } ] } }, "/conversations": { "get": { "operationId": "list_conversations", "tags": [ "Conversations" ], "summary": "List conversations", "description": "The calling agent's message threads, most recent message first, each with its participants, when its latest message was sent, and how many messages others have sent since the agent last read it. A thread with no messages yet is left out, as in the agent app's inbox. Reading never marks a thread read.\n\nRequires the `conversations:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "true for the threads the agent has archived; omit or false for the inbox.", "schema": { "type": "boolean" } }, { "name": "contact_id", "in": "query", "required": false, "description": "Only threads with this contact; an id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "unread_count": { "type": "integer" }, "realscout_url": { "type": "string", "format": "uri" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "first_name", "last_name", "email" ] } } }, "required": [ "id", "created_at", "last_message_at", "unread_count", "realscout_url", "participants" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "Q29udmVyc2F0aW9uLTQy", "created_at": "2026-08-06T07:06:40Z", "last_message_at": "2026-08-19T02:11:00Z", "unread_count": 2, "realscout_url": "https://www.realscout.com/agent/conversations/Q29udmVyc2F0aW9uLTQy", "participants": [ { "id": "QWdlbnQtNw==", "type": "Agent", "first_name": "Dana", "last_name": "Agent", "email": "dana@example.com" }, { "id": "VXNlci0xMjM=", "type": "User", "first_name": "Eleanor", "last_name": "Nguyen", "email": "eleanor@example.com" } ] } ], "has_more": true, "next_cursor": "bGlzdF9jb252ZXJzYXRpb25zfFd5SXlNREkyTFRBNExUSXlJREE1T2pBd09qQXdJaXcwTWwwPQ" } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the conversations:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/conversations.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/conversations?limit=25\"" } ] } }, "/home-value-alerts": { "get": { "operationId": "list_home_value_alerts", "tags": [ "Home Value Alerts" ], "summary": "List home value alerts", "description": "Home value alerts across the agent's contacts or for one contact, newest first, with the home each values, any valuation the agent gave, how often it sends, and whether it is paused. An archived contact's alerts are left out, as in the agent app.\n\nRequires the `home_value_alerts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact's alerts; omit for all of the agent's contacts. An id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "agent_valuation": { "type": [ "integer", "null" ] }, "agent_value_low": { "type": [ "integer", "null" ] }, "agent_value_high": { "type": [ "integer", "null" ] }, "agent_valuation_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "schedule": { "type": [ "string", "null" ] }, "disabled": { "type": [ "boolean", "null" ] }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "contact", "address", "city", "state", "zipcode", "agent_valuation", "agent_value_low", "agent_value_high", "agent_valuation_updated_at", "schedule", "disabled", "last_sent_at", "next_send_at", "created_at", "updated_at", "realscout_url" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "SG9tZVJlcG9ydC03ODk=", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "address": "456 Oak Ave", "city": "San Jose", "state": "CA", "zipcode": "95112", "agent_valuation": 1150000, "agent_value_low": 1100000, "agent_value_high": 1200000, "agent_valuation_updated_at": "2026-07-15T18:00:00Z", "schedule": "MONTHLY", "disabled": false, "last_sent_at": "2026-08-01T12:00:00Z", "next_send_at": "2026-09-01T12:00:00Z", "created_at": "2026-06-01T17:00:00Z", "updated_at": "2026-08-01T12:00:00Z", "realscout_url": "https://www.realscout.com/agent/users/123/home-reports/SG9tZVJlcG9ydC03ODk=" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the home_value_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/home-value-alerts.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/home-value-alerts?contact_id=VXNlci0xMjM=\"" } ] } }, "/listing-alert-templates": { "get": { "operationId": "list_listing_alert_templates", "tags": [ "Listing Alerts" ], "summary": "List listing alert templates", "description": "The calling agent's listing alert templates and the ones a manager has shared with them, newest first, each with its description, search type, MLS, schedule and tags.\n\nRequires the `listing_alerts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "search_type": { "type": [ "string", "null" ], "enum": [ "BASIC", "EXCLUSIVES", "ADVANCED", "AI", null ] }, "mls": { "type": [ "string", "null" ] }, "schedule": { "type": [ "string", "null" ], "enum": [ "ASAP", "DAILY", "NEVER", "MANUAL", "MANUAL_DAILY", "MONTHLY", "WEEKLY", null ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "owned": { "type": [ "boolean", "null" ] }, "auto_nurture_fallback": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "description", "search_type", "mls", "schedule", "tags", "owned", "auto_nurture_fallback", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "U2F2ZWRTZWFyY2hUZW1wbGF0ZS0xNw==", "name": "Sunnyvale 3BR Template", "description": "3+ beds in Sunnyvale under $1.5M", "search_type": "BASIC", "mls": "MLSListings", "schedule": "DAILY", "tags": [ "Buyer" ], "owned": true, "auto_nurture_fallback": false, "created_at": "2026-08-19T02:11:00Z", "updated_at": "2026-08-19T02:11:00Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the listing_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/listing-alert-templates.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/listing-alert-templates?limit=25\"" } ] } }, "/listing-alerts": { "get": { "operationId": "list_listing_alerts", "tags": [ "Listing Alerts" ], "summary": "List listing alerts", "description": "Listing alerts across the agent's contacts or for one contact, newest first, with type and email_settings (mode and schedule, with the settings of whichever mode it is in). An archived contact's alerts are left out, as in the agent app.\n\nRequires the `listing_alerts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact's alerts; omit for all of the agent's contacts. An id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Only alerts in this email_settings mode; omit for every mode.", "schema": { "type": "string", "enum": [ "automated", "handpicked", "disabled" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "search_type": { "type": [ "string", "null" ], "enum": [ "BASIC", "EXCLUSIVES", "ADVANCED", "AI", null ] }, "email_settings": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "automated", "handpicked", "disabled" ] }, "schedule": { "type": "string", "enum": [ "ASAP", "DAILY", "WEEKLY", "MONTHLY", "DISABLED" ] }, "automated_settings": { "type": [ "object", "null" ], "properties": { "day_schedule": { "type": [ "array", "null" ], "items": { "type": "string" } }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "send_to_agent": { "type": "boolean" }, "send_oh_reminder": { "type": "boolean" } }, "required": [ "day_schedule", "next_send_at", "send_to_agent", "send_oh_reminder" ] }, "handpicked_settings": { "type": [ "object", "null" ], "properties": { "needs_review": { "type": "boolean" }, "last_reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "needs_review", "last_reviewed_at" ] } }, "required": [ "mode", "schedule", "automated_settings", "handpicked_settings" ] }, "last_ran_at": { "type": [ "string", "null" ], "format": "date-time" }, "sunset": { "type": [ "boolean", "null" ] }, "source": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "name", "contact", "search_type", "email_settings", "last_ran_at", "sunset", "source", "created_at", "updated_at", "realscout_url" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "U2F2ZWRTZWFyY2gtOTk=", "name": "Sunnyvale 3BR", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "automated", "schedule": "DAILY", "automated_settings": { "day_schedule": [ "0_AM", "1_AM", "2_AM", "3_AM", "4_AM", "5_AM", "6_AM" ], "next_send_at": "2026-09-02T03:00:00Z", "send_to_agent": false, "send_oh_reminder": true }, "handpicked_settings": null }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": false, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtOTk=" }, { "id": "U2F2ZWRTZWFyY2gtMTAw", "name": "Palo Alto picks", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "handpicked", "schedule": "DAILY", "automated_settings": null, "handpicked_settings": { "needs_review": true, "last_reviewed_at": "2026-08-17T16:00:00Z" } }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": false, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAw" }, { "id": "U2F2ZWRTZWFyY2gtMTAx", "name": "Old Mountain View search", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "search_type": "BASIC", "email_settings": { "mode": "disabled", "schedule": "DISABLED", "automated_settings": null, "handpicked_settings": null }, "last_ran_at": "2026-08-18T13:00:00Z", "sunset": true, "source": null, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-18T13:00:00Z", "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAx" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "mode must be one of: automated, handpicked, disabled.", "field": "mode", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the listing_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/listing-alerts.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/listing-alerts?contact_id=VXNlci0xMjM=\"" } ] } }, "/listing-links": { "get": { "operationId": "list_listing_links", "tags": [ "Listing Links" ], "summary": "List listing links", "description": "The calling agent's shared listing links, newest first, each with its address, the contact it was shared with (none for a public link) and how many listings it holds.\n\nRequires the `listing_links:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Only links shared with this contact; an id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "public": { "type": [ "boolean", "null" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "listing_count": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "url", "public", "contact", "listing_count", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "UHJvcGVydHlMaXN0LTc4", "name": "3 listings Dana picked for you", "url": "https://dana.realscout.com/homesearch/property-lists/UHJvcGVydHlMaXN0LTc4", "public": false, "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "listing_count": 3, "created_at": "2026-08-19T02:11:00Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the listing_links:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/listing-links.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/listing-links?limit=25\"" } ] } }, "/market-alerts": { "get": { "operationId": "list_market_alerts", "tags": [ "Market Alerts" ], "summary": "List market alerts", "description": "Market alerts across the agent's contacts or for one contact, newest first, with the area each covers, its price band and filters, how often it sends, and whether it is paused. An archived contact's alerts are left out, as in the agent app.\n\nRequires the `market_alerts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "contact_id", "in": "query", "required": false, "description": "Only this contact's alerts; omit for all of the agent's contacts. An id that is none of the agent's contacts is an empty page.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "contact": { "type": "object", "properties": { "id": { "type": "string" }, "realscout_url": { "type": "string", "format": "uri" } }, "required": [ "id", "realscout_url" ] }, "schedule": { "type": "string", "enum": [ "BIWEEKLY", "MONTHLY", "QUARTERLY", "MANUAL" ] }, "disabled": { "type": "boolean" }, "queued": { "type": "boolean" }, "price_min": { "type": [ "integer", "null" ] }, "price_max": { "type": [ "integer", "null" ] }, "beds_min": { "type": [ "integer", "null" ] }, "beds_max": { "type": [ "integer", "null" ] }, "baths_min": { "type": [ "number", "null" ] }, "baths_max": { "type": [ "number", "null" ] }, "sqft_min": { "type": [ "integer", "null" ] }, "sqft_max": { "type": [ "integer", "null" ] }, "property_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "APARTMENT", "COMM", "LAL", "MF", "MOBILE", "OTHER", "SFR", "TC", "TOWNHOUSE", "CONDO", "COOP", "CONDOP" ] } }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "id", "name", "contact", "schedule", "disabled", "queued", "price_min", "price_max", "beds_min", "beds_max", "baths_min", "baths_max", "sqft_min", "sqft_max", "property_types", "last_sent_at", "next_send_at", "created_at", "updated_at", "realscout_url" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "TWFya2V0QWxlcnQtNzc=", "name": "Palo Alto", "contact": { "id": "VXNlci0xMjM=", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=" }, "schedule": "MONTHLY", "disabled": false, "queued": false, "price_min": 500000, "price_max": 900000, "beds_min": 3, "beds_max": null, "baths_min": null, "baths_max": null, "sqft_min": null, "sqft_max": null, "property_types": [ "SFR" ], "last_sent_at": "2026-08-01T12:00:00Z", "next_send_at": "2026-09-01T12:00:00Z", "created_at": "2026-06-01T17:00:00Z", "updated_at": "2026-08-01T12:00:00Z", "realscout_url": "https://www.realscout.com/agent/users/VXNlci0xMjM=/market-activity-alerts/TWFya2V0QWxlcnQtNzc=" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the market_alerts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/market-alerts.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/market-alerts?contact_id=VXNlci0xMjM=\"" } ] } }, "/search-links": { "get": { "operationId": "list_search_links", "tags": [ "Search Links" ], "summary": "List search links", "description": "The calling agent's search links, newest first, each with its sign-up address, its tracking parameters, the tags it gives whoever signs up, and how many have.\n\nRequires the `search_links:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "utm_campaign": { "type": [ "string", "null" ] }, "utm_source": { "type": [ "string", "null" ] }, "utm_medium": { "type": [ "string", "null" ] }, "utm_term": { "type": [ "string", "null" ] }, "utm_content": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "signup_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "url", "utm_campaign", "utm_source", "utm_medium", "utm_term", "utm_content", "tags", "signup_count", "created_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "id": "U2hhcmVhYmxlU2VhcmNoTGluay00Mg==", "name": "Willow Glen under $1.5M", "url": "https://dana.realscout.com/homesearch/shared-searches/U2hhcmVhYmxlU2VhcmNoTGluay00Mg==?utm_campaign=spring&utm_source=newsletter", "utm_campaign": "spring", "utm_source": "newsletter", "utm_medium": null, "utm_term": null, "utm_content": null, "tags": [ "Newsletter" ], "signup_count": 12, "created_at": "2026-08-19T02:11:00Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the search_links:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/search-links.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/search-links?limit=25\"" } ] } }, "/tags": { "get": { "operationId": "list_tags", "tags": [ "Contacts" ], "summary": "List tags", "description": "Every tag one of the calling agent's contacts carries, alphabetically, whether the agent, RealScout or an integration applied it. Each name works as the tag filter on the contact list.\n\nRequires the `contacts:read` scope. Rate budget: 60 calls per 1 minute per credential (the `list` class).", "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100.", "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } }, "required": [ "name" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Send as cursor for the next page; null on the last one." } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "data": [ { "name": "Hot Lead" }, { "name": "kvCore: Sphere" }, { "name": "RealScout Property Saved" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer.", "field": "limit", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:read scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at GET /api/agent/v1/tags.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -H \"Authorization: Bearer rs_agent_...\" \"https://www.realscout.com/api/agent/v1/tags?limit=100\"" } ] } }, "/contacts/tags/remove": { "post": { "operationId": "remove_contact_tags", "tags": [ "Contacts" ], "summary": "Remove contact tags", "description": "Remove up to 20 tags from up to 100 contacts. Names match exactly. Only a tag listed under a contact's tags is removed; one a CRM applied, listed under external_tags, stays. contacts holds the agent's live contacts among the ids, with their tags after the call; any other id is left out and nothing about it changes.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/tags/remove.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A RemoveUserTagsInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveUserTagsInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\"],\"tags\":[\"Hot Lead\"]}' https://www.realscout.com/api/agent/v1/contacts/tags/remove" } ] } }, "/contacts/unarchive": { "post": { "operationId": "unarchive_contacts", "tags": [ "Contacts" ], "summary": "Unarchive contacts", "description": "Restore up to 100 archived contacts. contacts holds the ones this call restored; whether each comes back UNDESIGNATED or NURTURED is up to the contact record, as in the agent app, so read status. An id not archived, or not one of the agent's live contacts, is left out and nothing about it changes.\n\nRequires the `contacts:write` scope. Rate budget: 120 calls per 1 minute per credential (the `write` class).", "parameters": [ ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Calls allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Calls left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds at which the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "primary_mobile_phone": { "type": [ "string", "null" ] }, "lead_source": { "type": [ "string", "null" ] }, "external_user_key": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "external_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "realscout_tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "favorite": { "type": "boolean" }, "emailable": { "type": "boolean" }, "email_issue": { "type": [ "string", "null" ] }, "status": { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "enum": [ "UNDESIGNATED", "NURTURED", "OVERAGE", "ARCHIVED", null ] }, "reasons": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "value", "reasons" ] }, "auto_nurture": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "first_enabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "enabled", "first_enabled_at" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time" }, "sign_up_source": { "type": [ "string", "null" ] }, "primary_home_phone": { "type": [ "string", "null" ] }, "primary_work_phone": { "type": [ "string", "null" ] }, "additional_first_name": { "type": [ "string", "null" ] }, "additional_last_name": { "type": [ "string", "null" ] }, "additional_mobile_phone": { "type": [ "string", "null" ] }, "additional_home_phone": { "type": [ "string", "null" ] }, "additional_work_phone": { "type": [ "string", "null" ] }, "additional_emails": { "type": "array", "items": { "type": "string" } }, "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "contact_type": { "type": [ "string", "null" ], "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER", null ] }, "price_status_alerts_enabled": { "type": "boolean" }, "exclusives_alerts_enabled": { "type": "boolean" }, "scout_score": { "type": [ "integer", "null" ] }, "scout_score_change_7d": { "type": [ "integer", "null" ] }, "scout_score_change_30d": { "type": [ "integer", "null" ] }, "scout_score_calculated_on": { "type": [ "string", "null" ], "format": "date" }, "realscout_url": { "type": "string", "format": "uri" }, "scout_score_summary_7d": { "type": [ "string", "null" ] }, "scout_score_summary_30d": { "type": [ "string", "null" ] } }, "required": [ "id", "first_name", "last_name", "email", "primary_mobile_phone", "lead_source", "external_user_key", "tags", "external_tags", "realscout_tags", "favorite", "emailable", "email_issue", "status", "auto_nurture", "created_at", "updated_at", "archived_at", "last_active_at", "last_login_at", "sign_up_source", "primary_home_phone", "primary_work_phone", "additional_first_name", "additional_last_name", "additional_mobile_phone", "additional_home_phone", "additional_work_phone", "additional_emails", "street", "city", "state", "zipcode", "contact_type", "price_status_alerts_enabled", "exclusives_alerts_enabled", "scout_score", "scout_score_change_7d", "scout_score_change_30d", "scout_score_calculated_on", "realscout_url", "scout_score_summary_7d", "scout_score_summary_30d" ] } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "id": "VXNlci0xMjM=", "first_name": "Nora", "last_name": "Nguyen", "email": "nora@example.com", "primary_mobile_phone": "555-0100", "lead_source": "Open House", "external_user_key": "crm-3187", "tags": [ "Hot Lead" ], "external_tags": [ "kvCore: Sphere" ], "realscout_tags": [ "Buyer" ], "favorite": true, "emailable": true, "email_issue": null, "status": { "value": "NURTURED", "reasons": [ "An active email alert" ] }, "auto_nurture": { "enabled": false, "first_enabled_at": null }, "created_at": "2026-08-01T17:00:00Z", "updated_at": "2026-08-20T09:30:00Z", "archived_at": null, "last_active_at": "2026-08-19T02:11:00Z", "last_login_at": "2026-08-18T19:40:00Z", "sign_up_source": "agent", "primary_home_phone": null, "primary_work_phone": null, "additional_first_name": "Sam", "additional_last_name": "Nguyen", "additional_mobile_phone": null, "additional_home_phone": null, "additional_work_phone": null, "additional_emails": [ "sam@example.com" ], "street": "123 Main St", "city": "Sunnyvale", "state": "CA", "zipcode": "94086", "contact_type": "BUYER", "price_status_alerts_enabled": true, "exclusives_alerts_enabled": true, "scout_score": 78, "scout_score_change_7d": 9, "scout_score_change_30d": 14, "scout_score_calculated_on": "2026-08-18", "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM=", "scout_score_summary_7d": "Viewing steadily and opening every alert.", "scout_score_summary_30d": "Viewing steadily and opening every alert." } ] } } } }, "400": { "description": "The request is invalid; `field` names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "ids is required.", "field": "ids", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "401": { "description": "Invalid or missing bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Invalid or missing credentials.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "403": { "description": "The credential was not granted the scope this call requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "missing_scope", "message": "This call requires the contacts:write scope, which this credential was not granted.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "404": { "description": "Not found, or not yours: the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No endpoint at POST /api/agent/v1/contacts/unarchive.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } }, "429": { "description": "Rate limit exceeded; `Retry-After` says when to try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 30 seconds.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } }, "headers": { "Retry-After": { "description": "Seconds until the budget refills.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Something went wrong on our side.", "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c" } } } } } }, "requestBody": { "required": true, "description": "A UnarchiveUsersInput, as the agent app's own mutation takes it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnarchiveUsersInput" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST -H \"Authorization: Bearer rs_agent_...\" -H \"Content-Type: application/json\" -d '{\"ids\":[\"VXNlci0xMjM=\",\"VXNlci05OTk=\"]}' https://www.realscout.com/api/agent/v1/contacts/unarchive" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send `Authorization: Bearer ` with a token issued on the Integrations page. The scopes it was granted decide which calls it may make." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "internal_error", "invalid_request", "missing_scope", "not_found", "rate_limited", "unauthorized" ] }, "message": { "type": "string" }, "field": { "type": "string", "description": "The offending input, when one input is to blame." }, "request_id": { "type": "string", "description": "Quote this when reporting a problem; it identifies the call in our logs." } } } } }, "AddUserTagsInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The tag names to add, at most 20. A name no contact has carried before becomes a new tag." } }, "required": [ "ids", "tags" ] }, "ArchiveUsersInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." } }, "required": [ "ids" ] }, "CreateUserInput": { "type": "object", "properties": { "email": { "type": "string", "description": "The contact's email address. Matching an existing live contact is refused; matching a deleted one revives them." }, "first_name": { "type": "string", "description": "The first name of the contact." }, "last_name": { "type": "string", "description": "The last name of the contact." }, "primary_mobile_phone": { "type": "string", "description": "The primary mobile phone number for the contact." }, "primary_home_phone": { "type": "string", "description": "The primary home phone number for the contact." }, "primary_work_phone": { "type": "string", "description": "The primary work phone number for the contact." }, "additional_first_name": { "type": "string", "description": "The first name of the contact's additional contact (usually a significant other)." }, "additional_last_name": { "type": "string", "description": "The last name of the contact's additional contact." }, "additional_mobile_phone": { "type": "string", "description": "The mobile phone number of the contact's additional contact." }, "additional_home_phone": { "type": "string", "description": "The home phone number of the contact's additional contact." }, "additional_work_phone": { "type": "string", "description": "The work phone number of the contact's additional contact." }, "additional_emails": { "type": "array", "items": { "type": "string" }, "description": "The additional contact's email addresses, at most five." }, "street": { "type": "string", "description": "The street the contact lives on." }, "city": { "type": "string", "description": "The city the contact lives in." }, "state": { "type": "string", "description": "The state the contact lives in." }, "zipcode": { "type": "string", "description": "The zipcode the contact lives in." }, "lead_source": { "type": "string", "description": "Where the contact came from, in your own words." }, "contact_type": { "type": "string", "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER" ], "description": "What the contact is here to do." }, "favorite": { "type": "boolean", "description": "Whether the agent has favorited the contact." }, "price_status_alerts_enabled": { "type": "boolean", "description": "Whether to send the contact price and status changes on the listings they are interested in." }, "exclusives_alerts_enabled": { "type": "boolean", "description": "Whether to send the contact Exclusives You May Like alerts." }, "buyer_agreement_signed": { "type": "boolean", "description": "Whether the contact has signed their buyer agreement." }, "listing_agreement_signed": { "type": "boolean", "description": "Whether the contact has signed their listing agreement." }, "note": { "type": "string", "description": "A note to file on the contact as it is created." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The agent's own tags for the contact. Never echo realscout_tags here." }, "external_user_key": { "type": "string", "description": "Your own id for the contact. Not enforced unique, and never read by RealScout beyond the external_user_key filter." } }, "required": [ "email" ] }, "DisableUsersAutoNurtureInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." } }, "required": [ "ids" ] }, "EnableUsersAutoNurtureInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." } }, "required": [ "ids" ] }, "ActionableProperty": { "title": "Property", "type": "object", "properties": { "type": { "type": "string", "const": "Property" }, "id": { "type": [ "string", "null" ] }, "mls_number": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "price": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "number", "null" ] }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" }, "realscout_client_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "type", "id", "mls_number", "address", "city", "state", "zipcode", "price", "status", "beds", "baths", "realscout_url", "realscout_client_url" ] }, "ActionableHomeReport": { "title": "HomeReport", "type": "object", "properties": { "type": { "type": "string", "const": "HomeReport" }, "id": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "valuation": { "type": [ "integer", "null" ] }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "type", "id", "address", "city", "state", "zipcode", "valuation", "realscout_url" ] }, "ActionableMarketAlert": { "title": "MarketAlert", "type": "object", "properties": { "type": { "type": "string", "const": "MarketAlert" }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "price_min": { "type": [ "integer", "null" ] }, "price_max": { "type": [ "integer", "null" ] }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "type", "id", "name", "price_min", "price_max", "realscout_url" ] }, "ActionableCmaReport": { "title": "CmaReport", "type": "object", "properties": { "type": { "type": "string", "const": "CmaReport" }, "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "subject_address": { "type": [ "string", "null" ] }, "realscout_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "type", "id", "title", "subject_address", "realscout_url" ] }, "RemoveUserTagsInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The tag names to remove, at most 20, matched exactly." } }, "required": [ "ids", "tags" ] }, "UnarchiveUsersInput": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The contact ids, at most 100." } }, "required": [ "ids" ] }, "UpdateUserInput": { "type": "object", "properties": { "email": { "type": "string", "description": "The contact's email address." }, "first_name": { "type": "string", "description": "The first name of the contact." }, "last_name": { "type": "string", "description": "The last name of the contact." }, "primary_mobile_phone": { "type": "string", "description": "The primary mobile phone number for the contact." }, "primary_home_phone": { "type": "string", "description": "The primary home phone number for the contact." }, "primary_work_phone": { "type": "string", "description": "The primary work phone number for the contact." }, "additional_first_name": { "type": "string", "description": "The first name of the contact's additional contact (usually a significant other)." }, "additional_last_name": { "type": "string", "description": "The last name of the contact's additional contact." }, "additional_mobile_phone": { "type": "string", "description": "The mobile phone number of the contact's additional contact." }, "additional_home_phone": { "type": "string", "description": "The home phone number of the contact's additional contact." }, "additional_work_phone": { "type": "string", "description": "The work phone number of the contact's additional contact." }, "additional_emails": { "type": "array", "items": { "type": "string" }, "description": "The additional contact's email addresses, at most five." }, "street": { "type": "string", "description": "The street the contact lives on." }, "city": { "type": "string", "description": "The city the contact lives in." }, "state": { "type": "string", "description": "The state the contact lives in." }, "zipcode": { "type": "string", "description": "The zipcode the contact lives in." }, "lead_source": { "type": "string", "description": "Where the contact came from, in your own words." }, "contact_type": { "type": "string", "enum": [ "BUYER", "BUYER_SELLER", "SELLER", "OTHER" ], "description": "What the contact is here to do." }, "favorite": { "type": "boolean", "description": "Whether the agent has favorited the contact." }, "price_status_alerts_enabled": { "type": "boolean", "description": "Whether to send the contact price and status changes on the listings they are interested in." }, "exclusives_alerts_enabled": { "type": "boolean", "description": "Whether to send the contact Exclusives You May Like alerts." }, "buyer_agreement_signed": { "type": "boolean", "description": "Whether the contact has signed their buyer agreement." }, "listing_agreement_signed": { "type": "boolean", "description": "Whether the contact has signed their listing agreement." } } } } } }