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.

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 will be removed in version 2 of the Receptiviti API; release date expected 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.

Jupyter Notebooks Demo Projects

To walk through a demo project to make calls to the Receptiviti API using both a single call and a bulk call, go here.

For a demo project where you can see how to make calls to the API that include different scores and formatting options, go here.