Getting Started

Calling the API

There a several ways you can make calls to the Receptiviti API. How you choose to do so is dependent upon your experience and comfort level in the different tools available. Some of the most commonly used methods are as follows:

The Receptiviti CSV Upload Tool

This is a basic user interface we provide where you can upload a CSV file of text to have it scored and returned as a separate CSV. This is an easy way for people with no programming experience to use the API. Note that you will need an account to use the CSV upload tool. You can register for an account here.

Note: The CSV you process must consist of two columns: one is a unique identifier and the other the text sample. It cannot not have a header row. It cannot exceed 25,000 rows or 10MB. If you are saving it from Excel, use the CSV UTF-8 option. See the example below for a CSV that analyzes the text samples of three different people:

CSV example

Postman

Postman is a popular API collaboration platform widely used by developers. It allows you to make calls to endpoints you specify by authorizing your credentials and using your own input data. You can use Postman with or without an account — the Scratch Pad feature allows you to make API calls without an account, but if you want to create a Workspace and save your API calls, you will need an account. Either way, you will need to download the Postman desktop app.

To get started using Postman (with an account):

  1. In Postman, create a new Workspace, then open a new tab.

  2. In the Postman input fields, configure the following:

    1. From the drop-down menu, select POST.

    2. In the URL field, enter https://api.receptiviti.com/v1/framework for a single text sample call, or https://api.receptiviti.com/v1/framework/bulk for a call with more than one text sample.

      Postman Workspace

      Note: The score endpoint is deprecated and is not recommended for new users of the Receptiviti API as of late 2022.

    3. Click the Authorization header, and in the Type drop-down, select Basic Auth.

    4. To the right of the drop-down, in the Username field, paste your API Key, and in the Password field, paste your API Secret. Both are found in your dashboard.

      Postman Workspace 2

    5. Click the Body header, then click the raw button, and then select JSON from the drop-down menu.

    6. In the content window below the settings you just configured, paste your text sample and be sure to have it formatted in JSON. (Note that these instructions specify a call with a single text sample.)

      Postman Workspace 3

    7. Finally, click Send.

You should see a successful response (Status: 200 OK) that lists the scores of the measures associated with your Receptiviti account in the Body tab of the Response window, which appears just below where you pasted your sample. If you are getting an error, be sure that you selected POST as the call method, that the body is properly formatted JSON, and that the endpoint is exactly as it appears above in step 2.2.

For more in-depth information about the Receptiviti API endpoints, as well as code samples for calling the API programmitcally, see the API Reference section. For more information about interpreting the responses, see the Frameworks section.

cURL

To use cURL to make a single text sample call to the Receptiviti API, you can use the following syntax in your Terminal, replacing <YOUR_API_KEY>:<YOUR_API_SECRET> with your actual credentials, as well as adding your text sample to the "content" section:

curl --location --request \
POST 'https://api.receptiviti.com/v1/framework' \
-u <YOUR_API_KEY>:<YOUR_API_SECRET> \
--header 'Content-Type: application/json' \
--data-raw '{
    "request_id": "req-1",
    "content": "my text sample...."
}'

Python

To use Python to make a single text sample call to the Receptiviti API, you can use the following syntax in your Terminal, replacing api_key and api_secret with your actual credentials, as well as adding your text sample to the "content" section:

import json
import requests


url = 'https://api.receptiviti.com/v1/framework'
api_key = <YOUR_API_KEY>
api_secret = <YOUR_API_SECRET>
data = json.dumps({
  'request_id': 'req-1',
  'content': 'my text sample....'
})
resp = requests.post(url, auth=(api_key, api_secret), data=data)
print(json.dumps(resp.json(), indent=4, sort_keys=True))

For more in-depth information about making calls to the Receptiviti API and interpreting responses, see the API Reference section.

Previous
The Receptiviti API - Documentation Home
Next
Normed vs. Dictionary Measures