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​

In your n8n workflow, add our verified gotoHuman community node.

Read more in our n8n integration guide.

Send request​

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 n8n integration guide.

Request attributes​

formId​

The formId is the ID of your review template. You can find it in the template details and the example request.

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 request shown for your created review template (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 (AI Retries / Prompt Edits), 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:

Our n8n node will automatically show you the necessary inputs according to your review template.

Read more in our n8n 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 download URLs to proceed with your workflow as well as the original URLs:

{
  "responseValues": {
    "imageOptions": {
      "selected": [
        "https://cdn1.gotohuman.com/..."
      ],
      "value": [
        {
          "originalUrl": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz",
          "url": "https://cdn1.gotohuman.com/...",
          "response": null
        },
        {
          "response": "approved",
          "originalUrl": "https://files.oaiusercontent.com/file-somethingelse?se=xyz",
          "url": "https://cdn1.gotohuman.com/..."
        }
      ]
    },
    ...
  },
  ...
}
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:

When using our sendAndWait n8n node, you shouldn't need to add meta data as you will still have access to data from previous nodes in the same workflow run.

Read more in our n8n 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.

Our n8n node shows a field Assigned Users. Select All Users or alternatively Only selected users and map or enter their email addresses.

Read more in our n8n integration guide.

Selectable options & default values​

When using Buttons, Checkboxes, or Dropdowns in your review templates, you can either define a fixed set of selectable options or send dynamic options with each request.
Either way, you can also set default values that will be preselected.

Read our n8n integration guide about how to send dynamic options and defaults.

Workflow metadata​

If your workflow includes manual triggers and/or multiple review steps, you can send workflow metadata, so we can provide reviewers with an overview and navigation for each run of the workflow.

gotoHuman - workflow navi

In the Meta Data field, enter JSON with a field _gthWorkflow holding the workflow information:

{
  "_gthWorkflow": {
    "runId": "1234567890",
    "runName": "My Workflow",
    "prevSteps": [
      "1234567890"
    ]
  }
}
  • runId is a unique identifier for the current run of the workflow. You need to incl. the same runId in each review request of the same run to link them together. If you incl. _gthWorkflow but no runId (even {}), and also for manual triggers, we'll create a new runId for you and return it in the review response as workflowRunId so you can reference it in your subsequent review requests.
  • runName is an optional name identifying the current run of the workflow (for display purposes). You can set or overwrite it in any of your review requests during a run.
  • prevSteps is an array of reviewIds of any previous gotoHuman review step(s) (omit for first step). We need this to know how the steps are linked together.

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.