Create 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

mcp.json 
{
  "RealScout API MCP server": {
    "url": "https://bump.sh/realscout/doc/realscout-api/mcp"
  }
}
Close
POST /contacts
Bearer auth

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.

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

application/json

Body Required

A CreateUserInput, as the agent app's own mutation takes it.

  • email string Required

    The contact's email address. Matching an existing live contact is refused; matching a deleted one revives them.

  • first_name string

    The first name of the contact.

  • last_name string

    The last name of the contact.

  • primary_mobile_phone string

    The primary mobile phone number for the contact.

  • primary_home_phone string

    The primary home phone number for the contact.

  • primary_work_phone string

    The primary work phone number for the contact.

  • additional_first_name string

    The first name of the contact's additional contact (usually a significant other).

  • additional_last_name string

    The last name of the contact's additional contact.

  • additional_mobile_phone string

    The mobile phone number of the contact's additional contact.

  • additional_home_phone string

    The home phone number of the contact's additional contact.

  • additional_work_phone string

    The work phone number of the contact's additional contact.

  • additional_emails array[string]

    The additional contact's email addresses, at most five.

  • street string

    The street the contact lives on.

  • city string

    The city the contact lives in.

  • state string

    The state the contact lives in.

  • zipcode string

    The zipcode the contact lives in.

  • lead_source string

    Where the contact came from, in your own words.

  • contact_type string

    What the contact is here to do.

    Values are BUYER, BUYER_SELLER, SELLER, or OTHER.

  • favorite boolean

    Whether the agent has favorited the contact.

  • price_status_alerts_enabled boolean

    Whether to send the contact price and status changes on the listings they are interested in.

  • exclusives_alerts_enabled boolean

    Whether to send the contact Exclusives You May Like alerts.

  • buyer_agreement_signed boolean

    Whether the contact has signed their buyer agreement.

  • listing_agreement_signed boolean

    Whether the contact has signed their listing agreement.

  • note string

    A note to file on the contact as it is created.

  • tags array[string]

    The agent's own tags for the contact. Never echo realscout_tags here.

  • external_user_key string

    Your own id for the contact. Not enforced unique, and never read by RealScout beyond the external_user_key filter.

Responses

  • 201 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 attribute Show response attribute object
    • contact object | null Required
      Hide contact attributes Show contact attributes object | null
      • 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
  • 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.
POST /contacts 
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
Request examples 
{
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "primary_mobile_phone": "string",
  "primary_home_phone": "string",
  "primary_work_phone": "string",
  "additional_first_name": "string",
  "additional_last_name": "string",
  "additional_mobile_phone": "string",
  "additional_home_phone": "string",
  "additional_work_phone": "string",
  "additional_emails": [
    "string"
  ],
  "street": "string",
  "city": "string",
  "state": "string",
  "zipcode": "string",
  "lead_source": "string",
  "contact_type": "BUYER",
  "favorite": true,
  "price_status_alerts_enabled": true,
  "exclusives_alerts_enabled": true,
  "buyer_agreement_signed": true,
  "listing_agreement_signed": true,
  "note": "string",
  "tags": [
    "string"
  ],
  "external_user_key": "string"
}
Response examples (201) 
{
  "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
  }
}
Response examples (400) 
{
  "error": {
    "code": "invalid_request",
    "message": "email is required.",
    "field": "email",
    "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:write scope, which this credential was not granted.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}
Response examples (404) 
{
  "error": {
    "code": "not_found",
    "message": "No endpoint at POST /api/agent/v1/contacts.",
    "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"
  }
}