Hanzo Docs
Sign inAPI key

Import forms

Brings responses made elsewhere into a form, keeping when each was made, a batch of at most 500 at a time.

POST /v1/form/forms/{id}/import

Form → · All API references → · Get started →

Addresshttps://api.hanzo.ai/v1/form/forms/{id}/import
MethodPOST
Operationimport_form_responses
AuthAuthorization: Bearer $HANZO_API_KEY

Brings responses made elsewhere into a form, keeping when each was made, a batch of at most 500 at a time. Each is keyed by its external id (on a subscribe form, by its address), so a batch sent again, or an import resumed from any point, makes nothing twice. Each answer is read against its field as a submission's is; a required field may be unanswered. With file, each new response is also filed in the CRM at the time it was made; nothing is mailed and no webhook is told. An org admin only.

Request

18 fields, body application/json (required).

FieldInTypeRequiredDescription
idpathstringyesID is the form's id or slug, from the path.
filebodyboolean—File also files each new response in the CRM, at the time it was made.
idbodystring—ID is the form's id or slug, from the path.
responsesbodyform.Imported[]—Responses are the responses, at most 500.
responses[].answersbodyform.Answer[]—Answers are its answers, each read against the form's field as a submission's is; a required field may be unanswered.
responses[].answers[].booleanbodyboolean—
responses[].answers[].choicesbodystring[]—
responses[].answers[].datebodystring—
responses[].answers[].fieldbodystring—Field is the ref of the field answered.
responses[].answers[].numberbodynumber (double)—
responses[].answers[].textbodystring—
responses[].answers[].typebodystring—Type is the field's type.
responses[].atbodystring—At is when it was made, RFC 3339.
responses[].emailbodystring—Email is the address it was from, when the source knew one.
responses[].externalbodystring—External is its id where it was made: at most 200 characters, and the response's key, so importing it again is the same response.
responses[].hiddenbodyobject—Hidden are values it carried, by the names the form declares.
responses[].hidden.*bodystring—
responses[].sourcebodystring—Source is where it was made, at most 100 characters: commerce, a list's name.

Response

StatusBodyMeaning
200form.Importsok
defaultproblem-detailsrefused

200 body — 5 fields.

FieldInTypeAlwaysDescription
createdbodyinteger (int64)—Created counts the responses made new.
existingbodyinteger (int64)—Existing counts the ones already held: imported before, or the same subscriber.
failedbodyform.ImportFailure[]—Failed are the ones refused, with why.
failed[].externalbodystring—
failed[].reasonbodystring—

Failure carries the platform error shape — see Errors.

Examples

hanzo form forms import <id>
import { Configuration, FormApi } from 'hanzoai';

const api = new FormApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.importFormResponses({ id: 'id', file: false, id: "<id>" });
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import FormApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = FormApi(client).import_form_responses(id='id', file=False, id="<id>")
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.FormAPI.ImportFormResponses(context.Background()).Execute()
if err != nil {
	return err
}
use hanzo_client::apis::{configuration::Configuration, form_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = form_api::import_form_responses(&cfg, Default::default()).await?;
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.FormApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new FormApi(client).importFormResponses();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/form/forms/<id>/import \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "file": false,
       "id": "<id>"
     }'

Tool form, op import_form_responses — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "form",
         "arguments": {
           "op": "import_form_responses",
           "input": {
             "id": "<id>",
             "file": false
           }
         }
       }
     }'

Form API · All Hanzo APIs · Interactive reference

Was this page useful?
Broken link or missing step? Drop it in #docs on Discord or open a PR.
PreviousGet publicNextList deliveries