Create leads
Files one public form in the deployment's own CRM.
POST /v1/marketing/leads
| Address | https://api.hanzo.ai/v1/marketing/leads |
| Method | POST |
| Operation | post_marketing_leads |
| Auth | Authorization: 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).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
address | body | marketing.Address | — | |
address.city | body | string | — | City is the city. |
address.country | body | string | — | Country is the country. |
address.postcode | body | string | — | Postcode is the postal code. |
address.region | body | string | — | Region is the state, province or region. |
address.street | body | string | — | Street is the street address, on one line. |
amount | body | any | — | 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. |
answers | body | marketing.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[].answer | body | string | — | Answer is what the person said; options they picked are joined by commas. |
answers[].question | body | string | — | Question is the question as the form asked it, on one line. |
campaign | body | marketing.Tags | — | |
campaign.utm_campaign | body | string | — | Name is utm_campaign: the campaign's own name. |
campaign.utm_content | body | string | — | Content is utm_content: which link of several in one placement. |
campaign.utm_medium | body | string | — | Medium is utm_medium: the kind of placement, such as cpc or email. |
campaign.utm_source | body | string | — | Source is utm_source: where the link was placed, such as google. |
campaign.utm_term | body | string | — | Term is utm_term: the paid search term. |
company | body | string | — | Company is the person's company. |
consent | body | boolean | — | Consent is the applicant ticking "Keep me posted about roles and news at Hanzo. |
country | body | string | — | Country is where the person is. |
coupon | body | string | — | Coupon is the offer code the visitor's page held: letters, digits, dash and underscore, at most 32. |
department | body | string | — | Department is the opening's department. |
email | body | string | — | Email is where sales replies: the person's work email. |
entity | body | string | — | Entity is the legal name of the entity an investor invests through; empty, they invest in their own name. |
job | body | string | — | Job is the opening a careers form applies to, by its id on the careers page (senior-backend-engineer). |
links | body | string[] | — | Links are https addresses the applicant gave: a portfolio, a profile, a site. |
name | body | string | — | Name is the person's name. |
need | body | string | — | Need is what the person wants from sales, in their own words. |
payment | body | string | — | Payment is how an order the form files would be paid: "card" or "invoice" (a bank transfer against an invoice sales sends). |
phone | body | string | — | Phone is an investor's phone number: 3 to 20 digits, an optional leading +, and any spaces, dots, dashes or brackets between them. |
program | body | string | — | Program is the program the person applies to: beta, research or partner. |
resume | body | string | — | Resume is an https address the applicant gave for their resume. |
resume_file | body | string | — | ResumeFile is the key POST /v1/marketing/leads/resume handed out for the resume the applicant uploaded. |
role | body | string | — | Role is the person's job title. |
size | body | string | — | Size is the company's headcount band: 1-49, 50-249, 250-999, 1000-4999 or 5000+. |
source | body | string | — | Source is the page the form was filed from, such as hanzo.ai/contact-sales. |
title | body | string | — | Title is the investor's title at Entity, as the SAFE's signature block names it. |
upgrade | body | string | — | Upgrade is the handle of the organization an order upgrades. |
visit | body | marketing.Visit | — | |
visit.cid | body | string | — | Cid is the Google Analytics client id, the last two fields of _ga. |
visit.clicked | body | integer (int64) | — | Clicked is when the page captured the click, in unix seconds. |
visit.consent | body | string | — | Consent is the Cookie Preferences the visitor granted, comma separated: any of analytics, marketing and ads. |
visit.fbc | body | string | — | Fbc is Meta's click cookie, fb.1.<ms>.<fbclid>. |
visit.fbclid | body | string | — | Fbclid is the Meta click id the visitor arrived with. |
visit.fbp | body | string | — | Fbp is Meta's browser cookie, fb.1.<ms>.<random>. |
visit.gbraid | body | string | — | Gbraid is the Google Ads click id for an iOS app click. |
visit.gclid | body | string | — | Gclid is the Google Ads click id the visitor arrived with. |
visit.tags | body | string | — | Tags is which of the page's ad tags already saw this lead: ga, meta. |
visit.url | body | string | — | URL is the page the form was filed from, in full. |
visit.userAgent | body | string | — | UserAgent is the visitor's browser, as navigator.userAgent reads. |
visit.wbraid | body | string | — | Wbraid is the Google Ads click id for an iOS web click. |
Response
| Status | Body | Meaning |
|---|---|---|
201 | marketing.Lead | created |
default | problem-details | refused |
201 body — 4 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
lead | body | string | — | Lead is the reference of what was filed: "lead_" and 24 hex characters for a lead, "cand_" and 24 for a job application. |
offer | body | string | — | Offer says what an application's code did: "mailed", a new code went to the address; "held", the address already holds one. |
sent | body | boolean | — | 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. |
stage | body | string | — | Stage is where the lead stands. |
Failure carries the platform error shape — see Errors.
Examples
hanzo marketing leads createimport { 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"
}
}
}'