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").

info

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.

webhookUrl​

In most cases you'll enter a static webhook URL in the review template. But in some cases you might want to pass along a dynamic/adhoc webhook URL with each request using this attribute (This is what our n8n integration does under the hood).

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.

Images / Videos​

Storage / Caching​

When your review request includes images or videos, gotoHuman automatically stores these files for you so they are always accessible via our CDN. This ensures reliable access to your content throughout the review process and beyond without the need to set up extra storage.

This is particularly relevant for AI-generated content where source URLs from OpenAI or Gemini can expire quickly, often before your team is ready to review. By storing the files, we ensure persistent access to your media content for both the review process and any subsequent workflow steps after approval.

File URLs

When you provide URLs to images or videos in your review request, gotoHuman will automatically download and store these files. Use the url property for image fields:

{
  "fields": {
    "imageFieldId": [
      {
        "url": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz"
      },
      {
        "url": "https://files.oaiusercontent.com/file-somethingelse?se=xyz"
      }
    ]
  }
}

In the response you'll receive both the original URLs and our CDN 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"

Base64 encoded images

Instead of providing URLs, you can also send base64 encoded images directly in your request. Use the base64 property for image fields:

{
  "fields": {
    "imageFieldId": [
      {
        "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k="
      },
      ...
    ],
    ...
  },
  ...
}

Files (binary)

For direct file uploads, you can use our dedicated upload endpoint before requesting a review:

Endpoint: https://api.gotohuman.com/uploadFiles
Method: POST
Content-Type: multipart/form-data

Upload your binary files as form data, and optionally include a config field for image editing options (see Image editing section below).

Image editing​

You can configure on-the-fly image resizing and cropping for image fields by including a config object with resize options.
Use it if any following workflow steps (e.g. video generation based on reference image) or publishing targets (e.g. social media) require a specific image size or aspect ratio.

{
  "fields": {
    "imageFieldId": {
      "options": [
        {
          "url": "https://www.imgs.com/img.jpg"
        },
        {
          "url": "https://www.imgs.com/img2.jpg"
        }
      ],
      "config": {
        "resize": {
          "width": 400,
          "height": 800,
          "fit": "cover"
        }
      }
    },
    ...
  },
  ...
}

Resize options:

  • width, height: Target dimensions in pixels
  • fit: How to fit the image - cover, contain, fill, inside, outside
  • position: Where to position the image when using cover or contain - top, right top, right, right bottom, bottom, left bottom, left, left top, centre
  • background: Background color for contain fit (e.g., "#ffffff", "red", {r: 255, g: 0, b: 0, alpha: 1})
  • withoutEnlargement: Boolean to prevent upscaling
  • withoutReduction: Boolean to prevent downscaling

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.

This feature is available with our paid plans.

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"
}