Data Sync APIs (v2)

Our Data Sync APIs are perfect for integrating data from the SocialClimb application into your BI Database via a JSON API. Looking for the v1 docs? See Data Sync APIs (v1).

The v2 API uses OAuth 2.0 client credentials with a signed JWT client assertion (RFC 7523) instead of the static api-token header used by v1. You authenticate once to exchange a signed assertion for a short-lived bearer access token, then send that bearer token on every data request.

The api base domain is https://api.socialclimb.com.

• Content-Type header is required to be set as application/json
• All v2 endpoints live under /v2/... (v1 lives under /v1/... — see Data Sync APIs (v1))

In https://app.socialclimb.com, under Preferences → API / OAuth clients, create a new OAuth client. You will provide:

On creation you will receive a client_id. You keep the matching private key on your side; SocialClimb never sees it. To rotate keys, update the JWKS at the jwk_url — no changes in SocialClimb are needed.

Sign a JWT with your private key using RS384. Claim set:

The signing key’s kid must be present in the JWKS at your jwk_url so SocialClimb can select the right public key.

POST /oauth/token — Content-Type: application/x-www-form-urlencoded.

Form body:

curl -X POST https://api.socialclimb.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=eyJhbGciOiJSUzM4NCIs..."

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}

The access_token is an HS256-signed JWT issued by SocialClimb. expires_in is the lifetime in seconds. Treat the access token as opaque — do not parse it in your client; just replay it.

Token endpoint errors:

Send the access token on every data request in the Authorization header:

curl --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
     --header "Content-Type: application/json" \
     https://api.socialclimb.com/v2/locations

Run the command above to quickly test authorization. Requests without a valid bearer token return 401 Invalid or expired OAuth access token. Requests from a disabled or revoked client, or against a disabled account, also return 401.

When the access token expires, exchange a new client assertion at /oauth/token and reuse the new access token until it expires. You do not need a fresh access token per request.

• Authentication — OAuth 2.0 bearer token on every call, not a static api-token header. No account-scoped secret is stored in your integration code.
• Base path — /v2/... instead of /v1/.... Endpoint shapes and response bodies are otherwise the same as v1.
• Scoping filters — the Reviews, NPS Surveys, Survey Responses, and Invites endpoints gain optional location_id, provider_id, group_id, and custom_filters query parameters (see Filtering results). v1 returned the full account-scoped dataset and expected you to filter client-side.

Several v2 endpoints accept optional scoping filters and a custom-field filter on the query string. Endpoints that support filtering explicitly say so in their section below. They are:

• /v2/reviews
• /v2/surveys (NPS Surveys)
• /v2/survey-responses
• /v2/invites

Other endpoints ignore these parameters.

Combination rules:

• Within a single parameter the list is OR-ed (location_id=1,2 means locations 1 or 2).
• Across parameters the filters are AND-ed (location_id=1,2&provider_id=9 means (location 1 OR 2) AND provider 9).

Ownership check: every ID is verified to belong to the caller’s account. If any ID does not, the API returns 400 Unknown location_id(s)/provider_id(s)/group_id(s) for this account: [...]. This prevents probing IDs that belong to other tenants.

Integer validation: any non-integer list member returns 400 Invalid integer in list: '<value>'.

Partners who use SocialClimb custom fields (the EAV surface underneath Invites / Reviews) can filter by custom-field value using the custom_filters query parameter. The value is a URL-encoded JSON object whose keys are of the form custom_fields.<field_name>.

<field_name> must match [A-Za-z0-9_]+. Any other key shape returns 400 Invalid custom_filters key.

Example — filter by appointment_type and referral_source:

{"custom_fields.appointment_type": ["eq", "Office"],
 "custom_fields.referral_source":  ["in_", ["Web", "Phone"]]}

URL-encoded (abbreviated):

?custom_filters=%7B%22custom_fields.appointment_type%22%3A%5B%22eq%22%2C%22Office%22%5D%7D

Errors:

Scoping filters and custom_filters may be used together on the same request. They combine with AND semantics — the result is the intersection of the scoping predicate and the custom-field predicate.

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 /v2/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
• location_id, provider_id, group_id, and custom_filters are optional — see Filtering results.
• Response is sorted by create_time desc

• Example: GET /v2/reviews?date=2020-09-01&end=2020-09-30&rating=1,2,3
• Example (scoped): GET /v2/reviews?date=2020-09-01&end=2020-09-30&location_id=12,34&provider_id=56

