Get contact | RealScout API documentation

Get contact Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://bump.sh/realscout/doc/realscout-api/mcp

Standard setup for AI tools providing an mcp.json file

{
  "RealScout API MCP server": {
    "url": "https://bump.sh/realscout/doc/realscout-api/mcp"
  }
}

GET /contacts/{id}

Bearer auth

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.

Requires the contacts:read scope. Rate budget: 300 calls per 1 minute per credential (the read class).

Path parameters

id string Required

The contact id.

Query parameters

window_days integer

Look-back window in days for the activity counts, 1 to 90.

Minimum value is 1, maximum value is 90. Default value is 30.

Responses

200 application/json

OK
Hide headers attributes Show headers attributes
- X-RateLimit-Limit integer
  
  Calls allowed in the current window.
- X-RateLimit-Remaining integer
  
  Calls left in the current window.
- X-RateLimit-Reset integer
  
  Epoch seconds at which the window resets.
Hide response attributes Show response attributes object
- id string Required
- first_name string | null Required
- last_name string | null Required
- email string Required
- primary_mobile_phone string | null Required
- lead_source string | null Required
- external_user_key string | null Required
- tags array[string] | null Required
- external_tags array[string] | null Required
- realscout_tags array[string] | null Required
- favorite boolean Required
- emailable boolean Required
- email_issue string | null Required
- status object Required
  
  Hide status attributes Show status attributes object
  
  value string | null Required
  
  Values are UNDESIGNATED, NURTURED, OVERAGE, ARCHIVED, or null.
  
  reasons array[string] | null Required
- auto_nurture object Required
  
  Hide auto_nurture attributes Show auto_nurture attributes object
  
  enabled boolean Required
  
  first_enabled_at string(date-time) | null Required
- created_at string(date-time) | null Required
- updated_at string(date-time) | null Required
- archived_at string(date-time) | null Required
- last_active_at string(date-time) | null Required
- last_login_at string(date-time) | null Required
- sign_up_source string | null Required
- primary_home_phone string | null Required
- primary_work_phone string | null Required
- additional_first_name string | null Required
- additional_last_name string | null Required
- additional_mobile_phone string | null Required
- additional_home_phone string | null Required
- additional_work_phone string | null Required
- additional_emails array[string] Required
- street string | null Required
- city string | null Required
- state string | null Required
- zipcode string | null Required
- contact_type string | null Required
  
  Values are BUYER, BUYER_SELLER, SELLER, OTHER, or null.
- price_status_alerts_enabled boolean Required
- exclusives_alerts_enabled boolean Required
- scout_score integer | null Required
- scout_score_change_7d integer | null Required
- scout_score_change_30d integer | null Required
- scout_score_calculated_on string(date) | null Required
- realscout_url string(uri) Required
- scout_score_summary_7d string | null Required
- scout_score_summary_30d string | null Required
- first_email_received_at string(date-time) | null Required
- alerts object Required
  
  Hide alerts attributes Show alerts attributes object
  
  listing_alerts object Required
  
  Hide listing_alerts attributes Show listing_alerts attributes object
  
  scheduled_count integer Required
  
  inactive_count integer Required
  
  last_sent_at string(date-time) | null Required
  
  market_alerts object Required
  
  Hide market_alerts attributes Show market_alerts attributes object
  
  scheduled_count integer Required
  
  inactive_count integer Required
  
  last_sent_at string(date-time) | null Required
  
  home_value_alerts object Required
  
  Hide home_value_alerts attributes Show home_value_alerts attributes object
  
  scheduled_count integer Required
  
  inactive_count integer Required
  
  last_sent_at string(date-time) | null Required
- activity object | null Required
  
  Hide activity attributes Show activity attributes object | null
  
  listing_views integer Required
  
  listing_saves integer Required
  
  open_house_views integer Required
  
  alert_opens integer Required
  
  alert_clicks integer Required
  
  emails_received integer Required
  
  home_value_views integer Required
  
  market_activity_views integer Required
- commutes object | null Required
  
  Hide commutes attribute Show commutes attribute object | null
  
  nodes array[object | null] | null Required
  
  Hide nodes attributes Show nodes attributes object | null
  
  address string | null Required
  
  type string | null Required
  
  lat number | null Required
  
  lng number | null Required
- feature_preferences array[object] | null Required
  
  Hide feature_preferences attributes Show feature_preferences attributes object
  
  name string | null Required
  
  sentiment string | null Required
  
  Values are like, dislike, neutral, or null.
- notes object | null Required
  
  Hide notes attribute Show notes attribute object | null
  
  nodes array[object | null] | null Required
  
  Hide nodes attributes Show nodes attributes object | null
  
  id string Required
  
  body string | null Required
  
  agent object | null Required
  
  Hide agent attribute Show agent attribute object | null
  
  full_name string | null Required
  
  created_at string(date-time) | null Required
  
  updated_at string(date-time) | null Required
- buying_timeline object | null Required
  
  Hide buying_timeline attributes Show buying_timeline attributes object | null
  
  key string Required
  
  label string Required
  
  updated_at string(date-time) Required
- selling_timeline object | null Required
  
  Hide selling_timeline attributes Show selling_timeline attributes object | null
  
  key string Required
  
  label string Required
  
  updated_at string(date-time) Required
- residence object | null Required
  
  Hide residence attributes Show residence attributes object | null
  
  own_rent string | null Required
  
  length_of_residence string | null Required
  
  last_confirmed_at string(date-time) | null Required
400 application/json

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.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
401 application/json

Invalid or missing bearer token.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
403 application/json

The credential was not granted the scope this call requires.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
404 application/json

Not found, or not yours: the two are indistinguishable on purpose.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
429 application/json

Rate limit exceeded; Retry-After says when to try again.
Hide headers attribute Show headers attribute
- Retry-After integer
  
  Seconds until the budget refills.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
500 application/json

Something went wrong on our side.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.

GET /contacts/{id}

curl -H "Authorization: Bearer rs_agent_..." "https://www.realscout.com/api/agent/v1/contacts/VXNlci0xMjM="

Response examples (200)

{
  "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"
  }
}

Response examples (400)

{
  "error": {
    "code": "invalid_request",
    "message": "window_days must be an integer.",
    "field": "window_days",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing credentials.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (403)

{
  "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"
  }
}

Response examples (404)

{
  "error": {
    "code": "not_found",
    "message": "No contact with id VXNlci0xMjM= for this agent.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (500)

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}