SocialClimb API Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. Welcome to SocialClimb's API documentation
  2. /
  3. Api
  4. /
  5. Data Sync APIs

Data Sync APIs

Our Data Sync APIs are perfect for integrating data from the SocialClimb application into your BI Database via a JSON API.

Getting started with the SocialClimb Data Sync API

Requests to the api will require a header named api-token. Your api token can be found in https://app.socialclimb.com under “Account API Key”.

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 is required to be set as application/json

API Endpoints

Reviews

SocialClimb reviews are a normalized set of all reviews aggregated and normalized from other platforms.

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

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|john@doe.com"
    }
  ]
}

Invites

SocialClimb Invites are the record of a patient visit and corresponding patient interaction with the survey or review platform.

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

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|john@doe.com",
      "status": "sent",
      "type": "sms|email"
    }
  ]
}

Calls

SocialClimb Calls are the recorded instance of prospects having called a SocialClimb Call Tracker in a Marketing Campaign.

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 no end_date is provided.
  • end_date is optional. If no start_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"
    }
  ]
}

Conversions

Get Conversions

This endpoint retrieves Conversions. Conversions can be either a Call to SocialClimb’s Call Tracker or an Online submission from a SocialClimb integrated partner.

HTTP Request

GET /v1/conversions

  • start_date is optional and limits the results to the next 24 hrs after if no end_date is provided.
  • end_date is optional. If no start_date is provided, results will include all conversions up to the end date.
  • modified_since is optional. It cannot be used with a start_date. Will return conversions that have been created or have been modified since the given date. Filters on the modified_at date. See the section below on using this to keep your data up to date.
  • Response is sorted by date desc
  • Example: GET /v1/conversions?start_date=2022-09-01&end_date=2022-09-30
  • The example above will return all conversions that were recorded on or after September 1st, 2022 and before September 30th, 2022
  • Example: GET /v1/conversions?modified_since=2022-09-30
  • The example above will return all conversions that were created or have been modified on or after September 30th, 2022
Field Description
conversion_id The unique identifier of the conversion
*appt_date The date of the patient’s appointment that occurred after the conversion event
campaign The marketing campaign that generated the conversion
channel The marketing channel that generated the conversion
date The date the call or submission occurred
from_number The patient’s phone number
*location_name The location of the patient’s appointment
new_patient The new_patient flag is set to True if, at the time the call or submission occurred, we haven’t seen any previous appointments (invites) on that account with the given phone number.
*patient_id The patient id from the corresponding appointment
*patient_name Name of the patient
*provider The name of provider that saw the patient
source The marketing source that generated the conversion
tracking_number The tracking number that the patient called
type Can be one of the following values: “Call”, “Online”, “App”
modified_at The date of the last modification. Will be the date the conversion was created until it becomes associated with an appointment, at which point the date of that association will populate this field

*These fields are only populated after the conversion gets associated with an appointment for the patient. Unpopulated values mean that an appointment for the patient hasn’t occurred after the given conversion event.

JSON Response

{
  "items": [
    {
      "appt_date": "---",
      "campaign": "Your Campaign Name",
      "channel": "Organic Search",
      "conversion_id": "123456_Call",
      "date": "9/22/2022 11:06 pm",
      "from_number": "8019982830",
      "location_name": "---",
      "modified_at": "9/24/2022 12:37 pm",
      "new_patient": false,
      "patient_id": "UNKNOWN",
      "patient_name": "UNKNOWN",
      "provider": "---",
      "source": "Google Business Profiles",
      "tracking_number": "8019982830",
      "type": "Call"
    }
  ]
}

Using modified_since Parameter to Get Updates

Conversion data is a living dataset. When a new conversion is associated with an existing appointment, the order of associations along with other details are changed. You can use the modified_since parameter to keep your data up to date and track any changes/modifications. After pulling initial data, use the modified_since paramater to pass in the date of your last data pull to get all the changes that may have occurred since then. Track the conversions with their unique conversion_id and update any that are retrieved using this parameter.

Campaigns

This endpoint retrieves Campaigns data for the account over a specified time period.

HTTP Request

GET /v1/campaigns

  • start_date and end_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

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

This endpoint retrieves survey responses 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"
    }
  ]
}

NPS Surveys

SocialClimb NPS Surveys is an endpoint dedicated to pulling NPS responses from patients.

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

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|john@doe.com"
    }
  ]
}

Google Insights

The Insights API allows you to retrieve monthly aggregated data by Google Business Profile.

Request

GET /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
  }
]

Locations

A SocialClimb Location is an aggregation of public location profiles & listings.

This endpoint retrieves all locations

HTTP Request

GET /v1/locations

JSON Response

{
  "items": [
    {
      "id": 1,
      "location_name": "name"
    }
  ]
}

Platforms

A SocialClimb Platform is a public review platform such as Google Business Profiles, Apple, Yelp, Facebook, etc.

This endpoint retrieves all platforms

HTTP Request

GET /v1/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"
    }
  ]
}

Messages

SocialClimb Messages is the configuration of the message patients receive including text message and invite experience.

This endpoint retrieves all messages

HTTP Request

GET /v1/messages

JSON Response

{
  "items": [
    {
      "id": 52345,
      "name": "Physical Therapy Patient Sat",
      "oid": "EXTERNAL_ID",
      "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}"
        }
      }
    }
  ]
}
Online Submissions gdoc_arrow_right_alt