Skip to Content
Docs are evolving — expect frequent updates.
CompanyChange Stage

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:

  1. Fetch available stages — call GET /api/integration/stages to get the list of stages configured for your organization
  2. Set the stage — call POST /api/integration/project/stage with 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

HeaderRequiredDescription
AuthorizationYesYour API key (format: YOUR_API_KEY)

Response (200 OK)

CODE
{
  "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

HeaderRequiredDescription
AuthorizationYesYour API key (format: YOUR_API_KEY)
Content-TypeYesMust be application/json

Request Body

FieldTypeRequiredDescription
projectIdstring (UUID)YesThe project to update
projectstageIdstring (UUID)YesStage ID from GET /api/integration/stages

Response (200 OK)

CODE
{
  "metadata": {
    "code": "1000",
    "title": "Successful",
    "description": ""
  },
  "data": {
    "projectId": "521a93a6-091d-4943-ba13-7c1a654a14ae",
    "projectstageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Code Examples

JavaScript/TypeScript

CODE
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

CODE
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

CODE
# 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

CODE
{
  "metadata": {
    "code": "102",
    "title": "Error",
    "description": "Invalid input parameter"
  }
}

Returned when projectId or projectstageId is missing or not a valid UUID.

401 Not Authorized

CODE
{
  "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

CODE
{
  "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 name in 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.

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
Last updated on