SocialClimb API Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

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

Response

Name Type Description
comment string Email or phone number survey was sent to
create_time string Date survey was submitted. Example: 2017-05-04T18:22:22+00:00
external_location_ids array Array of eid given to survey’s location
external_provider_ids array Array of eid of survey provider
groups array Array of group_id of survey
invite_name string Name of survey recipient
invite_type string Contact info type of survey. sms or email
location number Total for this location/month/type combination.
location_id number location_id of survey location
location_oid string location_oid of survey location
message string Name of provider of invite
nps_rating number Overall nps rating of survey
platform string Name of survey
provider string Name of provider of invite
provider_id number Id of provider of invite
question_id string Descriptive name of question
rating (optional) number Overall rating of survey
review_id number Id of review
reviewer string Reviewer’s name
sent_at string Date and time survey invite was sent 2024-05-14T18:45:03Z
sent_to string Email or phone number invite was sent to

JSON Response

{
  "items": [
    {
      "comment": "Review text comment",
      "create_time": "2017-05-04T18:22:22+00:00",
      "external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
      "external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3"],
      "invite_name": "Customer's name",
      "invite_type": "sms|email",
      "location": "Location's name",
      "location_id": 123456789,
      "location_oid": "Location identifier",
      "message": "Provider's Name",
      "nps_rating": 10.0,
      "provider": "Provider's Name",
      "provider_id": "Provider's Id",
      "question_id": "Recommend",
      "platform": "Google|Facebook|...",
      "rating": 5,
      "review_id": "...",
      "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's identifier",
      "location_id": "Location's Id",
      "provider": "Provider's Name",
      "provider_id": "Provider's Id",
      "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.

Response

Name Type Description
appointment_date string Date of appointment
contact string Email or phone number survey was sent to
groups array Array of group_id of survey
location number Total for this location/month/type combination.
location_id number location_id of survey location
npi string Nation Provider ID
overall number Overall rating of survey
patient_first string Patient’s first name
patient_name string Patient’s full name
patient_id string Patient id
patient_last string Patient last name
provider string Provider name
state string State in address of Google Business Profile
survey_date string Date survey was submitted. Example: 1/1/2024 12:00:00 pm
user string Patient’s full name
user_id string Patient id
*additional rows any Each survey will also add a key/value pair for each question’s
descriptive name and answer value.
Example: {“experience”: “Very Good”}

JSON Response

{
  "items": [
    {
      "appointment_date": "8/30/22 12:00:00 pm",
      "contact": "8019982830",
      "groups": [
        1234,
        2345,
        3456
      ],
      "location": "Clinic Location",
      "location_id": 123456,
      "npi": null,
      "overall": 5.0,
      "patient_first": "FirstName",
      "patient_name": "FirstName LastName",
      "patient_id": "123456",
      "patient_last": "LastName",
      "provider": "Provider Name, MD",
      "state": "UT",
      "survey_date": "1/1/22 12:00:01 am",
      "user": "FirstName LastName",
      "user_id": "123456"
    }
  ]
}

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

Response

Name Type Description
comment string Email or phone number survey was sent to
create_time string Date survey was submitted. Example: 2017-05-04T18:22:22+00:00
external_location_ids array Array of eid given to survey’s location
external_provider_ids array Array of eid of survey provider
groups array Array of group_id of survey
invite_name string Name of survey recipient
invite_type string Contact info type of survey. sms or email
location number Total for this location/month/type combination.
location_id number location_id of survey location
location_oid string location_oid of survey location
message string Name of provider of invite
nps_rating number Overall nps rating of survey
platform string Name of survey
provider string Name of provider of invite
provider_id number Id of provider of invite
question_id string Descriptive name of question
rating (optional) number Overall rating of survey
review_id number Id of review
reviewer string Reviewer’s name
sent_at string Date and time survey invite was sent 2024-05-14T18:45:03Z
sent_to string Email or phone number invite was sent to

JSON Response

{
  "items": [
    {
      "comment": "Review text comment",
      "create_time": "2017-05-04T18:22:22+00:00",
      "external_location_ids": ["OFFICE_EXT_NAME", "EXAMPLE_ID", "EXAMPLE3"],
      "external_provider_ids": ["NPI", "EXAMPLE_ID", "EXAMPLE3"],
      "invite_name": "Customer's name",
      "invite_type": "sms|email",
      "location": "Location's name",
      "location_id": 123456789,
      "location_oid": "Location identifier",
      "message": "Provider's Name",
      "nps_rating": 10.0,
      "provider": "Provider's Name",
      "provider_id": "Provider's Id",
      "question_id": "Recommend",
      "platform": "Google|Facebook|...",
      "rating": 5,
      "review_id": "...",
      "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 number Location Id
month number Number representing the month. Format: YYYYMM.
metric_type string Enum: views_maps, views_search, actions_website, actions_phone, actions_driving_directions
count number 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",
      "external_location_ids": ["external_id_1", "external_id_2"]
    }
  ]
}

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",
      "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}"
        }
      }
    }
  ]
}

Groups

SocialClimb Groups serve as a means to categorize locations and associated providers within the system. These groupings facilitate streamlined report filtering and administrative delegation within the SocialClimb application.

This endpoint retrieves all groups within the account, along with the providers and locations affiliated with each group. The children generally serve as a bridge between providers and the locations where they operate.

HTTP Request

GET /v1/groups

Response

Name Type Description
id number Unique identifier for the group.
name string Name of the group.
providers array List of providers associated with the group.
- id number Unique identifier for the provider.
- name string Unique identifier for the provider.
- external_provider_ids array List of external ids for provider.
locations array List of locations associated with the group.
- id number Unique identifier for the location.
- name string Name of the location.
- formatted string Formatted address of the location.
- external_location_ids array List of external ids for location.
- children array List of child entities associated with the location, typically providers.
- - id number Unique identifier for the child location entity.
- - name string Name of the child location entity.
- - formatted string Formatted address of the child entity’s location.
- - provider_id number Unique identifier for the connected provider entity.
{
  "items": [
    {
      "id": 5231652,
      "name": "Physical Therapy North",
      "providers":
        [
          {
            "id": 12412525,
            "name": "Dr. Tommy"
          }
        ],
      "locations":
      [
        {
          "formatted": "123 S Decatur, Las Vegas, NV, 89107",
          "id": 347347,
          "name": "Example Therapy Office",
          "children": [
            {
              "provider_id": 12412525,
              "formated": "123 S Decatur Suite #201, Las Vegas, NV, 89107",
              "id": 452346,
              "name": "Dr. Tommy"
            }
          ]
        }
      ]
    }
  ]
}