• 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

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

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 /v2/invites?date=2017-07-01T00:00:00Z

• date is optional and limits the results to the next 24hrs after
• location_id, provider_id, group_id, and custom_filters are optional — see Filtering results.
• Response is sorted by sent_at desc

• Example (scoped): GET /v2/invites?date=2024-01-01T00:00:00Z&group_id=42

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

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

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 /v2/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 /v2/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 /v2/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

*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.

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

HTTP Request

GET /v2/campaigns

• start_date and end_date parameters are both required.
• Response is grouped by campaign channel

• Example: GET /v2/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": "16",
      "Assists": "20",
      "Channel": "Paid Search",
      "Conversions": "40",
      "Cost": "$320.00",
      "Cost/Appt": "20",
      "Cost/Assist": "16",
      "Cost/Conversion": "8",
      "Cost/Patient": "25",
      "Estimated Revenue": "$4600.00",
      "New Patients": "8",
      "ROAS": "140%"
    }
  ]
}

This endpoint retrieves a list of Survey names and IDs for the account.

HTTP Request

GET /v2/surveys-list

• This endpoint does not take any additional parameters.

JSON Response

{
  "items": [
    {
      "id": 99999,
      "name": "Survey Name"
    }
  ]
}

This endpoint retrieves survey responses for a particular survey.

HTTP Request

GET /v2/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.
• location_id, provider_id, group_id, and custom_filters are optional — see Filtering results.
• Response fields will vary according to the fields on the survey.
• Response is sorted by when desc

• Example: GET v2/survey-responses?start_date=2022-09-01&end_date=2022-09-30&survey_id=99999
• Example (scoped): GET v2/survey-responses?survey_id=99999&location_id=12,34

• 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

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

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 /v2/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
• location_id, provider_id, group_id, and custom_filters are optional — see Filtering results.
• Response is sorted by create_time desc

• Example: GET /v2/surveys?date=2020-09-01&end=2020-09-30&rating=1,2,3
• Example (scoped): GET /v2/surveys?date=2020-09-01&end=2020-09-30&group_id=7,8

• 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

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

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

Request

GET /v2/insights/byMonth

{}

Response

[
  {
    "location_id": 12345,
    "month": 202303,
    "metric_type": "views_maps",
    "count": 123
  }
]

Returns a list of PX (Integration Import) runs for the account (one object per run). Data matches what is shown in the Integration Imports UI grid. Each item is one run; the API does not return a single aggregated summary.

HTTP Request

GET /v2/integration-imports

Query parameters (all optional)

• If only start_date: runs with start_date >= start_date.
• If only end_date: runs with start_date <= end_date.
• If both: runs with start_date between the two (inclusive).
• By default, test runs (is_test=true) are excluded. Use show_test_runs=true to include them.
• Results are ordered by run ID descending (newest first).

• Example: GET /v2/integration-imports?start_date=2025-06-01&end_date=2025-06-30
• Example: GET /v2/integration-imports?show_test_runs=true

Response (top-level)

Response (each object in items)

JSON Response (default, no test runs)

{
  "items": [
    {
      "import_id": 9896,
      "rows_processed": 1398,
      "mismatches": 136,
      "warnings": 0,
      "appointment_captured": 356,
      "new_patients": 142,
      "scheduled_invites": 149,
      "skipped_appointments": 0,
      "skipped_invites": 0,
      "start_date": "2025-06-30T00:00:00+00:00",
      "end_date": "2025-06-30T00:00:00+00:00",
      "upload_date": "2025-06-30 00:00:00"
    }
  ]
}

JSON Response (with show_test_runs=true)

When show_test_runs=true, each item includes an is_test field:

{
  "items": [
    {
      "import_id": 9897,
      "rows_processed": 100,
      "mismatches": 0,
      "warnings": 0,
      "is_test": true,
      "appointment_captured": 50,
      "new_patients": 20,
      "scheduled_invites": 30,
      "skipped_appointments": 0,
      "skipped_invites": 0,
      "start_date": "2025-06-30T00:00:00+00:00",
      "end_date": "2025-06-30T00:00:00+00:00",
      "upload_date": "2025-06-30 00:00:00"
    }
  ]
}

Errors (missing or invalid Authorization: Bearer token, wrong Content-Type, or disabled account) follow the same behavior as other Data Sync endpoints.

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

This endpoint retrieves all locations

HTTP Request

GET /v2/locations

JSON Response

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

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

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

This endpoint retrieves all messages

HTTP Request

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

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 /v2/groups

Response

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