​
Step 1: Sign Up and Get Your API Key

  1. Sign up for a Roundtable Alias account.
  2. Log in and navigate to the account dashboard.
  3. Click ”+ Create new API Key” and copy the API key.

​
Step 2: Prepare Your Survey Data

To use Roundtable Alias, you’ll need to collect the following data for each survey response:

  • participant_id: A unique identifier for the respondent
  • survey_id: A unique identifier for the survey
  • questions: An object mapping question IDs to the text of each question
  • responses: An object mapping question IDs to the respondent’s answers
  • question_histories (optional): Typing data for each question, collected using the JavaScript tracker
  • fingerprint_id (optional): A unique identifier for the device session, collected using the fingerprinting script

Ensure your data is formatted correctly before sending it to the API.

​
Step 3: Make an API Request

Send a POST request to the Roundtable Alias API with your survey data:

curl -X POST https://api.roundtable.ai/alias/v020 \
  -H 'Content-Type: application/json' \
  -H 'api_key: YOUR_API_KEY' \
  -d '{
    "fingerprint_id": "fp_789xyz",
    "participant_id": "p123",
    "survey_id": "s456",
    "questions": {
      "Q1": "How has our product improved your workflow?"
    },
    "responses": {
      "Q1": "It has made me hungry for pineapple pizza."
    },
    "question_histories": {
      "Q1": [
        [
          {"s":"I","t":0},
          {"s":"It","t":253},
          {"s":"It ","t":1290},
          {"s":"It h","t":1563},
          {"s":"It ha","t":1817},
          ...
        ]
      ]  
    }
  }'

​
Step 4: Interpret the API Response

The API will respond with a JSON object containing fraud signals and effort scores for each question:

{
  "error": false,
  "flagged": true,
  "num_checks_failed": 1,
  "response_groups": {
    "Q1": 1
  },
  "checks": {
    "Q1": [
      "Automated test: Off-topic"
    ]
  },
  "effort_ratings": {
    "Q1": 4
  },
  "typing_url": "<string>",
  "model": "alias-v020",
  "fingerprint_checks": {
    "device_id": "3pzig2Tu5GtqHY1Kh1p3",
    "duplicate": true,
    "error": false
  }
}

Review the flagged, effort_ratings, and checks fields to identify suspicious responses:

  • flagged: true if the response failed any fraud checks, false otherwise
  • effort_ratings: An object with effort scores (1-10) for each question, where 1 is low effort and 10 is high effort
  • checks: An object listing the specific fraud checks failed for each question
  • fingerprint_checks: An object listing the specific device fingerprinting checks for each session

Use this data to decide which responses to remove or investigate further.

​
Next Steps

  • Learn more about the JavaScript tracker for enhanced fraud detection.
  • Explore the API reference for details on request and response formats.
  • Read the FAQ for answers to common questions.

​
Support

If you have any questions or need assistance, our support team is here to help:

  • Email us at support@roundtable.ai.
  • Visit the Support Center for guides and troubleshooting tips.
  • Check the Status Page for updates on system performance and uptime.
Account SetupOverview