{"openapi":"3.0.3","info":{"title":"LeadGrid API","version":"1.0.0","description":"Public REST API for LeadGrid.io. Authenticate with a Bearer token obtained from Settings → API. API access requires the Growth plan."},"servers":[{"url":"https://leadgrid.io/api/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Use an API key from your LeadGrid settings: `Authorization: Bearer lg_live_xxx`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"Meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}},"Dossier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"flow_id":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string","enum":["candidate","sales"]},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"contact_person":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","won","lost","archived"]},"current_stage_id":{"type":"string","format":"uuid","nullable":true},"assigned_to":{"type":"string","format":"uuid","nullable":true},"deal_size":{"type":"number","nullable":true},"deal_currency":{"type":"string","nullable":true},"intake_notes":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","organization_id","type","name","status"]},"Stage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"flow_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer"},"deadline_days":{"type":"integer","nullable":true},"color":{"type":"string"}}},"Flow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organization_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["candidate","sales"]},"is_default":{"type":"boolean"},"stages":{"type":"array","items":{"$ref":"#/components/schemas/Stage"}}}},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"dossier_id":{"type":"string","format":"uuid"},"content":{"type":"string"},"is_internal":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/dossiers":{"get":{"summary":"List dossiers","description":"Returns dossiers for the authenticated organization. Requires scope `dossiers:read`.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["candidate","sales"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","won","lost","archived"]}},{"name":"stage_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":25,"maximum":100}}],"responses":{"200":{"description":"List of dossiers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dossier"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}}},"post":{"summary":"Create a dossier","description":"Create a dossier. Requires scope `dossiers:write`. Send `application/json` for a plain create, or `multipart/form-data` to create the dossier **and** attach a PDF CV in a single atomic call — if the upload fails, the dossier is rolled back and nothing is persisted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","enum":["candidate","sales"]},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"contact_person":{"type":"string","nullable":true},"flow_id":{"type":"string","format":"uuid","description":"Defaults to your org's default flow for this type."},"assigned_to":{"type":"string","format":"uuid","nullable":true},"intake_notes":{"type":"string","nullable":true},"deal_size":{"type":"number","nullable":true},"deal_currency":{"type":"string","nullable":true}}}},"multipart/form-data":{"schema":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","enum":["candidate","sales"]},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"role":{"type":"string","nullable":true},"contact_person":{"type":"string","nullable":true},"flow_id":{"type":"string","format":"uuid"},"assigned_to":{"type":"string","format":"uuid","nullable":true},"intake_notes":{"type":"string","nullable":true},"deal_size":{"type":"number","nullable":true},"deal_currency":{"type":"string","nullable":true},"cv":{"type":"string","format":"binary","description":"Optional PDF CV (max 10 MB). Attached to the dossier on create."}}}}}},"responses":{"201":{"description":"Dossier created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dossier"}}}}}}}}},"/dossiers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get dossier","description":"Requires scope `dossiers:read`.","responses":{"200":{"description":"A single dossier.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dossier"}}}}}}}},"patch":{"summary":"Update dossier","description":"Requires scope `dossiers:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["active","won","lost","archived"]},"assigned_to":{"type":"string","format":"uuid","nullable":true},"current_stage_id":{"type":"string","format":"uuid","nullable":true},"intake_notes":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Updated dossier."}}},"delete":{"summary":"Archive dossier","description":"Soft-delete: sets status to `archived`. Requires scope `dossiers:write`.","responses":{"200":{"description":"Archived."}}}},"/dossiers/{id}/cv":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Attach a PDF CV to a dossier","description":"Upload a PDF (max 10 MB) and store it on the dossier. Accepts either multipart/form-data with a `cv` file field, or `application/pdf` with the PDF bytes as the raw body. Requires scope `dossiers:write`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["cv"],"properties":{"cv":{"type":"string","format":"binary"}}}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Updated dossier with cv_url pointing to the stored file."},"400":{"description":"Invalid body or not a PDF."},"404":{"description":"Dossier not found."},"413":{"description":"File too large (max 10 MB)."},"415":{"description":"Unsupported Content-Type."}}}},"/dossiers/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List notes","description":"Requires scope `notes:read`.","responses":{"200":{"description":"Notes."}}},"post":{"summary":"Add a note","description":"Requires scope `notes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"is_internal":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Note created."}}}},"/flows":{"get":{"summary":"List flows","description":"Requires scope `flows:read`.","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["candidate","sales"]}}],"responses":{"200":{"description":"List of flows with stages."}}}},"/flows/{id}/stages":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List flow stages","description":"Requires scope `flows:read`.","responses":{"200":{"description":"Stages sorted by position."}}}}}}