JSON API Introduction
Caring.com provides a JSON API over HTTPS. Examples are provided for shell assuming basic usage of Curl. Other language exmaples can be provided if requested.
You can report API bugs with github issues
Authentication
Requests require an API key that you can obtain by contacting us at engineering AT caring.com
Authentication header example:
curl "https://dir.caring.com/api/v2/example.json" -H "Caring-Partner: TOKEN_VALUE"
Make sure to replace
TOKEN_VALUEwith your API key.
Caring.com Directory expects for the API key to be included as a header in all API requests and for the requests to be made over HTTPS.
Request Header: Caring-Partner: TOKEN_VALUE
Testing Sandbox
For testing and debugging, we maintain a fully featured testing sandbox. To use the sandbox replace the hostname dir.caring.com with sandbox-dir.caring.com.
Example request to the Sandbox environment:
curl "https://sandbox-dir.caring.com/api/v2/example.json" -H "Caring-Partner: TOKEN_VALUE"
Error Codes
The Caring.com JSON API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is malformed. |
| 401 | Unauthorized -- Your API key is wrong, or you're trying to be sneaky. |
| 404 | Not Found -- not found. |
| 406 | Not Acceptable -- You requested a format that we don't support. |
| 422 | Unprocessable Entity -- There was an validation error in your request. See the returned error messages. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Resources
A resource is a care provider. To create leads within the Caring.com APIs you will need to know the resource ID.
Querying the collection
GET https://dir.caring.com/api/v2/resources.json
curl "https://dir.caring.com/api/v2/resources.json" \
-H "Caring-Partner: TOKEN_VALUE"
The above command returns a paginated JSON response like this:
{
"results": [
{
"id": 551,
"address": {
"address_line1": "2280 North Highway 29",
"address_line2": "",
"city": "Newnan",
"county": "Coweta County",
"state": "GA",
"zip_code": "30265",
"latitude": 33.4931,
"longitude": -84.6741
},
"care_type": "retirement_community",
"caring_url": "https://www.caring.com/senior-living/georgia/newnan/wesley-woods-of-newnan",
"chain": "Wesley Woods Senior Living, Inc.",
"description": "Refund Plans: 90% of Entrance Fee; Traditional (Price: 66% (Avg.) of Entrance Fee). Assisted Living and Nursing Care on Fee-For-Service basis.",
"name": "Wesley Woods of Newnan",
"photos": [
"https://d13iq96prksfh0.cloudfront.net/cdn/photos/218935/original.jpeg",
"https://d13iq96prksfh0.cloudfront.net/cdn/photos/217572/original.png",
"https://d13iq96prksfh0.cloudfront.net/cdn/photos/217573/original.png",
"https://d13iq96prksfh0.cloudfront.net/cdn/photos/217574/original.png",
"https://d13iq96prksfh0.cloudfront.net/cdn/photos/217575/original.png"
],
"thumbnail": "https://d13iq96prksfh0.cloudfront.net/cdn/photos/218935/150x150%23.jpeg",
"national_aggregator": false,
"enhanced": true,
"pets_allowed": "",
"no_self_qualified": true,
"special_comment_extra": "Experience the best of both worlds, small and large. Wesley Woods is a warm and friendly community located in Newnan, a charming historic town that boasts all of the modern conveniences and is just a short drive from Atlanta with its metropolitan perks and world-class airport. Click here for directions to Wesley Woods of Newnan.",
"resident_capacity": 162,
"local_resource_types": ["continuing_care_retirement_communities"],
"homecare_pulse_awards": "",
"dma_region_code": 524,
"features": {
"alzheimers_care": false,
"diet": [],
"languages": []
},
"data_version": "69341935f928bf66fb339197103b371c"
}
],
"page": 1,
"page_size": 50,
"next_page": 2,
"prev_page": null,
"total_entries": 14572,
"total_pages": 292,
"next": "https://dir.caring.com/api/v2/resources.json?page=2&page_size=50",
"prev": null
}
Request Parameters (all optional)
| Name | Description |
|---|---|
| local_resource_type_id | The ID of the resource type to filter by (e.g. 6, for assisted living) |
| zip_code | The zipcode to filter by (e.g. 94131) |
| amenities | A list of amenities to filter by, in the form amenities=computer_room=true,low_fat=true |
| state_code | State code to filter by state_code=CA |
| page | The page to return (e.g. 2) |
Response Attributes
| Name | Description |
|---|---|
| results | A JSON array of resources |
| page | The current page number of the collection |
| page_size | The number of results on the page |
| next_page | The next page number of the collection |
| prev_page | The previous page number of the collection |
| total_entries | The total number of results across all pages |
| total_pages | The total number of pages that make up the collection |
| next | The URL to the next page of results |
| prev | The URL to the previous page of results |
Querying a particular resource
GET https://dir.caring.com/api/v2/resources/12341234.json
(replace 12341234 with the ID of the resource you wish to query)
Leads
A lead is the record for tracking customer interest for a resosource in the Caring.com catalog. For tracking we allow an affiliate_lead_id parameter to be passed so you can conveneiently use your internal record IDs to lookup a lead record or provide a status updates.
Creating a Lead
HTTP Request
POST https://dir.caring.com/api/v2/leads.json
curl "https://dir.caring.com/api/v2/leads.json" \
-H "Caring-Partner: TOKEN_VALUE" \
-d '{
"provider_id": "CARING_PROVIDER_ID",
"affiliate_lead_id": "ID_OF_THE_LEAD_IN_YOUR_SYSTEM",
"email_address": "caring-lead@example.com",
"browser": "Some User-Agent string",
"care_location": "90210",
"first_name": "Max",
"last_name": "Powers",
"relationship_name": "spouse",
"phone_number": "3335551212",
"tour_time": "09:00 03/13/2019",
"type_of_care": "alzheimers_care_facilities",
"phone_qualified": "no",
"utm_source": "bamedical",
"utm_campaign": "b2b+marketing",
"ip_address": "0.0.0.0"
}'
Request Attributes
| Name | Required | Data Type | Description |
|---|---|---|---|
| affiliate_campaign | String | Opaque string for the affiliate to use to store their campaign name. Max length of 255 characters. | |
| affiliate_lead_id | String | The ID of the lead your system if you want to continue to use that ID to track updates on the API. Max length of 255 characters. | |
| affiliate_notes | String | Free form text from the affiliate. Max length of 1024 characters. | |
| alternate_call_time | Time of Day | The preferred time to call the alternate phone. | |
| alternate_payment_method | Payment Method | A second way for the caregiver to pay for the care. | |
| alternate_phone_number | Phone Number | A second phone number. | |
| browser | ✓ | String | The user-agent string of the caregiver's browser. Max length of 255 characters. |
| campaign_url | String | The URL that the caregiver entered on. Caring.com may access this URL for quality assurance purposes. Max length of 255 characters. | |
| care_location | String | The City and State (formatted as "City, State") or Zipcode where care is desired. For home-care services, a zip code is preferred over a city. Caring.com will validate that this is a valid US region. | |
| email_address | ✓ | Email Address | The email address of the caregiver. In addition to being well-formed, Email addresses are validated using a 3rd party data verification service. |
| first_name | ✓ | String | The first name of the caregiver. Max length of 255 characters. |
| relationship_name | ✓ (*) | String | The relationship of the caregiver to the care recipient. Allowed Values: spouse, son, son_in_law, daughter, daughter_in_law, granddaughter, grandson, sister, brother, friend, myself, patient_client, job, other_relative, unknown. |
| ip_address | ✓ | IP Address | The IP Address of the caregiver. |
| last_name | ✓ | String | The last name of the caregiver. Max length of 255 characters. |
| living_situation | Living Situation | The current living situation of the care recipient. | |
| max_budget | Integer | The maximum amount the caregiver can afford in US dollars/month. | |
| min_budget | Integer | The least amount the caregiver is expecting to pay in US dollars/month. | |
| notes | String | Free form text from the caregiver. Max length of 1024 characters. | |
| payment_method | Payment Method | How will the caregiver pay for the care. | |
| phone_number | ✓ | Phone Number | The primary phone number for contacting the caregiver. |
| phone_qualified | ✓ | Affirmation | Whether the affiliate has qualified the caregiver by phone. |
| preferred_call_time | Time of Day | The preferred time to call the primary phone. | |
| provider_id | ✓ | String | The ID of the provider for which this lead is being submitted. |
| source_channel | Traffic Channel | The traffic source used to acquire the lead. | |
| tour_time | Appointment | The date and time when the caregiver will tour the provider. | |
| type_of_care | ✓ | Care Type | What kind of care is being sought. Allowed Values: alzheimers_care_facilities, assisted_living_facilities, continuing_care_retirement_communities, geriatric_care_managers, home_healthcare_agencies, homecare_agencies, hospices, independent_living, nursing_homes. |
| utm_source | String | Inbound tracking params for things like GA. | |
| utm_campaign | String | Inbound tracking params for things like GA. |
A successful response will respond with
HTTP 200 OKand JSON like this:
{
"result": {
"id": 7558089,
"tour_time": "09:00 03/13/2019",
"affiliate_campaign": null,
"affiliate_lead_id": "ID_OF_THE_LEAD_IN_YOUR_SYSTEM",
"affiliate_notes": null,
"alternate_call_time": null,
"alternate_payment_method": null,
"alternate_phone_number": null,
"browser": "Some User-Agent string",
"campaign_url": null,
"care_location": "90210",
"email_address": "caring-lead@example.com",
"first_name": "Max",
"inquiry_for": "Spouse",
"ip_address": "0.0.0.0",
"last_name": "Powers",
"living_situation": null,
"max_budget": 0,
"min_budget": 0,
"notes": null,
"payment_method": null,
"phone_number": "(333) 555-1212",
"phone_qualified": "no",
"preferred_call_time": null,
"price": null,
"provider_id": 115,
"source_channel": null,
"care_level": null
}
}
Errors will respond with
HTTP 400 Bad Requestand contain JSON formatted error messages:
{
"error_code": 400,
"error_message": "Validation Failed",
"errors": [
{
"field": "ip_address",
"message": "ip_address is required."
},
{
"field": "phone_qualified",
"message": "phone_qualified is required."
},
{
"field": "phone_qualified",
"message": "phone_qualified must be 'yes' or 'no'."
},
{
"field": "provider_id",
"message": "provider_id with ID CARING_PROVIDER_ID does not exist."
}
]
}
HTTP Response Statuses
| Status | Description |
|---|---|
| 200 | Success |
| 400 | Validation Failed |
| 401 | Unauthorized |
Lead Statuses
A Lead Status is a record for tracking the progress of a lead. We're interested in as much detail as you can provide. See See Allowed Statuses below to map your CRM statuses and Events on to Caring.com Lead Statuses.
Creating a Lead Status
HTTP Request
POST https://dir.caring.com/api/v2/lead-status.json
curl "https://dir.caring.com/api/v2/lead-status.json" \
-H "Caring-Partner: TOKEN_VALUE" \
-d '{
"lead_id": "1234",
"status": "valid_lead",
"sub_status": "timeframe_30",
"notes": "After speaking with the customer, they will likely be moving within 30 days."
}'
Request Attributes
| Parameter | Type | Description |
|---|---|---|
| lead_id | String | The id returned of the lead created on the API |
| affiliate_lead_id | String | The id of the lead in your system. If you passed us this field on creation, you may use this param in place of lead_id for sending statuses. Normally, prefer lead_id |
| status | String | One of the allowed lead statuses. See Allowed Statuses |
| sub_status | String | A more granular reason for the lead status. See Allowed Statuses |
| tour_time | DateTime String | An Hour of Day and a Date separated by a space. Ex: 07:00 01/31/2019, 13:00 12/25/2019 |
| notes | String | A string providing extra information about a lead. Limit 2,000 characters. |
A successful response will respond with an
HTTP 200 OKand JSON like this:
{
"lead_id": 1234,
"source": "affiliate",
"status": "valid_lead",
"sub_status": "timeframe_30",
"notes": "After speaking with the customer, they will likely be moving within 30 days.",
"tour_date": null,
"tour_time": "",
"tour_completed_at": null,
"moved_in_at": null,
"created_at": "2019-02-28T17:07:09.000-08:00",
"processed": false,
"created_by": ""
}
Error responses will contain JSON formatted error messages:
{
"error_code": 400,
"error_message": "Validation Failed",
"errors": [
{
"field": "status",
"message": "status \"valid_leads\" is not a legal status. Must be one of valid_lead, accepted, changed_community, closed, community_not_appropriate, dummy_closed, email_only, inactive, interested_later, invalid_lead, memo, move_in_commitment, move_in_canceled, moved_in, moved_in_elsewhere, moved_in_elsewhere_commitment, moved_in_regulatory_exception, moved_out, mystery_shopper, no_interest_community, not_qualified, owner_changed, provider_qualified, reported_moved_in, reported_wait_list, tour_cancelled, tour_completed, tour_confirmed, tour_scheduled, tour_rescheduling, wait_list, reserved, receiving_care, pending, sold, credited_move_in, lead_received, lead_not_received"
}
]
}
Allowed Status and Sub-Status
The following is a complete set of status and sub_status pairs that we allow to be sent for updates.
| Status | Sub Status |
|---|---|
| valid_lead | timeframe_30 |
| valid_lead | timeframe_90 |
| valid_lead | timeframe_gt_90 |
| closed | required_care_unavailable |
| closed | received_lead_previously |
| closed | deceased |
| invalid_lead | unable_to_contact |
| invalid_lead | deceased |
| invalid_lead | bad_contact_information |
| move_in_commitment | N/A |
| not_qualified | too_young |
| owner_changed | N/A |
| tour_completed | N/A |
| tour_confirmed | N/A |
| tour_scheduled | N/A |
| tour_rescheduling | N/A |
| wait_list | N/A |
| closed | too_independent |
| closed | too_much_care |
| closed | too_young |
| closed | budget_too_low |
HTTP Response Statuses
| Status | Description |
|---|---|
| 200 | Success |
| 400 | Validation Failed |
| 401 | Unauthorized |
Inquiries
An Inquiry is basically a lead without a provider_id. For a list of parameters See Creating a Lead
Creating an Inquiry
HTTP Request
POST https://dir.caring.com/api/v2/inquiries.json
curl "https://dir.caring.com/api/v2/inquiries.json" \
-H "Caring-Partner: TOKEN_VALUE" \
-d '{
"affiliate_lead_id": "ID_OF_THE_LEAD_IN_YOUR_SYSTEM",
"email_address": "caring-lead@example.com",
"browser": "Some User-Agent string",
"care_location": "90210",
"first_name": "Max",
"last_name": "Powers",
"relationship_name": "spouse",
"phone_number": "3335551212",
"tour_time": "09:00 03/13/2019",
"type_of_care": "alzheimers_care_facilities",
"phone_qualified": "no",
"utm_source": "bamedical",
"utm_campaign": "b2b+marketing",
"ip_address": "0.0.0.0"
}'
Reviews
Querying reviews
curl "https://dir.caring.com/api/v2/reviews.jsonapi?filter[resource_id]=1229142" \
-H "Caring-Partner: TOKEN_VALUE"
The above command returns JSON API response structured like this:
{
"data": [
{
"id": "1148701",
"type": "local_reviews",
"attributes": {
"resource_id": 1229142,
"resource_url": "http://www.caring.com/local/memory-care-facilities-in-dallas-texas/villages-of-lake-highlands",
"resource_name": "Villages of Lake Highlands",
"title": "I am a friend or relative of a current/past resident",
"content": "This is a really good review",
"rating": 5,
"staff_score": 4,
"activities_score": 3,
"food_score": 2,
"facilities_score": 1,
"value_score": 0,
"provider_response": "Thank you for your wonderful review",
"moderation_status": "approved",
"moderated_at": "2017-07-20T14:42:44.000-07:00",
"author": {
"name": "Satisfied Reviewer",
"email": "8225995e75243d26@example.com",
"url": "https://www.example.com/people/satisfied-reviewer"
},
"origin_url": "https://www.caring.com/local/memory-care-facilities-in-dallas-texas/villages-of-lake-highlands#reviews",
"created_at": "2017-07-17T10:35:15.000-07:00",
"updated_at": "2017-07-21T19:23:11.000-07:00"
}
}
],
"links": {
"self": "https://dir.caring.com/api/v2/reviews.jsonapi?page%5Bnumber%5D=1&page%5Bsize%5D=1",
"next": "https://dir.caring.com/api/v2/reviews.jsonapi?page%5Bnumber%5D=2&page%5Bsize%5D=1",
"last": "https://dir.caring.com/api/v2/reviews.jsonapi?page%5Bnumber%5D=1799&page%5Bsize%5D=1"
}
}
This endpoint retrieves a paginated list of reviews ordered by last_modified by default.
To stay up to date, we recommend that you periodically check the reviews collection ordered by last_modified so you can efficently get the updates you need as moderation statuses or review content changes.
Filter Parameters
To filter the collection you can use any of the following parameters in the filter parameter.
GET https://dir.caring.com/api/v2/reviews.jsonapi?filter[resource_id]=1229142&filter[moderation_status]=approved
| Parameter | Type | Description |
|---|---|---|
| resource_id | List of comma separated resource IDs | ID of the reviewed resource. Ex: filter[resource_id]=1234,5678 for multiple resources or filter[resource_id]=1234 for single one. |
| property_id | List of comma separated property IDs | ID of the property that connects multiple resource type. Ex: filter[property_id]=1234,5678 for multiple properties or filter[property_id]=1234 for single one. |
| resource_url | Url | The caring.com url of the reviewed resource. |
| resource_name | String | The name of the reviewed resource. |
| chain_name | String | The name of the chain owning the reviewed resource. |
| author_name | String | The screen name of the author of the review. |
| author_email | Email Address | The email address of the user posting the review. |
| author_url | Url | A personal url to the author of the review. |
| moderation_status | Enum('approved', 'rejected', 'further_review', 'spam') | The moderation status of the review. |
| sort | String | A sort clause made up of a field and direction Ex: filter[sort]=id+asc filters ids ascending. |
Pagination Parameters
GET https://dir.caring.com/api/v2/reviews.jsonapi?page[number]=1&page[size]=50
| Parameter | Type | Description |
|---|---|---|
| number | Integer | The page number. |
| size | Integer | The number of items per requested page. |
Review Data Attributes
| Attribute | Type | Description |
|---|---|---|
| resource_id | Integer | The primary key ID of the service provider that was reviewed |
| resource_url | Url | The public URL of the service provider that was reviewed. |
| resource_name | String | The Name of the service provider that was reviewed |
| author | Object | name, email and url fields for the Author of the review. |
| title | String | The headline of the review, typically a description of the reviewers relation to the service provider provider. |
| content | Text | The full text of the review. |
| origin_url | Url | A url to the site the review was created on. |
| moderation_webhook_url | Url | A URL where you can receive moderation status updates as a webhook. |
| rating | 1-5 | Overall Raring. |
| staff_score | 1-5 | Staff Rating. |
| activities_score | 1-5 | Rating of Leisure Activities. |
| food_score | 1-5 | Rating of the food available. |
| facilities_score | 1-5 | Rating of the facility quality and cleanliness. |
| value_score | 1-5 | Rating of the value. |
| provider_response | Text | A response to the review from the service provider. |
| moderated_at | Timestamp | The timestamp of when the review was moderated. |
| created_at | Timestamp | The timestamp of the review creation |
| updated_at | Timestamp | The timestamp of the last time the review was modified. |
Get a single Review
curl "https://dir.caring.com/api/v2/reviews/2.jsonapi" \
-H "Caring-Partner: TOKEN_VALUE"
The above command returns JSON structured like this:
{
"data": {
"id": "1132501",
"type": "local_reviews",
"attributes": {
"resource_id": 1225974,
"resource_url": "http://www.caring.com/local/assisted-living-facilities-in-salisbury-maryland/lakeside-assisted-living-salisbury",
"resource_name": "Lakeside Assisted Living",
"title": "I visited this facility",
"content": "Lakeside Assisted Living was nice, and I enjoyed the tour we had. The food was excellent, and the dining area was very clean and very appeasing to the eye. The staff was very nice, very informative, and met us as soon as we walked in. They had a beauty and barber shop.",
"rating": 4,
"staff_score": 5,
"activities_score": 0,
"food_score": 4,
"facilities_score": 5,
"value_score": 0,
"provider_response": "Thank you for your wonderful review Daniel! You are welcome anytime. We strive to provide quality of life here at Lakeside.",
"moderation_status": "approved",
"moderated_at": "2017-07-20T14:42:44.000-07:00",
"author": {
"name": "Daniel",
"email": "b7da7994a7a270ac@example.com",
"url": null
},
"origin_url": "https://www.seniorhomes.com/f/md/lakeside-assisted-living-salisbury#reviews",
"created_at": "2017-07-17T10:35:15.000-07:00",
"updated_at": "2017-07-21T19:23:11.000-07:00"
}
}
}
This endpoint retrieves a single review.
HTTP Request
GET https://dir.caring.com/api/v2/reviews/:id.jsonapi
URL Parameters
| Parameter | Description |
|---|---|
| :id | The id of the review to retrieve |
Creating a Review
HTTP Request
POST https://dir.caring.com/api/v2/reviews.jsonapi
curl "https://dir.caring.com/api/v2/reviews.jsonapi" \
-H "Caring-Partner: TOKEN_VALUE" \
-d '{
"data": {
"attributes": {
"resource_id": 1225974,
"title": "I visited this facility",
"content": "The facility was new and in good repair. The staff was warm and friendly.",
"rating": 5,
"staff_score": 5,
"activities_score": 5,
"food_score": 4,
"facilities_score": 5,
"value_score": 5,
"origin_url": "https://www.partner-site.com/assisted-living-in-california/nice-provider#reviews",
"author": {
"name": "SatisfiedReviewer11",
"email": "SatisfiedReviewer11@example.com",
"url": "https://www.twitter.com/SatisfiedReviewer11"
}
}
}
}'
A successful response will respond with JSON like this:
{
"data": {
"id": "1148702",
"type": "local_reviews",
"attributes": {
"resource_id": 1225974,
"property_id": 123,
"resource_url": "http://www.caring.test/local/assisted-living-facilities-in-salisbury-maryland/lakeside-assisted-living-salisbury",
"resource_name": "Lakeside Assisted Living",
"title": "I visited this facility",
"content": "The facility was new and in good repair. The staff was warm and friendly.",
"rating": 5,
"staff_score": 5,
"activities_score": 5,
"food_score": 4,
"facilities_score": 5,
"value_score": 5,
"provider_response": null,
"moderation_status": "unmoderated",
"moderated_at": null,
"author": {
"name": "SatisfiedReviewer11",
"email": "SatisfiedReviewer11@example.com",
"url": "https://www.twitter.com/SatisfiedReviewer11"
},
"origin_url": "https://www.partner-site.com/assisted-living-in-california/nice-provider#reviews",
"created_at": "2017-07-28T14:34:47.259-07:00",
"updated_at": "2017-07-28T14:34:47.259-07:00"
}
}
}
Error responses will contain JSON API formatted error messages:
{
"errors": [
{
"source": {
"pointer": "/data/attributes/content"
},
"detail": "can't be blank"
}
]
}
Review Data Attributes
| Attribute | Type | Description |
|---|---|---|
| resource_id | Integer | The primary key ID of the service provider that was reviewed |
| property_id | Integer | ID of the property that connects multiple resource type |
| resource_url | Url | The public URL of the service provider that was reviewed. |
| resource_name | String | The Name of the service provider that was reviewed |
| author | Object | name, email and url fields for the Author of the review. |
| title | String | The headline of the review, typically a description of the reviewers relation to the service provider provider. |
| content | Text | The full text of the review. |
| origin_url | Url | A url to the site the review was created on. |
| moderation_webhook_url | Url | A URL where you can receive moderation status updates as a webhook. |
| rating | 1-5 | Overall Raring. |
| staff_score | 1-5 | Staff Rating. |
| activities_score | 1-5 | Rating of Leisure Activities. |
| food_score | 1-5 | Rating of the food available. |
| facilities_score | 1-5 | Rating of the facility quality and cleanliness. |
| value_score | 1-5 | Rating of the value. |
HTTP Response Statuses
| Status | Description |
|---|---|
| 201 | Created |
| 422 | Unprocessable Entity |
Creating a Response to a Review
HTTP Request
POST https://dir.caring.com/api/v2/reviews/:id/responses.jsonapi
curl "https://dir.caring.com/api/v2/reviews/2/responses.jsonapi" \
-H "Caring-Partner: TOKEN_VALUE" \
-d '{
"data": {
"attributes": {
public_response: "Thanks for the positive review.",
"author": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"title": "Community Manager"
}
}
}
}'
Request Attributes
| Parameter | Type | Description |
|---|---|---|
| public_response | Text | The body of the response to the review. |
| author_name | String | Name of the Author of the Review Response. |
| author_title | String | Job title of the person responding to the review. |
| author_email | String | Email address of the Author of the Review Response. |
| author | Object | Convenient assignment of name ,title and email fields for the Author of the review. |
A successful response will respond with
HTTP 201 Createdand JSON like this:
{
"data": {
"id": "1",
"type": "provider_review_responses",
"attributes": {
"local_review_id": 2,
"author": {
"title": "Community Manager",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
"public_response": "Thank you for your honesty, we'll work to address those issues.",
"status": "pending",
"created_at": "2017-07-31T20:58:33.849-07:00",
"updated_at": "2017-07-31T20:58:33.849-07:00"
}
}
}
Errors will respond with
HTTP 422 Unprocessable Entityand contain JSON API formatted error messages:
{
"errors": [
{
"source": {
"pointer": "/data/attributes/author_title"
},
"detail": "can't be blank"
}
]
}
Querying a Response by Review
curl "https://dir.caring.com/api/v2/reviews/2/responses.jsonapi" \
-H "Caring-Partner: TOKEN_VALUE"
The above command returns JSON structured like this:
{
"data": {
"id": "2000",
"type": "provider_review_responses",
"attributes": {
"local_review_id": 2,
"author": {
"title": "Community Manager",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
"public_response": "Thanks for the positive review.",
"status": "pending",
"created_at": "2021-10-08T14:56:45.000-07:00",
"updated_at": "2021-10-08T14:56:45.000-07:00"
}
}
}
This endpoint retrieves a single response to a review.
HTTP Request
GET https://dir.caring.com/api/v2/reviews/:id/responses.jsonapi
URL Parameters
| Parameter | Description |
|---|---|
| :id | The id of the review whose response is to be retrieved |
Querying a Response to a Review
curl "https://dir.caring.com/api/v2/provider_review_responses/2000.jsonapi" \
-H "Caring-Partner: TOKEN_VALUE"
The above command returns JSON structured like this:
{
"data": {
"id": "2000",
"type": "provider_review_responses",
"attributes": {
"local_review_id": 2,
"author": {
"title": "Community Manager",
"name": "Jane Doe",
"email": "jane.doe@example.com"
},
"public_response": "Thanks for the positive review.",
"status": "pending",
"created_at": "2021-10-08T14:56:45.000-07:00",
"updated_at": "2021-10-08T14:56:45.000-07:00"
}
}
}
This endpoint retrieves a single response to a review.
HTTP Request
GET https://dir.caring.com/api/v2/provider_review_responses/:id.jsonapi
URL Parameters
| Parameter | Description |
|---|---|
| :id | The id of the response to a review to retrieve |
Moderation Webhook
If a review is created with the moderation_webhook_url attribute set, a moderation action will trigger a request will be sent to that URL with an HTTP POST. This request includes all of the attributes that make up the review. The POST request will have a User-Agent header of Caring.com Review Moderation Webhook and a Referer header of https://dir.caring.com.
Example Webhook Payload
{
"review": {
"id": 1579647,
"resource_id": 2664,
"resource_url": "http://www.caring.test/local/assisted-living-facilities-in-salisbury-maryland/lakeside-assisted-living",
"resource_name": "Lakeside Assisted Living",
"chain_name": null,
"title": "I am a friend or relative of a current/past resident",
"content": "My grandmother and grandfather stayed at this facility for several years.",
"rating": 5.0,
"staff_score": 5.0,
"activities_score": 5.0,
"food_score": 4.0,
"facilities_score": 4.0,
"value_score": 5.0,
"provider_response": null,
"moderation_status": "unmoderated",
"rejection_reason": null,
"moderated_at": null,
"author": {
"name": "SatisfiedReviewer11",
"email": "SatisfiedReviewer11@example.com",
"url": "https://www.twitter.com/SatisfiedReviewer11"
},
"origin_url": null,
"created_at": "2019-05-17T01:58:37.000-07:00",
"updated_at": "2019-05-17T02:10:34.000-07:00"
}
}