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
- Python SDK
- JS/TS SDK
- REST API
- Make
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()
Install our SDK
npm i gotohuman
Initialize the SDK
const gotoHuman = new GotoHuman(GOTOHUMAN_API_KEY)
Find your API key in gotoHuman.
Send requests for review with POST
requests to our API at
https://api.gotohuman.com/requestReview
.
Include an x-api-key
header with your gotoHuman API key.
In your Make scenario, add a new module, search for gotoHuman
and select our Create a Review Request
module.
When setting up a connection, enter your gotoHuman API key.
Read more in our Make integration guide.
Send request
- Python SDK
- JS/TS SDK
- REST API
- Make
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)
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 some meta data.
const reviewRequest = gotoHuman.createReview(GOTOHUMAN_FORM_ID)
.addFieldData("exampleField1", value1)
.addFieldData("exampleField2", value2)
.addMetaData("threadId", threadId)
.assignToUsers(["[email protected]"])
await reviewRequest.sendRequest()
Here is the structure of the API request.
Pass 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 some meta data.
{
"formId": "abcdef12345",
"fields": {
...
},
"meta": {
...
},
"assignTo": ["[email protected]"]
}
Select the review review template you created in gotoHuman.
It will automatically load the fields you added to your review template and allow you to enter or map values to them.
Read more in our Make integration guide.
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").
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.
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:
- Python SDK
- JS/TS SDK
- REST API
- Make
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)
const reviewRequest = gotoHuman.createReview("abcdef12345")
.addFieldData("linkedin", {
label: "Rodrigo G.",
url: "https://www.linkedin.com/in/rodrigog12/"
})
.addFieldData("aiDraft", "Hey there, I saw...")
await reviewRequest.sendRequest()
{
"formId": "abcdef12345",
"fields": {
"linkedin": {
"label": "Rodrigo G.",
"url": "https://www.linkedin.com/in/rodrigog12/"
},
"aiDraft": "Hey there, I saw..."
}
}
Our Make module will automatically show you the necessary inputs according to your review template.
Read more in our Make integration guide.
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/..."
}
]
},
...
},
...
}
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:
- Python SDK
- JS/TS SDK
- REST API
- Make
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)
const reviewRequest = gotoHuman.createReview("abcdef12345")
.addFieldData(...)
.addMetaData("threadId", "oai-thread-443289")
await reviewRequest.sendRequest()
{
"formId": "abcdef12345",
"fields": {
...
},
"meta": {
"threadId": "oai-thread-443289"
}
}
Our module shows a dedicated Meta Data
field to add key-value pairs.
Read more in our Make integration guide.
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.
- Python SDK
- JS/TS SDK
- REST API
- Make
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)
const reviewRequest = gotoHuman.createReview("abcdef12345")
.addFieldData(...)
.assignToUsers(["[email protected]"])
await reviewRequest.sendRequest()
{
"formId": "abcdef12345",
"fields": {
...
},
"assignTo": ["[email protected]"]
}
Our module shows a field Assigned Users
. Select Only selected users
and map or enter their email addresses.
Read more in our Make integration guide.
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.
- Python SDK
- JS/TS SDK
- REST API
- Make
review.add_field_data("buttons", {
"options": [
{
"id": "choice1",
"label": "Choice 1"
},
{
"id": "choice2",
"label": "Choice 2"
}
],
"default": "choice2"
})
review.addFieldData("buttons", {
"options": [
{
"id": "choice1",
"label": "Choice 1"
},
{
"id": "choice2",
"label": "Choice 2"
}
],
"default": "choice2"
})
{
...
"fields": {
...
"buttons": {
"options": [
{
"id": "choice1",
"label": "Choice 1"
},
{
"id": "choice2",
"label": "Choice 2"
}
],
"default": "choice2"
}
}
}
For any of the mentioned field types you will see a field Options to show
to optionally enter the selectable options and a field Preselected Options
to enter the preselected option(s).
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
.