Search for contacts.
| Method | URI | Description |
|---|---|---|
| GET | /users/{user_id}/contacts |
Search user owned contacts |
{
"data": [
{
"id": 1,
"user_id": 1,
"first_name": "Gus",
"last_name": "Grasshopper",
"full_name": "Gus Grasshopper",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"email_status": "Valid",
"phone_status": "Valid",
"phone_subscribed": true,
"emails": [
{
"email": "[email protected]",
"type": "Work",
"status": "Valid"
}
],
"phones": [
{
"phone": "123-555-0100",
"type": "Mobile",
"status": "Valid"
}
],
"family_members": [
{
"relationship": "Spouse",
"first_name": "Gina",
"last_name": "Grasshopper",
"email": null,
"phone": null
}
],
"transaction_dates": [
{
"id": 1,
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701",
"created_at": "2025-05-02T14:00:00Z",
"updated_at": "2025-05-02T14:00:00Z"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
],
"created_at": "2020-04-09T16:34:59Z",
"updated_at": "2020-04-09T16:35:19Z",
"deleted_at": null
}
],
"links": {
"first": "http://api.happygrasshopper.com/v3/users/77179/contacts?page=1",
"last": "http://api.happygrasshopper.com/v3/users/77179/contacts?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "http://api.happygrasshopper.com/v3/users/77179/contacts",
"per_page": 15,
"to": 2,
"total": 2
}
}Create an contact.
| Method | URI | Description |
|---|---|---|
| POST | /users/{user_id}/contacts |
Create a user owned contact |
{
"first_name": "Gus",
"last_name": "Grasshopper",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"phone_subscribed": true,
"transaction_dates": [
{
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
]
}{
"id": 1,
"user_id": 1,
"first_name": "Gus",
"last_name": "Grasshopper",
"full_name": "Gus Grasshopper",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"email_status": "Valid",
"phone_status": "Valid",
"phone_subscribed": true,
"emails": [
{
"email": "[email protected]",
"type": "Work",
"status": "Valid"
}
],
"phones": [
{
"phone": "123-555-0100",
"type": "Mobile",
"status": "Valid"
}
],
"family_members": [
{
"relationship": "Spouse",
"first_name": "Gina",
"last_name": "Grasshopper",
"email": null,
"phone": null
}
],
"transaction_dates": [
{
"id": 1,
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701",
"created_at": "2025-05-02T14:00:00Z",
"updated_at": "2025-05-02T14:00:00Z"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
],
"created_at": "2020-04-09T16:34:59Z",
"updated_at": "2020-04-09T16:35:19Z",
"deleted_at": null
}Retrieve an contact.
| Method | URI | Description |
|---|---|---|
| GET | /contacts/{contact_id} |
Retrieve an contact by it's id |
{
"id": 1,
"user_id": 1,
"first_name": "Gus",
"last_name": "Grasshopper",
"full_name": "Gus Grasshopper",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"email_status": "Valid",
"phone_status": "Valid",
"phone_subscribed": true,
"emails": [
{
"email": "[email protected]",
"type": "Work",
"status": "Valid"
}
],
"phones": [
{
"phone": "123-555-0100",
"type": "Mobile",
"status": "Valid"
}
],
"family_members": [
{
"relationship": "Spouse",
"first_name": "Gina",
"last_name": "Grasshopper",
"email": null,
"phone": null
}
],
"transaction_dates": [
{
"id": 1,
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701",
"created_at": "2025-05-02T14:00:00Z",
"updated_at": "2025-05-02T14:00:00Z"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
],
"created_at": "2020-04-09T16:34:59Z",
"updated_at": "2020-04-09T16:35:19Z",
"deleted_at": null
}Update an contact.
| Method | URI | Description |
|---|---|---|
| PUT | /contacts/{contact_id} |
Update an contact |
{
"first_name": "Gus",
"last_name": "Grasshopper",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"phone_subscribed": true,
"transaction_dates": [
{
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
]
}{
"id": 1,
"user_id": 1,
"first_name": "Gus",
"last_name": "Grasshopper",
"full_name": "Gus Grasshopper",
"nickname": "Gus",
"company_name": "Grasshopper Realty",
"title": "Broker",
"email": "[email protected]",
"phone": "123-456-7890",
"dob": "1990-01-01",
"gender": "Male",
"audience": "Sphere",
"is_audience_locked": true,
"source": "List Upload",
"status": "Subscribed",
"email_status": "Valid",
"phone_status": "Valid",
"phone_subscribed": true,
"emails": [
{
"email": "[email protected]",
"type": "Work",
"status": "Valid"
}
],
"phones": [
{
"phone": "123-555-0100",
"type": "Mobile",
"status": "Valid"
}
],
"family_members": [
{
"relationship": "Spouse",
"first_name": "Gina",
"last_name": "Grasshopper",
"email": null,
"phone": null
}
],
"transaction_dates": [
{
"id": 1,
"date": "2025-05-01",
"type": "Sold",
"price": 450000,
"currency": "USD",
"representing_side": "Seller",
"property_address": "1 Main St, Springfield, IL 62701",
"created_at": "2025-05-02T14:00:00Z",
"updated_at": "2025-05-02T14:00:00Z"
}
],
"tags": [
"Tag 1",
"Tag 2"
],
"team_tags": [
"Tag 1",
"Tag 2"
],
"created_at": "2020-04-09T16:34:59Z",
"updated_at": "2020-04-09T16:35:19Z",
"deleted_at": null
}Delete an contact.
| Method | URI | Description |
|---|---|---|
| DELETE | /contacts/{contact_id} |
Delete an contact by it's id |
{
"success": true
}All of these are optional. A request that doesn't send them behaves exactly as before, and a key you leave out is never changed.
| Field | In requests | In responses | Notes |
|---|---|---|---|
nickname, company_name, title |
Create, Update | Yes | Strings, max 255. Send null or an empty string to clear. |
phone_subscribed |
Create, Update | Yes | Boolean. Whether the contact accepts texts and voicemails. |
email_status |
No | Yes | Deliverability of the primary email: Valid, Invalid Email, Hard Bounced, Spam Report, Soft Bounced. Set by HappyGrasshopper. |
phone_status |
No | Yes | Validity of the primary phone: Valid, Invalid, Unreachable. Set by HappyGrasshopper. |
emails, phones |
No | Yes | The contact's additional (non-primary) emails and phones, each with type and status. The primary stays in email / phone. |
family_members |
No | Yes | relationship (Spouse, Partner, Child, Parent, Sibling, Other), name, email and phone. |
transaction_dates[].price |
Create, Update | Yes | Whole currency units; decimals are rounded. |
transaction_dates[].currency |
Create, Update | Yes | 3-letter code. Defaults from the account's country (USD, or CAD in Canada) when a price is sent without one. |
transaction_dates[].representing_side |
Create, Update | Yes | Buyer, Seller, Both or Unknown. |
transaction_dates[].property_address |
Create, Update | Yes | A single-line address. |
status is unchanged. It still returns one value that combines subscription and email deliverability (for example Hard Bounced), and writing it works as before. email_status, phone_status and phone_subscribed show the same information split by channel.
Transactions are matched by date and type, as before: sending an existing date and type updates that transaction's price, currency, side or property address. A field you leave out (or send as null) keeps its stored value.