# Create contact

**POST /contacts**

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


## Servers
- https://www.realscout.com/api/agent/v1: https://www.realscout.com/api/agent/v1 ()


## Authentication methods
- Bearer auth


## Parameters



### Body: application/json (object)
A CreateUserInput, as the agent app's own mutation takes it.
- **email** (string)
  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.

- **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
OK
#### Headers

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


#### Body: application/json (object)
- **contact** (object | null)


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

#### Body: application/json (object)
- **error** (object)


### 401
Invalid or missing bearer token.

#### Body: application/json (object)
- **error** (object)


### 403
The credential was not granted the scope this call requires.

#### Body: application/json (object)
- **error** (object)


### 404
Not found, or not yours: the two are indistinguishable on purpose.

#### Body: application/json (object)
- **error** (object)


### 429
Rate limit exceeded; `Retry-After` says when to try again.
#### Headers

- **Retry-After** (integer)
  Seconds until the budget refills.


#### Body: application/json (object)
- **error** (object)


### 500
Something went wrong on our side.

#### Body: application/json (object)
- **error** (object)



[Powered by Bump.sh](https://bump.sh)