Moves one Startup Program application through the pipeline.

PATCH /v1/crm/applications/{id}

CRM → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/crm/applications/{id}`
Method	`PATCH`
Operation	`patch_crm_applications_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Moves one Startup Program application through the pipeline. The move is recorded on the application's timeline, attributed to the calling staff user: it may advance exactly one stage, go back to any earlier stage, reject from any non-rejected stage, or reopen a rejected application to applied; anything else is refused. Rejecting requires a reason. A note with no stage change is still recorded.

Request

5 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the application to move, from the path.
`id`	body	string	—	ID is the application to move, from the path.
`note`	body	string	—	Note is a free-text comment recorded on the timeline, with or without a stage change.
`reason`	body	string	—	Reason records WHY, and is required to reject.
`stage`	body	string	—	Stage is the stage to move to: applied, screened, qualified, credits-offered, onboarded or rejected.

Response

Status	Body	Meaning
`200`	ProgramApplication	ok

200 body — 31 fields.

Field	In	Type	Always	Description
`company`	body	string	—	Company is the applicant's company name.
`companyId`	body	string	—	CompanyID is the CRM Company minted for this lead at intake, so the startup also appears in the org's standard CRM tabs.
`contactId`	body	string	—	ContactID is the CRM Contact minted for this lead at intake.
`contactName`	body	string	—	ContactName is the person who applied.
`createdAt`	body	integer	—	CreatedAt is the unix second the application arrived.
`email`	body	string	—	Email is the applicant's email — half of the (email, company) key a resubmission refreshes instead of duplicating.
`events`	body	StageEvent[]	—	Events is the append-only stage-transition log, oldest first.
`events[].at`	body	integer	—	At is the unix second of the move.
`events[].by`	body	string	—	By is who moved it: "system" for intake and the AI auto-advance, else the validated staff user id.
`events[].from`	body	string	—	From is the stage moved out of; empty on the intake event that opens the log.
`events[].note`	body	string	—	Note is the free-text comment recorded with the move.
`events[].to`	body	string	—	To is the stage moved into.
`id`	body	string	—	ID is the server-minted application id ("appl_" + 128 random bits).
`metadata`	body	object	—	Metadata is the FULL submitted form, every field, including the arrays the promoted columns above do not carry (tier1Investors, useCases) and the deterministic…
`metadata.*`	body	object	—
`reason`	body	string	—	Reason is why the application was rejected, required to reject.
`role`	body	string	—	Role is the applicant's role at their company.
`screen`	body	ScreenResult	—
`screen.draftReply`	body	string	—	DraftReply is a suggested email reply for staff to edit and send.
`screen.error`	body	string	—	Error says why a failed screen failed — no AI gateway configured, a gateway error, or a reply that carried no parseable JSON.
`screen.model`	body	string	—	Model is the LLM the screen ran on.
`screen.score`	body	integer	—	Score is the model's 0..100 fit score, clamped to that range.
`screen.screenedAt`	body	integer	—	ScreenedAt is the unix second the screen finished (0 while pending).
`screen.status`	body	string	—	Status is the screen's state: pending \| done \| failed.
`screen.suggestedCredits`	body	integer	—	SuggestedCredits is the recommended credit grant in USD, snapped to the nearest allowed rung: 0 \| 5000 \| 25000 \| 50000 \| 150000.
`screen.summary`	body	string	—	Summary is the model's short assessment of the application.
`screen.tier1Backed`	body	string	—	Tier1Backed is the model's read on tier-1 backing, normalized to "yes", "no" or "unclear" (anything it cannot resolve reads "unclear").
`stage`	body	string	—	Stage is the pipeline stage: applied, screened, qualified, credits-offered, onboarded or rejected.
`tier1`	body	boolean	—	Tier1 is whether the applicant is tier-1 backed, derived deterministically at intake from the submitted fund list — independent of the AI screen.
`updatedAt`	body	integer	—	UpdatedAt is the unix second of the last write.
`website`	body	string	—	Website is the applicant's website as submitted.

Failure carries the platform error shape — see Errors.

Examples

hanzo crm applications update <id>

import { Configuration, CrmApi } from 'hanzoai';

const api = new CrmApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.patchCrmApplicationsById({ id: 'id', id: "<id>", note: "<note>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import CrmApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CrmApi(client).patch_crm_applications_by_id(id='id', id="<id>", note="<note>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.CrmAPI.PatchCrmApplicationsById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, crm_api};

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

let result = crm_api::patch_crm_applications_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.CrmApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new CrmApi(client).patchCrmApplicationsById();

curl -X PATCH https://api.hanzo.ai/v1/crm/applications/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "id": "<id>",
       "note": "<note>"
     }'

The door reaches crm through the crm tool, which names its 20 operations with its own verbs — this one among them, under a name only the door 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_crm_applications"
         }
       }
     }'

CRM API · All Hanzo APIs · Interactive reference

Moves one Startup Program application through the pipeline.

Request

Response

Examples

On this page