Skip to main content

Send requests for human review

Use our SDK or API to send requests for human review to gotoHuman.
Make sure you have created your customized review template in gotoHuman first.

Prepare​

Install our SDK

pip install gotohuman

Setup an environment variable with your gotoHuman API key:

GOTOHUMAN_API_KEY=YOUR_API_KEY

If you're using a .env file, don't forget to load it:

from dotenv import load_dotenv
load_dotenv()

Initialize the SDK

gotoHuman = GotoHuman()

Send request​

Create a request with the ID of the form/review template you created.
Pass the field values as shown in the review template editor (click "API Request") and optionally add some meta data.

  review = gotoHuman.create_review("YOUR_FORM_ID")
  review.add_field_data("exampleField1", value1)
  review.add_field_data("exampleField2", value2)
  review.add_meta_data("threadId", threadId)
  review.assign_to_users(["[email protected]"])
  try:
      response = review.send_request()
      print("Review sent successfully:", response)
  except Exception as e:
      print("An error occurred:", e)

formId​

The formId is the ID of your review template. You can also find it in the example SDK/API call shown for your created form/review template in the editor.

fields​

When creating your form/review template in our web app, you add different components to show dynamic content or collect user input.
These added components determine the payload that you need to send with your request.
You can find the expected format in the example SDK/API call shown for your created review template in the editor (click "API Request").

tip

Fields that you don't send any value for will be hidden.

This is handy for optional fields, but also if you need a varying number of a type of field, e.g. 1-n text fields. Then add n fields and just send values for the ones needed during this run.

For text-based fields you might in some cases not have a value for a field, but still want it to be shown to allow user input. To do that, simply send an empty string.

meta​

Add additional data to your request that you will receive back in the webhook. Read more below.

assignTo​

Assign reviewers from your organization. Read more below.

updateForReviewId​

When allowing reviewers to request a retry, you can update the review by referencing its' ID.

Example request​

Given that a urlLink (id: linkedin) and a text component (id: aiDraft) was added to a review template with ID "abcdef12345", a request might look like this:

  review = gotoHuman.create_review("abcdef12345")
  review.add_field_data("linkedin", {
      "label": "Rodrigo G.",
      "url": "https://www.linkedin.com/in/rodrigog12/"
      })
  review.add_field_data("aiDraft", "Hey there, I saw...")
  try:
      response = review.send_request()
      print("Review sent successfully:", response)
  except Exception as e:
      print("An error occurred:", e)

Image caching​

When sending images for review, you pass their public URLs in the review request. Often times these will be AI-generated images by a text-to-image service like Dall-E or Gemini. Links from these services can expire fairly quickly, often before your team is ready to review.
To ensure valid image URLs for your review and for further processing in your workflow after approval, we cache images.
In the response you'll receive short-lived download URLs to proceed with your workflow as well as the original URLs:

{
  "responseValues": {
    "imageOptions": {
      "selected": [
        "https://storage.googleapis.com/gotohuman.firebasestorage.app/..."
      ],
      "value": [
        {
          "originalUrl": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz",
          "url": "https://storage.googleapis.com/gotohuman.firebasestorage.app/...",
          "response": null
        },
        {
          "response": "approved",
          "originalUrl": "https://files.oaiusercontent.com/file-somethingelse?se=xyz",
          "url": "https://storage.googleapis.com/gotohuman.firebasestorage.app/..."
        }
      ]
    },
    ...
  },
  ...
}
info

The selected and response attributes are only present if you set up your images field to be "selectable"

Add additional meta data​

When a user is done reviewing and submits the form, you will receive a webhook. For convenience, you can add additional data to your request that you will receive back in the webhook. This could be an ID of your workflow run or of a conversation thread.
It could look like this:

  review = gotoHuman.create_review("abcdef12345")
  review.add_field_data(...)
  review.add_meta_data('threadId', 'oai-thread-443289')
  try:
      response = review.send_request()
      print("Review sent successfully:", response)
  except Exception as e:
      print("An error occurred:", e)

Assign reviewers​

To send a review request only to selected users of your team, add a list of email addresses of those users. Use the email address used when signing up for gotoHuman.

  review = gotoHuman.create_review("abcdef12345")
  review.add_field_data(...)
  review.assign_to_users(["[email protected]"])
  try:
      response = review.send_request()
      print("Review sent successfully:", response)
  except Exception as e:
      print("An error occurred:", e)

This feature is available in our Pro plan.

Preselected Options​

When using Buttons, Checkboxes, or Dropdowns in your review templates, you can also set default values that will be preselected.

  review.add_field_data("buttons", {
    "options": [
        {
            "id": "choice1",
            "label": "Choice 1"
        },
        {
            "id": "choice2",
            "label": "Choice 2"
        }
    ],
    "default": "choice2"
})
info

You can also send a default value if you defined fixed selectable options when creating your review template.

Response​

Our API responds with a 200 OK incl. a link to the pending review:

{
    "reviewId": "iVcn4fvRpPhAdVnZ7v0d",
    "gthLink": "https://app.gotohuman.com/accounts/Kb6A8ZqIaJkueTA76vv5/reviews/iVcn4fvRpPhAdVnZ7v0d"
}

If you enabled public links for your review template, this also includes a gthPublicLink.