Overview

This guide will provide you with the information and tools you need to quickly get started using the RepTrak Platform API. It will walk you through Authentication to retrieve your reputation data and discuss the different endpoints that you will use along the way. It will also point you to the resources you can use to continue to use the API going forward.

Terms

Slug - A slug is a unique identifier that you will use to construct URLs to access your data in our API.

Benchmark - A company or organization that you are tracking to compare against your own performance.

Client ID - The unique identifier that you use to obtain your API Access Token.

Client Secret - The private key that you use to obtain your API Access Token. This should be protected in the same way you would secure any other username and password.

Client company vs. Benchmark company - In our Platform and API there are two distinct sets of data that you will access. Your own RepTrak data for you as a client company and the data of the companies or organizations that you benchmark against, benchmark company data. To retrieve data for these two types of data in the API you will use separate API endpoints for each type of data. Please review the API reference document and API Overview for more information.

RepTrak Platform Glossary

Authentication

📘

API Reference Code Samples

The API Reference can be used for a more in-depth request and response formats. It also has great dynamic code samples, in many programming languages, to help you get started using the API.

Every time you use the Platform API you will need to authenticate with your client credentials. To do this you will need a ClientID and ClientSecret. Feel free to follow these steps using a tool like Postman, curl, or your preferred programming language.

Please do not share these credentials with anyone. Protect them like you would any username and password.

To access your ClientID and ClientSecret simply log in to platform.reptrak.com and go to your tools' section.

Retrieving your Access Token

🚧

Client ID and Client Secret should never be used in client-side code

Note that because the following request uses your client secret, it must never be made in client-side code or in an app binary that could be decompiled. It is important that your client secret is never shared with anyone. Therefore, this API call should only be made using server-side code.

Start by making a POST request to the following endpoint with your ClientID and ClientSecret in the request body:

POST - <https://apigateway.reptrak.com/auth/v1/access_token>
API Reference: Get Access Token

{
    "client_id": string,
    "client_secret": string
}

If you pass valid credentials in this format, you’ll get a response that looks like this:

{
    "access_token": string,
    "token_type": "Bearer",
    "expires_in": 86400
}

As you can see, the access token is only valid for 86400 seconds (1 day) in this example. This time should decrease as your token ages and when it expires you’ll have to repeat this process to get a new one.

Authorization Header

The Access token retrieved above will not be added to all other requests you make to the Platform API in your Authorization Header. You will need to add Bearer <access_token> to your Authorization header in all requests.

📘

Authorization Header

For all of your requests to the API add Bearer \<access_token>, replacing <access_token> with the token provided in the last step, to your Authorization Header.

Retrieving Company Information

Once you have your access token you can start exploring the API. This step will show you how to get information about all the available data in the API and how you can request it.

The API Reference can be used for a more in-depth request and response format.

The first action in this section is to get your Company Slug, which is used to filter data for your company in later requests. You’ll need this ID to be able to request information about your company’s reputation and other scores.

To do this you need to make a GET request to the following endpoint:

GET - <https://apigateway.reptrak.com/api/v1/companies>
API Reference: Get Companies

You’ll get a response with your ID:

{
    "companies": [
        {
            "company_id": "12345",
            "company_label": "Company Name",
            "slug": "company-slug"
        }
    ]
}

The slug in this response is the <company_slug> mentioned in upcoming steps.

Retrieving Detailed Company Information

Now make the following request with your previously obtained slug to get more details about what data is available to you in the API:

GET - <https://apigateway.reptrak.com/api/v1/companies/><company_slug>
API Reference: Get Company Tree

This will return the options available to you with information about each country, stakeholder, and benchmark that you have access to. The response will look similar to this:

{
  "company_id": "string",
  "company_name": "string",
  "slug": "string",
  "countries": [
    {
      "country_id": "string",
      "country_label": "string",
      "country_iso_code": "string",
      "stakeholders": [
        {
          "stakeholder_id": "string",
          "stakeholder_label": "string",
          "slug": "string",
          "benchmarks": [
            {
              "benchmark_id": "string",
              "benchmark_label": "string",
              "slug": "string",
              "benchmark_type": "string"
            }
          ],
          "time_periods": [
            "string"
          ]
        }
      ]
    }
  ]
}

You can see how this object can expand when we have data in multiple countries, stakeholders, and benchmarks. This also shows you the time periods of available data so you know what you can expect when requesting scores.

Retrieving Reputation Data

When you use RepTrak’s platform, you are able to review different types of metrics about your company's reputation. You can access much of the data that is in the RepTrak Platform through the API.

To start we will show you how to retrieve your reputation data through the API.

To make this request you’ll need all the information obtained in the previous calls, replacing company_id, country_id, and stakeholder_id with the desired slugs or iso-codes (company slug, country_iso_code, and stakeholder slug) from the Detailed Company Information.

GET - <https://apigateway.reptrak.com/api/v1/scores/company/><company_slug>/country/<country_iso_code>/stakeholder/<stakeholder_slug>/metric/reputation

Get Metric Scores

The response to this request looks like this:

{
  "metric_slug": "string",
  "metric_description": "string",
  "company_id": 0,
  "company_name": "string",
  "company_slug": "string",
  "stakeholder_id": 0,
  "stakeholder_name": "string",
  "stakeholder_slug": "string",
  "country_id": 0,
  "country_name": "string",
  "country_iso_code": "string",
  "scores": [
    {
      "year": 0,
      "month": 0,
      "date": "string",
      "score": 0,
      "delta": 0,
      "significant": true
    }
  ]
}

Reputation Data Filtering

You can use from_date and to_date query parameters to filter the response and obtain only data related to a specific timeframe. You can use those query parameters optionally, using both or just one of them. You can also specify both with the same value to get data about only one month. Just make sure your to_date is greater than or equal to your from_date or you’ll get an error.

📘

Date Format

Both require "YYYY-MM" format, which is the 4-digit year followed by a hyphen and the 2-digit month.

When using these filters, the URL will look something like this:

<https://apigateway.reptrak.com/api/v1/scores/company/><company_slug>/country/<country_iso_code>/stakeholder/<stakeholder_slug>/metric/reputation?**from_date=2020-01&to_date=2020-02**
Get Metric Scores