Change Stage
Move projects through your investment pipeline by changing their stage. Stages represent pipeline positions (e.g., Inbox, Screening, Due Diligence, Portfolio) and each stage automatically maps to the correct underlying status and phase.
How It Works
Changing a project’s stage is a two-step process:
- Fetch available stages — call
GET /api/integration/stagesto get the list of stages configured for your organization - Set the stage — call
POST /api/integration/project/stagewith the project ID and the desired stage ID
Each stage includes a name, order (display position), and its associated projectstatusId and projectphaseId — these are applied automatically when you set the stage.
Step 1: Get Available Stages
GET https://api.kruncher.ai/api/integration/stages
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Your API key (format: YOUR_API_KEY) |
Response (200 OK)
{
"metadata": {
"code": "1000",
"title": "Successful",
"description": ""
},
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Inbox",
"order": 1,
"projectstatusId": "status-uuid-here",
"projectphaseId": "phase-uuid-here"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Screening",
"order": 2,
"projectstatusId": "status-uuid-here",
"projectphaseId": "phase-uuid-here"
},
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "Due Diligence",
"order": 3,
"projectstatusId": "status-uuid-here",
"projectphaseId": "phase-uuid-here"
}
]
}Stages are returned sorted by order. The id field is what you pass to the next endpoint.
Step 2: Set Project Stage
POST https://api.kruncher.ai/api/integration/project/stage
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Your API key (format: YOUR_API_KEY) |
Content-Type | Yes | Must be application/json |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
projectId | string (UUID) | Yes | The project to update |
projectstageId | string (UUID) | Yes | Stage ID from GET /api/integration/stages |
Response (200 OK)
{
"metadata": {
"code": "1000",
"title": "Successful",
"description": ""
},
"data": {
"projectId": "521a93a6-091d-4943-ba13-7c1a654a14ae",
"projectstageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}Code Examples
JavaScript/TypeScript
Basic
const API_KEY = "YOUR_API_KEY_HERE";
const BASE_URL = "https://api.kruncher.ai/api/integration";
const headers = {
"Authorization": API_KEY,
"Content-Type": "application/json"
};
// Step 1: Fetch available stages
const stagesResponse = await fetch(`${BASE_URL}/stages`, { headers });
const stagesResult = await stagesResponse.json();
const stages = stagesResult.data;
console.log("Available stages:");
stages.forEach(s => console.log(` ${s.order}. ${s.name} (${s.id})`));
// Step 2: Move project to a stage
const targetStage = stages.find(s => s.name === "Screening");
const response = await fetch(`${BASE_URL}/project/stage`, {
method: "POST",
headers,
body: JSON.stringify({
projectId: "521a93a6-091d-4943-ba13-7c1a654a14ae",
projectstageId: targetStage.id
})
});
const result = await response.json();
console.log("Stage updated:", result);Python
Basic
import requests
API_KEY = "YOUR_API_KEY_HERE"
BASE_URL = "https://api.kruncher.ai/api/integration"
headers = {
"Authorization": API_KEY,
"Content-Type": "application/json"
}
# Step 1: Fetch available stages
stages_response = requests.get(f"{BASE_URL}/stages", headers=headers)
stages_response.raise_for_status()
stages = stages_response.json()["data"]
print("Available stages:")
for s in stages:
print(f" {s['order']}. {s['name']} ({s['id']})")
# Step 2: Move project to a stage
target_stage = next(s for s in stages if s["name"] == "Screening")
response = requests.post(
f"{BASE_URL}/project/stage",
headers=headers,
json={
"projectId": "521a93a6-091d-4943-ba13-7c1a654a14ae",
"projectstageId": target_stage["id"]
}
)
response.raise_for_status()
print("Stage updated:", response.json())cURL
Get Stages
# Fetch all available stages
curl -s -X GET "https://api.kruncher.ai/api/integration/stages" \
-H "Authorization: YOUR_API_KEY_HERE" \
| jq '.data[] | {id: .id, name: .name, order: .order}'Error Responses
400 Bad Request
{
"metadata": {
"code": "102",
"title": "Error",
"description": "Invalid input parameter"
}
}Returned when projectId or projectstageId is missing or not a valid UUID.
401 Not Authorized
{
"metadata": {
"code": "106",
"title": "Error",
"description": "Not authorized to access this project"
}
}Returned when the project does not belong to your organization or you don’t have access.
404 Not Found
{
"metadata": {
"code": "122",
"title": "Error",
"description": "API key not found"
}
}Returned when the API key in the Authorization header is invalid.
Best Practices
- Cache stages — the list of stages rarely changes, so fetch it once and reuse. Refresh periodically (e.g., every hour) or when you get unexpected errors.
- Use stage names for readability — look up stages by
namein your code instead of hardcoding UUIDs, since stage IDs may differ between environments. - Validate before updating — confirm the stage ID exists in your stages list before calling the POST endpoint.
Related Endpoints
- Find Companies — get project IDs
- Webhooks — receive notifications on pipeline changes
- Create Company — add new projects to your pipeline
Need Help?
- Custom stages? Configure your pipeline stages in Kruncher Settings
- Webhook issues? Check Webhook Guide
- Bulk updates? Use the code examples above to loop through multiple projects