API

Integrate with Discko programmatically using our REST API.

Getting Started

Step 1: Create an API key

Log in to your Discko dashboard.
Go to Mise en place > CRM > API.
Create a new key and copy it somewhere safe. You will use it to authenticate every request.

Step 2: Make an authenticated request

Send your API key in the X-Discko-Key header.


curl -X GET "https://app.discko.io/api/v1/leads" -H "X-Discko-Key: <YOUR_API_KEY>"


// Example in Node.js / browser
const API_URL = "https://app.discko.io/api/v1";
 
async function listLeads() {
  const response = await fetch(`${API_URL}/leads`, {
    headers: {
      "X-Discko-Key": process.env.DISCKO_API_KEY
    }
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

How it works

Base URL: https://app.discko.io/api/v1
Authentication: X-Discko-Key: <YOUR_API_KEY> on every request
Dates: All timestamps use ISO 8601 (UTC), for example 2026-01-13T10:30:00Z

2025-12-18 - Standardized Error Format

All API endpoints now return a standardized response format for both success and error cases.

Success Response Format:


{
  "success": true,
  "data": [...]
}

Error Response Format:


{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is missing or invalid.",
    "details": null
  },
  "timestamp": "2025-12-18T10:30:00Z"
}

Available Error Codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	API key is missing or invalid.
`FORBIDDEN`	403	Access denied to this resource.
`LEAD_NOT_FOUND`	404	The requested lead does not exist or is not yet finished.
`VALIDATION_ERROR`	400	Request validation failed.
`INVALID_JSON`	400	Request body is not valid JSON.
`INVALID_STATUS`	400	Status must be one of: NEW, IN_PROGRESS, WON, LOST.
`INTERNAL_ERROR`	500	An unexpected error occurred.

Migration Guide:

Existing integrations must update their error parsing:

Before: response.error (string)
After: response.error.code (string) + response.error.message (string)

The success boolean field allows you to quickly distinguish success from error responses.

Endpoints

Leads

GET /api/v1/leads

Returns the list of leads collected from your forms.


curl -H "X-Discko-Key: <YOUR_API_KEY>" "https://app.discko.io/api/v1/leads"


{
  "success": true,
  "data": [
    {
      "id": "req_abc123",
      "locked": false,
      "url": "https://app.discko.io/webflow-agency/leads/req_abc123",
      "date": "2026-01-10T14:22:00.000Z",
      "status": "NEW",
      "completion": 100,
      "category": "Website",
      "contact": {
        "type": "COMPANY",
        "firstName": "Sarah",
        "lastName": "Johnson",
        "email": "sarah.johnson@retailtech.com",
        "phone": "+1-555-0142",
        "linkedin": "https://linkedin.com/in/sarahjohnson",
        "jobTitle": "Product Manager",
        "discProfile": "Dominant",
        "discProfileExplanation": "Direct communicator who values efficiency and quick decision-making. Prefers data-driven discussions and clear ROI metrics."
      },
      "company": {
        "name": "RetailTech Solutions",
        "address": "456 Commerce Ave, San Francisco, CA",
        "website": "https://retailtech-solutions.com"
      },
      "analysis": {
        "fitScore": 2,
        "fitScoreExplanation": "Perfect match: Company size, budget, and technical requirements align with typical project scope. No blocking constraints identified.",
        "intentScore": 2,
        "intentScoreExplanation": "Strong purchase intent: Budget allocated, project timeline defined, decision-maker engaged. Ready to move forward immediately.",
        "budget": "€75,000-120,000",
        "budgetExplanation": "Enterprise-grade budget for comprehensive e-commerce website with custom integrations. Q1 2026 allocation confirmed.",
        "deadline": "2026-03-31T00:00:00.000Z",
        "deadlineExplanation": "Critical: Platform needs to launch before Q2 retail season. Firm deadline with executive sponsorship.",
        "score": 8
      },
      "summary": {
        "abstract": "Enterprise B2C retailer seeking complete digital transformation with custom integration capabilities",
        "needs": "Full-stack e-commerce platform with real-time inventory sync, multi-channel fulfillment, and advanced analytics dashboard",
        "comment": "CEO recently approved digital budget. Team has previous experience with Shopify. Looking for upgrade to custom solution.",
        "categories": [
          {
            "name": "Technical Architecture",
            "description": "Required platform and infrastructure",
            "summary": [
              "Custom React-based frontend",
              "API-first backend architecture",
              "Real-time database with 99.9% uptime SLA",
              "Multi-region deployment capability"
            ]
          },
          {
            "name": "Business Requirements",
            "description": "Strategic objectives and constraints",
            "summary": [
              "Expected 40% increase in online revenue",
              "Support for 10+ concurrent payment providers",
              "Launch in time for spring promotional campaign",
              "Existing customer base of 50,000+ users to migrate"
            ]
          },
          {
            "name": "Integration Needs",
            "description": "Third-party system connections",
            "summary": [
              "SAP ERP system sync",
              "Salesforce CRM integration",
              "Klaviyo email marketing platform",
              "Shipstation fulfillment automation"
            ]
          }
        ]
      }
    }
  ]
}

GET /api/v1/leads/:id

Returns a single lead by ID with full details.


curl -H "X-Discko-Key: <YOUR_API_KEY>" "https://app.discko.io/api/v1/leads/req_xyz789"


{
  "success": true,
  "data": {
    "id": "req_xyz789",
    "locked": false,
    "url": "https://app.discko.io/creative-minds/leads/req_xyz789",
    "date": "2026-01-08T09:15:22.312Z",
    "status": "NEW",
    "completion": 100,
    "category": "Branding",
    "contact": {
      "type": "PERSON",
      "firstName": "Marcus",
      "lastName": "Chen",
      "email": "marcus.chen@startupventures.io",
      "phone": "+1-555-0187",
      "address": "789 Innovation Blvd, Austin, TX",
      "discProfile": "Influential",
      "discProfileExplanation": "Collaborative decision-maker who values relationships and consensus. Enthusiastic about innovative solutions and creative approaches."
    },
    "company": null,
    "analysis": {
      "fitScore": 2,
      "fitScoreExplanation": "Good match: Startup needs align well with our branding expertise. Creative industry focus matches our specialization.",
      "intentScore": 1,
      "intentScoreExplanation": "Moderate intent: Exploring options, gathering proposals. Budget not yet finalized but timeline is flexible for right partner.",
      "budget": "€18,000-28,000",
      "budgetExplanation": "Series A funded startup with marketing budget allocated. Prefers fixed-scope project with milestone-based payments.",
      "deadline": "2026-04-15T00:00:00.000Z",
      "deadlineExplanation": "Target launch before summer. No immediate pressure but wants branding complete before Series B investor meetings.",
      "score": 7
    },
    "summary": {
      "abstract": "Pre-Series A SaaS startup seeking cohesive brand identity and positioning strategy",
      "needs": "Complete branding package including logo design, brand guidelines, website design, and pitch deck templates for investor presentations",
      "comment": "Founder is very hands-on, wants collaborative process. Already has rough brand direction but needs professional refinement. Team of 6 people currently.",
      "categories": [
        {
          "name": "Visual Identity",
          "description": "Logo and design system creation",
          "summary": [
            "Modern, tech-forward logo reflecting AI focus",
            "Comprehensive brand guidelines document",
            "Reusable design system for web and marketing",
            "Color palette and typography standards"
          ]
        },
        {
          "name": "Brand Strategy",
          "description": "Positioning and messaging framework",
          "summary": [
            "Differentiation strategy vs. competitors",
            "Core value proposition messaging",
            "Investor pitch narrative and positioning",
            "Customer testimonial and case study formats"
          ]
        },
        {
          "name": "Launch Deliverables",
          "description": "Materials needed for go-to-market",
          "summary": [
            "Website redesign with new brand identity",
            "Pitch deck template with brand assets",
            "LinkedIn brand assets and templates",
            "Email signature and marketing templates"
          ]
        }
      ]
    }
  }
}

Error Response Example


{
  "success": false,
  "error": {
    "code": "LEAD_NOT_FOUND",
    "message": "Lead not found",
    "details": {
      "lead_id": "req_abc123"
    }
  },
  "timestamp": "2025-12-18T10:30:00Z"
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	API key is missing or invalid.
`LEAD_NOT_FOUND`	404	The requested lead does not exist or is not yet finished.

PUT /api/v1/leads/:id

Update a lead’s status.

Request Body

Field	Type	Required	Description
`status`	String	Yes	Lead status: `"NEW"`, `"IN_PROGRESS"`, `"WON"`, or `"LOST"`

Example Request


curl -X PUT "https://app.discko.io/api/v1/leads/req_xyz789" \
  -H "X-Discko-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"status": "IN_PROGRESS"}'


const API_URL = "https://app.discko.io/api/v1";
 
async function updateLeadStatus(leadId, status) {
  const response = await fetch(`${API_URL}/leads/${leadId}`, {
    method: 'PUT',
    headers: {
      "X-Discko-Key": process.env.DISCKO_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ status })
  });
  
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  
  return response.json();
}
 
// Usage
await updateLeadStatus('req_xyz789', 'IN_PROGRESS');

Response

Returns the updated lead object with the same structure as GET /api/v1/leads/:id.


{
  "success": true,
  "data": {
    "id": "req_xyz789",
    "locked": false,
    "url": "https://app.discko.io/creative-minds/leads/req_xyz789",
    "date": "2026-01-08T09:15:22.312Z",
    "status": "IN_PROGRESS",
    "completion": 100,
    "category": "Branding",
    "contact": {
      "type": "PERSON",
      "firstName": "Marcus",
      "lastName": "Chen",
      "email": "marcus.chen@startupventures.io",
      "phone": "+1-555-0187",
      "address": "789 Innovation Blvd, Austin, TX",
      "discProfile": "Influential",
      "discProfileExplanation": "Collaborative decision-maker who values relationships and consensus. Enthusiastic about innovative solutions and creative approaches."
    },
    "company": null,
    "analysis": {
      "fitScore": 2,
      "fitScoreExplanation": "Good match: Startup needs align well with our branding expertise. Creative industry focus matches our specialization.",
      "intentScore": 1,
      "intentScoreExplanation": "Moderate intent: Exploring options, gathering proposals. Budget not yet finalized but timeline is flexible for right partner.",
      "budget": "€18,000-28,000",
      "budgetExplanation": "Series A funded startup with marketing budget allocated. Prefers fixed-scope project with milestone-based payments.",
      "deadline": "2026-04-15T00:00:00.000Z",
      "deadlineExplanation": "Target launch before summer. No immediate pressure but wants branding complete before Series B investor meetings.",
      "score": 7
    },
    "summary": {
      "abstract": "Pre-Series A SaaS startup seeking cohesive brand identity and positioning strategy",
      "needs": "Complete branding package including logo design, brand guidelines, website design, and pitch deck templates for investor presentations",
      "comment": "Founder is very hands-on, wants collaborative process. Already has rough brand direction but needs professional refinement. Team of 6 people currently.",
      "categories": [
        {
          "name": "Visual Identity",
          "description": "Logo and design system creation",
          "summary": [
            "Modern, tech-forward logo reflecting AI focus",
            "Comprehensive brand guidelines document",
            "Reusable design system for web and marketing",
            "Color palette and typography standards"
          ]
        },
        {
          "name": "Brand Strategy",
          "description": "Positioning and messaging framework",
          "summary": [
            "Differentiation strategy vs. competitors",
            "Core value proposition messaging",
            "Investor pitch narrative and positioning",
            "Customer testimonial and case study formats"
          ]
        },
        {
          "name": "Launch Deliverables",
          "description": "Materials needed for go-to-market",
          "summary": [
            "Website redesign with new brand identity",
            "Pitch deck template with brand assets",
            "LinkedIn brand assets and templates",
            "Email signature and marketing templates"
          ]
        }
      ]
    }
  }
}

Error Response Examples

Invalid status value:


{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Status must be one of: NEW, IN_PROGRESS, WON, LOST.",
    "details": {
      "provided": "INVALID_VALUE",
      "allowed": ["NEW", "IN_PROGRESS", "WON", "LOST"]
    }
  },
  "timestamp": "2025-12-18T10:30:00Z"
}

Invalid JSON:


{
  "success": false,
  "error": {
    "code": "INVALID_JSON",
    "message": "Request body is not valid JSON.",
    "details": null
  },
  "timestamp": "2025-12-18T10:30:00Z"
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	API key is missing or invalid.
`LEAD_NOT_FOUND`	404	The requested lead does not exist or is not yet finished.
`INVALID_JSON`	400	Request body is not valid JSON.
`INVALID_STATUS`	400	Status must be one of: NEW, IN_PROGRESS, WON, LOST.
`VALIDATION_ERROR`	400	Request validation failed.

Source Identification

Each lead includes a source field that identifies the originating Discko organization.

This is particularly useful when integrating multiple Discko clients into the same CRM or external tool.

Field structure


{
  "source": {
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "organizationName": "WebFlow Agency"
  }
}