Update contact | RealScout API documentation

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

PATCH /contacts/{id}

Bearer auth

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.

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

Path parameters

id string Required

The contact id.

application/json

Body Required

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

email string

The contact's email address.
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.

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

PATCH /contacts/{id}

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=

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
}

Response examples (200)

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

Response examples (400)

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

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