Query parameters

• name string

  Only contacts whose first or last name contains this substring (case-insensitive).

• email string

  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.

• external_user_key string

  The caller's own id for the contact, exact match; not enforced unique, so a page may hold more than one match.

• tag string

  Only contacts carrying this tag (case-insensitive exact match).

• emailable boolean

  Only contacts RealScout can (true) or cannot (false) email.

• status string

  Only contacts with this status.

  Values are UNDESIGNATED, NURTURED, OVERAGE, or ARCHIVED.

• created_after string(date-time)

  Only contacts created at or after this ISO-8601 timestamp.

• created_before string(date-time)

  Only contacts created at or before this ISO-8601 timestamp.

• updated_after string(date-time)

  Only contacts changed at or after this ISO-8601 timestamp — the filter a CRM sync pages on.

• updated_before string(date-time)

  Only contacts changed at or before this ISO-8601 timestamp.

• last_active_after string(date-time)

  Only contacts last active at or after this ISO-8601 timestamp.

• last_active_before string(date-time)

  Only contacts last active at or before this ISO-8601 timestamp.

• group string

  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.

  Values are most_engaged, recently_reengaged, or slipping_away.

• sort string

  created_at (default), last_active_at, or scout_score; contacts with no value sort last.

  Values are created_at, last_active_at, or scout_score. Default value is created_at.

• order string

  DESC (default) or ASC.

  Values are ASC or DESC. Default value is DESC.

• include array[string]

  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.

  Values are alerts or activity.

• window_days integer

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

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

• cursor string

  Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.

• limit integer

  Page size, 1 to 100.

  Minimum value is 1, maximum value is 100. Default value is 25.

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

  • data array[object] Required
    Hide data attributes Show data 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
    • alerts object

      Present when include contains alerts.

      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

      Present when include contains activity.

      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
  • has_more boolean Required
  • next_cursor string | null Required

    Send as cursor for the next page; null on the last one.

• 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.