API Integration Best Practices

Before integrating with the API, it’s highly recommended to first build and run a job within our graphical user interface. Once you’ve run a job successfully and are satisfied with the results, the job launch process can be automated. Find the full Figure Eight API Request Guide here.

To run more data through your existing job template, you have the option to either 1) upload more rows to an existing job 2) copy the job and upload data to the newly created job ID. It’s important to note that the maximum amount of data that can be uploaded to a single job is 250K rows.

When integrating it’ll be important to understand how you’ll want to receive the results, below are the two most common methods:

  • Webhook Integration
    • This route allows rows to be sent automatically to a webhook as soon as they finalize
    • Allows you to get results back in real time
      • Note: A web application will need to be set up to accept POST requests from Figure Eight.
  • Standard API Integration
    • This route allows you to pull finalized rows via an API request in batches

Copying a job

  • API Command to copy existing job with only test questions:
    • curl -X GET "{job_id}/copy.json?key={api_key}&gold=true"
      • Note: the job ID that is being copied from is required
    • The "gold=true" parameter tells the API to copy the job with test questions only. There are variations of this request that can be used to copy a job with all of its rows (source data + test questions) or none of its rows. If you intend to copy without rows and then upload test questions, see this request.
    • The API responds with a JSON structure of the job. Included in the JSON will be an attribute called "id" which is the job ID of the newly created copy. Save this ID and use it in requests moving forward.

Upload Data



  • It is recommended to monitor the job in the UI for highly missed test questions to ensure the job is running smoothly. After the initial monitoring, pinging the job with the following request will show how many rows have finalized and how many are still remaining:
    • curl -X GET{job_id}/ping.json?key={api_key}
      • The response will look like the following and when “needed_judgments” = 0, the job is finished:
        • {"golden_units":30,"all_units":20703,"ordered_units":20673,"completed_units_estimate":17887,"needed_judgments":8469,"all_judgments":88984,"tainted_judgments":24825,"completed_gold_estimate":25,"completed_non_gold_estimate":17862}


  • For Standard API integration:
    • Download a CSV of any report using this request:
    • Here are the available report types:
      • full - Returns the Full report containing every judgment
      • aggregated - Returns the Aggregated report containing the aggregated response for each row
      • json - Returns the JSON report containing the aggregated response, as well as the individual judgments
    • Once downloaded, the file will need to be unzipped.
  • When using a webhook:
    • When a row finalizes in your job, meaning it has collected the required number of judgments in order to finalize, Figure Eight will send a POST request to the webhook URL containing all of the information associated with that row. Please see this article for more information about Figure Eight Webhook Basics.


Was this article helpful?
0 out of 0 found this helpful

Have more questions? Submit a request
Powered by Zendesk