Introduction
SocialClimb is a HIPAA compliant Reputation Management platform.
- Listings Management
- Surveys
- Physician and Site of Service Benchmarking
- Physician and Brand Reputation Marketing
Learn More at SocialClimb.com
Getting started
Requests to the api will require a header named api-token. Your api token can be found on https://app.socialclimb.com.
The api base domain is https://api.socialclimb.com
curl --header "api-token: xxxx-xxx-xxxxx-xxxxxxxx" --header "content-type: application/json" https://api.socialclimb.com/v1/locations
Run this command to quickly test authorization
- Content-Type header to be set as
application/json
Locations
JSON Response
{
"items": [
{
"id": 1,
"location_name": "name"
}
]
}
Get All Locations
This endpoint retrieves all locations
HTTP Request
GET /v1/locations
Platforms
JSON Response
{
"items": [
{
"active": true,
"id": 90238,
"is_survey": false,
"name": "Google"
},
{
"active": true,
"id": 90239,
"is_survey": false,
"name": "Yelp"
},
{
"active": true,
"id": 91230,
"is_survey": false,
"name": "Facebook"
},
{
"active": true,
"id": 91232,
"is_survey": false,
"name": "Private"
},
{
"id": 100143,
"is_survey": true,
"name": "Survey #2"
}
]
}
Get All Platforms
This endpoint retrieves all platforms
HTTP Request
GET /v1/platforms
Messages
JSON Response
{
"items": [
{
"id": 52345,
"name": "Johnny Doe",
"oid": "doe",
"division": "",
"img_url": "https://storage.googleapis.com/socialclime-prod/message-default.png",
"languages": {
"en": {
"key": "en",
"message":
"{customer.firstname},\nThank you for choosing {account.name}. Please take a minute and leave me feedback at the link below.\n{user.name}"
},
"es": {
"key": "es",
"message":
"{customer.firstname},\nGracias por usar {account.name}. Por favor, deje un comentario en el siguiente enlace.\n{user.name}"
}
}
}
]
}
Get All Messages
This endpoint retrieves all messages
HTTP Request
GET /v1/messages
Create a new Message
JSON Request Body
{
"name": "Provider Name",
"oid": "UNIQUE_EXTERNAL_ID",
"languages": {
"en": {
"message":
"{customer.firstname},\nThank you for allowing me to help you. Please click the link below to leave your feedback!\n{user.name}\n\n{account.name}",
"greeting": "Would you recommend {account.name}?"
},
"es": {
"message":
"{customer.firstname},\nGracias por permitirme ayudarte. Por favor, haga clic en el enlace de abajo para dejar su opinión!\n{user.name}\n\n{account.name}",
"greeting": "Recomendarias {account.name}?"
}
},
"platforms": [111, 222, 333]
}
Creates a new Message
Creates a new message with the supplied configuration
HTTP Request
POST /v1/messages
Update Message
JSON Request Body
{
"id": 770490,
"name": "Test 2",
"oid": "UNIQUE_EXTERNAL_ID",
"languages": {
"en": {
"greeting": "Would you recommend {account.name}?",
"message":
"{customer.firstname},\nThank you for allowing me to help you. Please click the link below to leave your feedback!\n{user.name}\n\n{account.name}"
},
"es": {
"greeting": "Recomendarias {account.name}?",
"message":
"{customer.firstname},\nGracias por permitirme ayudarte. Por favor, haga clic en el enlace de abajo para dejar su opinión!\n{user.name}\n\n{account.name}"
}
},
"platforms": [111, 222, 333]
}
Updates a Message
Updates a message with the supplied configuration
HTTP Request
PUT /v1/messages/:id
Update Message Image
Example
multipart/form-data
post body
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=""; filename="provider_image.png"
Content-Type: image/png
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Adds or replaces a messages image
Upload and set a messages image
HTTP Request
PUT /v1/messages/:id/image
Delete a Message
Deletes a Message
Deletes a message with the id on the url path
HTTP Request
DELETE /v1/messages/:id
Users
Get Users
JSON Response
{
"items": [
{
"active": true,
"email": "[email protected]",
"id": 132532,
"name": "Provider Name",
"oid": "EXTERNAL_ID",
"phone": "5555555555",
"bio": "User Bio"
},
{
"active": true,
"email": "[email protected]",
"id": 102344,
"name": "Another Name"
}
]
}
Gets all Users
This endpoint retrieves all users
HTTP Request
GET /v1/users
Get User Reviews
JSON Response
{
"items": [
{
"review_id": "...",
"comment": "Review text comment",
"create_time": "2017-05-04T18:22:22+00:00",
"invite_name": "Customer's name",
"invite_type": "sms|email",
"location": "Location's name",
"location_oid": "Location identifier",
"external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3"],
"external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
"message": "SocialClimb message name used in invite",
"platform": "Google|Facebook|...",
"rating": 5,
"reviewer": "Reviewer's name",
"sent_at": "2017-05-04T18:24:58+00:00",
"sent_to": "8005550000|[email protected]"
}
]
}
Get User Reviews
This endpoint retrieves all reviews by user_id
HTTP Request
GET /v1/users/:user_id/reviews
- date is optional and limits the results to the next 24hrs after
- Response is sorted by
create_time
desc
Invite User
JSON Request Body
{
"role": "Administrator",
"name": "Provider Name",
"email": "[email protected]",
"oid": "EXTERNAL_ID"
}
Invites a User
Creates a pending user in the account awaiting the user creating his password
- Role can be
Administrator
,Service User
,Office Staff
,Location Admin
HTTP Request
POST /v1/users
Update User
{
"name": "j j",
"role": "Location Admin",
"oid": "EXTERNAL_ID"
}
Updates a User
Updates a user with the supplied configuration
- Role can be
Administrator
,Service User
,Office Staff
,Location Admin
HTTP Request
PUT /v1/users/:id
Update User Image
Example
multipart/form-data
post body
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=""; filename="provider_image.png"
Content-Type: image/png
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Adds or replaces a users image
Upload and set a users image
HTTP Request
PUT /v1/users/:id/image
Delete User
Deletes a User
Deletes a user with the id on the url path
HTTP Request
DELETE /v1/users/:id
Setup User & Message
Create user and message
Both user and message will created and linked.
Example
multipart/form-data
post body
Content-Type: multipart/form-data; boundary=123456
--123456
Content-Disposition: form-data; name=”file”; filename=”service_provider_picture.jpg”
content of service_provider_picture.jpg
--123456
Content-Disposition: form-data; name="role"
Adminstrator
--123456
Content-Disposition: form-data; name="name"
Provider Name
--123456
Content-Disposition: form-data; name="email"
[email protected]
--123456
Content-Disposition: form-data; name="oid"
EXTERNAL_ID
--123456--
HTTP Request
POST /v1/setup
role
,name
,email
are required fields- An image file is optional
Content-Type
must bemultipart/form-data
Update image
Updates both user and message image
HTTP Request
PUT /v1/setup/:id
id
can be a message or user id. It will update both the message and user image if they are linked.
Reviews
JSON Response
{
"items": [
{
"review_id": "...",
"comment": "Review text comment",
"create_time": "2017-05-04T18:22:22+00:00",
"invite_name": "Customer's name",
"invite_type": "sms|email",
"location": "Location's name",
"location_oid": "Location identifier",
"external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3" ],
"external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
"message": "SocialClimb message name used in invite",
"platform": "Google|Facebook|...",
"rating": 5,
"reviewer": "Reviewer's name",
"sent_at": "2017-05-04T18:24:58+00:00",
"sent_to": "8005550000|[email protected]"
}
]
}
Get All Reviews
This endpoint retrieves all reviews
HTTP Request
GET /v1/reviews
- date is optional and limits the results to the next 24hrs after if no end date is provided
- end is optional. If no start date is provided, results will include all reviews up to the end date.
- rating is optional. Use a comma separated list of all ratings that should be included in the results
- Response is sorted by
create_time
desc
- Example:
GET /v1/reviews?date=2020-09-01&end=2020-09-30&rating=1,2,3
- The example above will return all reviews with a rating of 1, 2, or 3 and were received between September 1st, 2020 and September 30th, 2020
NPS Surveys
JSON Response
{
"items": [
{
"nps_rating": 10.0,
"question_id": "Recommend",
"review_id": "...",
"comment": "Review text comment",
"create_time": "2017-05-04T18:22:22+00:00",
"invite_name": "Customer's name",
"invite_type": "sms|email",
"location": "Location's name",
"location_oid": "Location identifier",
"external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3"],
"external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
"message": "SocialClimb message name used in invite",
"platform": "Google|Facebook|...",
"rating": 5,
"reviewer": "Reviewer's name",
"sent_at": "2017-05-04T18:24:58+00:00",
"sent_to": "8005550000|[email protected]"
}
]
}
Get All NPS Surveys
This endpoint retrieves all NPS surveys. The body is very similar to the review api but with the addition of nps_rating and question_id.
HTTP Request
GET /v1/surveys
- date is optional and limits the results to the next 24hrs after if no end date is provided
- end is optional. If no start date is provided, results will include all surveys up to the end date.
- rating is optional. Use a comma separated list of all ratings that should be included in the results
- Response is sorted by
create_time
desc
- Example:
GET /v1/surveys?date=2020-09-01&end=2020-09-30&rating=1,2,3
- The example above will return all surveys with a rating of 1, 2, or 3 and were received between September 1st, 2020 and September 30th, 2020
Invites
JSON Response
{
"items": [
{
"clicked": [
{
"created_at": "2017-03-02 05:43:51+00:00",
"name": "Google|Facebook|..."
}
],
"customer_name": "John Smith",
"extras": {
"test": "A",
"address": "Stonebrick ln"
},
"location": "Location's name",
"location_oid": "Location identifier",
"external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3"],
"external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
"message": "SocialClimb message name used in invite",
"opened": "2017-03-02 05:43:36+00:00",
"platform": "Google|Facebook|...",
"proceeded_to_review": true,
"review_rating": 5,
"sent_at": "2017-07-02 03:35:19+00:00",
"sent_by": "",
"sent_to": "5554443333|[email protected]",
"status": "sent",
"type": "sms|email"
}
]
}
Get All Invites
This endpoint retrieves all invites
HTTP Request
GET /v1/invites?date=2017-07-01T00:00:00Z
- date is optional and limits the results to the next 24hrs after
- Response is sorted by
sent_at
desc
Create a new Invite
JSON Request Body
{
"name": "Name of customer who will be receiving ",
"sent_to": "5552228888",
"address": "123 bridge lane"
}
JSON Response
{
"id": "f0c3c82c-befa-4440-16cb-29ce6c623456",
"message": {
"image": {
"url": "https://storage.googleapis.com/socialclime-prod/an-image.png"
},
"languages": {
"en": {
"message": "English message"
},
"es": {
"message": "Spanish message"
}
}
},
"url": "https://goo.gl/example"
}
- message is optional if one is not selected the account default is used
- location and message id is an external id that you input within the SocialClimb web interface
- patient name required
- must include sent_to which can be a phone or email
POST /v1/locations/:id/invites?message=1
Optionally you can have SocialClimb do delivery by appending /send
POST /v1/locations/:id/invites/send?message=1
Optional referral query param
{
"send": true,
"url": "https://goo.gl/b6N69e"
}
JSON Response
{
"send": false
}
The existence of referral
changes the invite response based on if a previous review has been captured for the recipient identified by the sent_to
field.
-
If there is a review that has a rating > 3 stars.
POST /v1/locations/:id/invites?message=1&referral=true
Response - Invite information for the message ID requested with the additional field of"send": true
. -
If there is a review with rating <= 3 stars or no previously recorded review.
POST /v1/locations/:id/invites?message=1&referral=true
Previsits
Get Previsits
JSON Response
{
"items": [
{
"customer": "Name of customer to receive previsit",
"lang": "en|es",
"location": "Location name",
"location_id": "Location identifier",
"sent_at": "2017-06-14T20:12:05+00:00",
"sent_by": "Who sent the previsit",
"sent_to": "8005550000|[email protected]",
"service_provider": "Employee name previsit was sent for",
"service_provider_id": "Employee identifier",
"msg": "Previsit text message"
}
]
}
This endpoint retrieves all reviews
HTTP Request
GET /v1/previsits
- Response is sorted by
sent_at
desc
Create Previsit
JSON Request Body
{
"lang": "en|es",
"user": "identifier",
"location": "identifier",
"name": "Customer name",
"sent_to": "8005550000|[email protected]",
"msg": "Previsit message included in sms or email text"
}
JSON Response
- Success - http status code 200 with `{}` in body
- Error - appropriate http status code with error message details in body
This endpoint retrieves all reviews
HTTP Request
POST /v1/previsits
Med Import
Post Med Import
POST /v1/medimport
JSON Request Body
[
{
"mess_id": "",
"location_name": "",
"provider": "",
"patient_name": "",
"language": "",
"home_phone": "",
"day_phone": "",
"alt_phone": "",
"sec_home_phone": "",
"cell_phone": "",
"email_address": "",
"encounter_type": "",
"client_id": "",
"message_type": "",
"appointment_date": "",
"patient_id": ""
},
{
"mess_id": "",
"location_name": "",
"provider": "",
"patient_name": "",
"language": "",
"home_phone": "",
"day_phone": "",
"alt_phone": "",
"sec_home_phone": "",
"cell_phone": "",
"email_address": "",
"encounter_type": "",
"client_id": "",
"message_type": "",
"appointment_date": "",
"patient_id": ""
}
]
Calls
Get Calls
This endpoint retrieves all Calls.
HTTP Request
GET /v1/calls
start_date
is optional and limits the results to the next 24 hrs after if noend_date
is provided.end_date
is optional. If nostart_date
is provided, results will include all calls up to the end date.- Response is sorted by
Call Date
desc
- Example:
GET /v1/calls?start_date=2022-09-01&end_date=2022-09-30
- The example above will return all calls that were received on or after September 1st, 2022 and before September 30th, 2022
JSON Response
{
"items": [
{
"appt_date": "---",
"call_date": "9/22/2022 11:06 pm",
"campaign": "Campaign Name",
"channel": "Organic Search",
"from_number": "8019982830",
"location_name": "---",
"new_patient": false,
"patient_id": "UNKNOWN",
"patient_name": "UNKNOWN",
"provider": "---",
"source": "Google Business Profiles",
"tracking_number": "8019982830"
}
]
}
Campaigns
Get Campaigns
This endpoint retrieves Campaigns data for the account over a specified time period.
HTTP Request
GET /v1/campaigns
start_date
andend_date
parameters are both required.- Response is grouped by campaign channel
- Example:
GET /v1/campaigns?start_date=2022-09-01&end_date=2022-09-30
- The example above will return the Campaigns data for the specified time period, grouped by campaign channel.
JSON Response
{
"items": [
{
"appointments": "3",
"calls": "248",
"channel": "Direct",
"cost": "$320.00",
"cost_per_appt": "$106.67",
"cost_per_call": "$1.29",
"cost_per_patient": "$320.00",
"new_patients": "1"
}
]
}
Surveys List
Get Surveys List
This endpoint retrieves a list of Survey names and IDs for the account.
HTTP Request
GET /v1/surveys-list
- This endpoint does not take any additional parameters.
JSON Response
{
"items": [
{
"id": 99999,
"name": "Survey Name"
}
]
}
Survey Responses
Get Survey Responses
This endpoint retrieves survey response data for a particular survey.
HTTP Request
GET /v1/survey-responses
- The
survey_id
parameter is required. Survey IDs can be obtained using the Surveys List endpoint. start_date
is optional. If provided, results will include all records after this date.end_date
is optional. If provided, results will include all records before this date.- Response fields will vary according to the fields on the survey.
- Response is sorted by
when
desc
- Example:
GET v1/survey-responses?start_date=2022-09-01&end_date=2022-09-30&survey_id=99999
- The example above will return all responses for survey
99999
that were submitted on or after September 1, 2022 and before September 30, 2022.
JSON Response
{
"items": [
{
"appointment_date": "8/30/22 12:00:00 pm",
"care_from_provider": "Very Good",
"contact": "8019982830",
"friendliness": "Very Good",
"friendliness_team": "Very Good",
"likelihood_to_recommend": "Very Good",
"location": "Clinic Location",
"npi": null,
"overall": 5.0,
"patient_first": "FirstName",
"patient_id": "123456",
"patient_last": "LastName",
"patient_name": "FirstName LastName",
"provider": "Provider Name, MD",
"provider_time": "Very Good",
"scheduling": "Very Good",
"survey_submit_date": "9/1/22 12:39:46 am",
"user": "FirstName LastName",
"user_id": "123456",
"wait_time_clinic": "Very Good",
"when": "9/1/22 12:39:46 am"
}
]
}
Insights
The Insights API allows you to retrieve monthly aggregated data by Google Business Profile.
Request
POST /v1/insights/byMonth
{}
Response
Name | Type | Description |
---|---|---|
location_id | int | Location Id |
month | int | Number representing the month. Format: YYYYMM. |
metric_type | string | Enum: views_maps, views_search, actions_website, actions_phone, actions_driving_directions |
count | int | Total for this location/month/type combination. |
[
{
"location_id": 12345,
"month": 202303,
"metric_type": "views_maps",
"count": 123
}
]
Partners
The partner api allows a partner to get data from his client accounts.
Difference from other api calls
Requests to the partner api will require a header named api-token. This is different from a client token. Contact customer support to have a token created for you. The api functions the same as the standard SocialClimb api, except how you get your token.
Providers
JSON Response
{
"count": "20",
"average_rating": "4.8"
}
This endpoint retrieves a count and average rating for a provider associated with one of your client accounts.
HTTP Request
GET /v1/providers/<NPI>
GET /v1/providers/12345678
SSO
SAML 2.0
Required Attributes(Claims)
<Attribute Name="Role">
<AttributeValue>Administrator</AttributeValue>
</Attribute>
Role can be
Administrator
,Service User
,Office Staff
,Location Admin
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
<AttributeValue>[email protected]</AttributeValue>
</Attribute>
Email should be valid and match the IDP users identity
Introduction
SocialClimb supports enterprise single sign-on (SSO) using the SAML 2.0 standard (http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). Authentication is supported via both IDP and SP workflows and allows for JIT user provisioning.
SocialClimb uses OneLogin's SAML Python Toolkit. https://github.com/onelogin/python3-saml
SocialClimb requires AuthNRequest and LogoutRequest are signed
Setup Requirements
SSO integration requires coordination between your IT department and the SocialClimb implementation team. The data that needs to be prepared prior to the integration is:
- Metadata xml file. The metadata file should follow the SAML 2.0 standard and include all of the information necessary for SocialClimb to validate the authentication request with the identity provider. Your IDP system should be able to generate this file.
- Socialclimb requires two Attributes/Claims in order to enable JIT user provisioning.
Frequently Asked Questions
- Does SocialClimb support SHA256 signed tokens - Yes
- Does SocialClimb support/require signature verification of AuthNRequests? Yes
- How are user accounts deprovisioned and terminated - Accounts can be deprovisioned and/or terminated either through the SocialClimb interface or API.
User Provisioning
- Within your IDP add required attributes to the users your expect to be using SocialClimb
- The user can then use IDP initiated or SP initiated SSO and have the user JIT provisioned
User Deprovisioning
- Go to the user accounts https://app.socialclimb.com/app/user-accounts
- Edit the user using the more options icon on the right side
- Scroll to the bottom and hit the trashcan icon to delete the user
- You will need to remove the SocialClimb Role attribute within your IDP to prevent the user from being JIT provisioned again.
Support Information
- You can contact us about your SAML integration through [email protected]
Website Embed
iframe
Unfiltered reviews
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/reviews" width="720" height="400">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to a location reviews
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/reviews?loc=<loc_id>" width="720" height="400">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to a doctor reviews
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/reviews?doc=<doc_id>" width="720" height="400">
<p>Your browser does not support iframes.</p>
</iframe>
Unfiltered averages
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/averages" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to a location averages
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/averages?loc=<loc_id>" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to a doctor averages
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/averages?doc=<doc_id>" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to one survey
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/survey-average?survey=<survey_id>" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to one survey and one location
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/survey-average?survey=<survey_id>&loc=<loc_id>" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Filtered to one survey and one doctor
<iframe src="https://iframe.socialclimb.com/iframe/<iframe_token>/survey-average?survey=<survey_id>&doc=<doc_id>" width="720" height="55">
<p>Your browser does not support iframes.</p>
</iframe>
Introduction
The iframe snippet will enable you to embed your reviews directly into your website.
Your iframe token can be found on https://app.socialclimb.com.
Iframe Settings
Once the iframe has been enabled in your account, some granular settings can be configured. Below is an image showing all the different settings that can be changed. The different settings that can be configured include:
- Maximum Rating
- Reviews Limit
- Font size for the Averages iframe
- Font size for the Reviews iframe
- Show/Hide private reviews
- Show/Hide reviewer's last name
- Horizontally center Averages iframe
- View Reviews iframe in grid format
- Filter iframe by Platform
Iframe Reviews Coloring
If you're using our reviews iframe, it comes with ability to be styled to match your brand. These inputs work off of hex values and allow hex values with or without alpha channels (i.e. #000000 and #00000000 will work). Below are all of the options that can be edited with your own hex value to style the reviews iframe.
- Background Color
- Background Card Color (used for card color if “View reviews in grid format” is toggled on)
- Star Color (Filled In)
- Star Color (Not Filled In)
- Font Color
Something to note is that when initally enabling iframe's for your account, there will be default SocialClimb colors for your account. If at anytime you wish to change back to these colors, just click the “Restore Default Colors” and click “Save” to reset the reviews iframe colors.
Iframe of average review score
Iframe of customer reviews, standard layout
The standard layout can be used at any time by adding ?layout=rows
to the end of the reviews url.
- Example:
https://iframe.socialclimb.com/iframe/..../reviews?layout=rows
Iframe of customer reviews, grid layout
The grid layout can be used at any time by adding ?layout=grid
to the end of the reviews url.
- Example:
https://iframe.socialclimb.com/iframe/..../reviews?layout=grid
Iframe of all survey averages
Iframe of survey average from one survey and one location
Iframe of survey average from one survey and one doctor
Security
We do our best to make sure our software is free of security vulnerabilities. Reality though is that it's not always the case. That is why we are very much eager and grateful to hear about any issues you find. Please report these directly via email.