Create leads

Files one public form in the deployment's own CRM.

POST /v1/marketing/leads

Addresshttps://api.hanzo.ai/v1/marketing/leads
MethodPOST
Operationpost_marketing_leads
AuthAuthorization: Bearer $HANZO_API_KEY

Files one public form in the deployment's own CRM. A sales inquiry or a program application becomes a lead: the person, and the form on their timeline with every answer, the campaign and coupon its page carried; it is stated on the event plane and mailed to the brand's sales mailbox. A body naming a job opening becomes a candidate and its form, mailed to the brand's careers mailbox and stated nowhere. Program investor is an investor and their form at status submitted, stated nowhere, mailed to nobody, and sent a SAFE to sign (sent says whether it went). No account is needed: every record lands in the brand's org. A person signed in who applies to the beta also opens the products in beta (the CRM) for the org they act in. Answers 201 with an opaque reference.

A person signed in files under the address their token was issued to: a body naming another address is 400, and so is a sign-in issued with no address. An order that upgrades an organization names it in upgrade, sent signed in and acting in that organization (X-Org-Id) as its owner or an admin, and the lead records that verified handle; anyone else naming one is 403. payment is card or invoice, and an Enterprise inquiry paying by invoice is also stated as invoice_requested. X-Idempotency-Key makes a retry safe: the same key from the same address answers the same reference, and files, mails and states nothing twice; the same key sent with another form is 409. The sales mail states the payment and the verified organization to upgrade beside the answers.

A brand org whose Base cannot hold the CRM answers 503, a caller past ten forms in an hour 429, a body over 16 KiB 413, and a missing or malformed email 400 — in that order; an investor's form then answers 400 for its name, its amount ("The minimum investment is $25,000."), its address, entity, title and phone, in that order.

Request

50 fields, body application/json (required).

FieldInTypeRequiredDescription
addressbodymarketing.Address—
address.citybodystring—City is the city.
address.countrybodystring—Country is the country.
address.postcodebodystring—Postcode is the postal code.
address.regionbodystring—Region is the state, province or region.
address.streetbodystring—Street is the street address, on one line.
amountbodyany—Amount is what an investor invests, as a JSON number of whole US dollars: at least 25000, which a smaller amount is refused as "The minimum investment is $25,000.", and at most 1000000000.
answersbodymarketing.Answer[]—Answers is the application question by question, as the form asked it: at most 40, each question clipped at 200 characters and each answer at 2 KiB.
answers[].answerbodystring—Answer is what the person said; options they picked are joined by commas.
answers[].questionbodystring—Question is the question as the form asked it, on one line.
campaignbodymarketing.Tags—
campaign.utm_campaignbodystring—Name is utm_campaign: the campaign's own name.
campaign.utm_contentbodystring—Content is utm_content: which link of several in one placement.
campaign.utm_mediumbodystring—Medium is utm_medium: the kind of placement, such as cpc or email.
campaign.utm_sourcebodystring—Source is utm_source: where the link was placed, such as google.
campaign.utm_termbodystring—Term is utm_term: the paid search term.
companybodystring—Company is the person's company.
consentbodyboolean—Consent is the applicant ticking "Keep me posted about roles and news at Hanzo.
countrybodystring—Country is where the person is.
couponbodystring—Coupon is the offer code the visitor's page held: letters, digits, dash and underscore, at most 32.
departmentbodystring—Department is the opening's department.
emailbodystring—Email is where sales replies: the person's work email.
entitybodystring—Entity is the legal name of the entity an investor invests through; empty, they invest in their own name.
jobbodystring—Job is the opening a careers form applies to, by its id on the careers page (senior-backend-engineer).
linksbodystring[]—Links are https addresses the applicant gave: a portfolio, a profile, a site.
namebodystring—Name is the person's name.
needbodystring—Need is what the person wants from sales, in their own words.
paymentbodystring—Payment is how an order the form files would be paid: "card" or "invoice" (a bank transfer against an invoice sales sends).
phonebodystring—Phone is an investor's phone number: 3 to 20 digits, an optional leading +, and any spaces, dots, dashes or brackets between them.
programbodystring—Program is the program the person applies to: beta, research or partner.
resumebodystring—Resume is an https address the applicant gave for their resume.
resume_filebodystring—ResumeFile is the key POST /v1/marketing/leads/resume handed out for the resume the applicant uploaded.
rolebodystring—Role is the person's job title.
sizebodystring—Size is the company's headcount band: 1-49, 50-249, 250-999, 1000-4999 or 5000+.
sourcebodystring—Source is the page the form was filed from, such as hanzo.ai/contact-sales.
titlebodystring—Title is the investor's title at Entity, as the SAFE's signature block names it.
upgradebodystring—Upgrade is the handle of the organization an order upgrades.
visitbodymarketing.Visit—
visit.cidbodystring—Cid is the Google Analytics client id, the last two fields of _ga.
visit.clickedbodyinteger (int64)—Clicked is when the page captured the click, in unix seconds.
visit.consentbodystring—Consent is the Cookie Preferences the visitor granted, comma separated: any of analytics, marketing and ads.
visit.fbcbodystring—Fbc is Meta's click cookie, fb.1.<ms>.<fbclid>.
visit.fbclidbodystring—Fbclid is the Meta click id the visitor arrived with.
visit.fbpbodystring—Fbp is Meta's browser cookie, fb.1.<ms>.<random>.
visit.gbraidbodystring—Gbraid is the Google Ads click id for an iOS app click.
visit.gclidbodystring—Gclid is the Google Ads click id the visitor arrived with.
visit.tagsbodystring—Tags is which of the page's ad tags already saw this lead: ga, meta.
visit.urlbodystring—URL is the page the form was filed from, in full.
visit.userAgentbodystring—UserAgent is the visitor's browser, as navigator.userAgent reads.
visit.wbraidbodystring—Wbraid is the Google Ads click id for an iOS web click.

Response

StatusBodyMeaning
201marketing.Leadcreated
defaultproblem-detailsrefused

201 body — 4 fields.

FieldInTypeAlwaysDescription
leadbodystring—Lead is the reference of what was filed: "lead_" and 24 hex characters for a lead, "cand_" and 24 for a job application.
offerbodystring—Offer says what an application's code did: "mailed", a new code went to the address; "held", the address already holds one.
sentbodyboolean—Sent says whether an investor's SAFE went out for signature from Hanzo eSign: false when the deployment sends none yet, or eSign did not take it, and the investor is filed either way.
stagebodystring—Stage is where the lead stands.

Failure carries the platform error shape — see Errors.

Examples

hanzo marketing leads create
import { Configuration, MarketingApi } from 'hanzoai';

const api = new MarketingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postMarketingLeads({ address: {"city":"<city>","country":"<country>","postcode":"<postcode>","region":"<region>"}, amount: "<amount>" });
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketingApi(client).post_marketing_leads(address={"city":"<city>","country":"<country>","postcode":"<postcode>","region":"<region>"}, amount="<amount>")
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

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

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

let result = marketing_api::post_marketing_leads(&cfg, Default::default()).await?;
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketingApi;

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

var result = new MarketingApi(client).postMarketingLeads();
curl -X POST https://api.hanzo.ai/v1/marketing/leads \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "address": {
         "city": "<city>",
         "country": "<country>",
         "postcode": "<postcode>",
         "region": "<region>"
       },
       "amount": "<amount>"
     }'

MCP reaches marketing through the marketing tool, which names its 82 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_marketing_audiences"
         }
       }
     }'

Marketing 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.