{"openapi":"3.1.0","info":{"title":"Crustomer API","version":"1.0.0","description":"Add Instagram leads to a Crustomer workspace and read them back. Made for AI agents such as Meta's Muse. Each workspace makes its own API key under Settings → API keys. Leads land in the CRM only; the API never messages anyone."},"externalDocs":{"url":"https://crustomer.us/developers"},"servers":[{"url":"https://crustomer.us/api/v1"}],"security":[{"bearer":[]}],"paths":{"/leads":{"post":{"operationId":"createLead","summary":"Add a lead (or up to 100)","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":120},"description":"A retry with the same key within a day returns the first answer instead of saving again."},{"name":"X-Batch","in":"header","schema":{"type":"string","maxLength":60},"description":"A run label, saved on the lead and its history."}],"description":"Adds a lead. If the workspace already has someone with that Instagram username, that lead is updated instead (blanks filled, follower count and vetted refreshed, new notes added; the team's own name, bio and status are kept) and the response is 200. Send {\"leads\": [...]} to add up to 100 at once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LeadInput"},{"type":"object","required":["leads"],"properties":{"leads":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/LeadInput"}}}}]}}}},"responses":{"200":{"description":"Already there; updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadSaved"}}}},"201":{"description":"Added. For a batch: at least one was new.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadSaved"}}}},"400":{"description":"The body isn't valid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The workspace is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A field needs fixing (see error.fields). Nothing was saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Couldn't check the key just now; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listLeads","summary":"List leads, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."},{"name":"vetted","in":"query","schema":{"type":"boolean"}},{"name":"created_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"updated_after","in":"query","schema":{"type":"string","format":"date-time"},"description":"Poll for changes since your last run."},{"name":"q","in":"query","schema":{"type":"string","minLength":2},"description":"Searches name, username and bio."},{"name":"username","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated: New, Contacted, Ghost, Interested, Confirmed Attendee, Sponsor Signed, Booked, Not Interested, Dead."},{"name":"contact_type","in":"query","schema":{"type":"string"},"description":"Comma-separated lead types, e.g. the looking_for list from /criteria."},{"name":"vetted_set","in":"query","schema":{"type":"boolean"},"description":"false: not checked yet."},{"name":"has_bio","in":"query","schema":{"type":"boolean"}},{"name":"profile_status","in":"query","schema":{"type":"string","enum":["ok","private","missing"]}}],"responses":{"200":{"description":"A page of leads.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last page."}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A query parameter needs fixing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/criteria":{"get":{"operationId":"getCriteria","summary":"What this business counts as a good lead","description":"Set by the business in its setup guide. Read it before vetting or looking for leads. If set is false, don't vet yet.","responses":{"200":{"description":"The criteria.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/Criteria"},{"type":"null"}]},"business":{"type":"object","properties":{"name":{"type":"string"},"industry":{"type":"string"},"specialty":{"type":["string","null"]}}},"summary":{"type":"string","description":"The same rules in plain English."},"set":{"type":"boolean"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/follow-ups":{"get":{"operationId":"listFollowUps","summary":"Who to message today","description":"The same list as the app's Follow-ups page. Suggestions only; people are messaged by hand.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Queues: hot (waiting on you), waiting, cold, revive.","content":{"application/json":{"schema":{"type":"object","properties":{"counts":{"type":"object"},"data":{"type":"object","properties":{"hot":{"type":"array"},"waiting":{"type":"array"},"cold":{"type":"array"},"revive":{"type":"array"}}}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/notes":{"get":{"operationId":"listLeadNotes","summary":"A lead's history, newest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"History entries.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"404":{"description":"No such lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addLeadNote","summary":"Add a note to a lead's history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":120},"description":"A retry with the same key within a day returns the first answer instead of saving again."},{"name":"X-Batch","in":"header","schema":{"type":"string","maxLength":60},"description":"A run label, saved on the lead and its history."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","maxLength":4000}}}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Note"}}}}}},"404":{"description":"No such lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The note needs fixing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}":{"patch":{"operationId":"updateLead","summary":"Update a lead","description":"Status, vetted (with vetted_reason), next follow-up, lead type and profile status. full_name, bio, follower_count and source_account only fill blanks; notes are appended once.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":120},"description":"A retry with the same key within a day returns the first answer instead of saving again."},{"name":"X-Batch","in":"header","schema":{"type":"string","maxLength":60},"description":"A run label, saved on the lead and its history."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["New","Contacted","Ghost","Interested","Confirmed Attendee","Sponsor Signed","Booked","Not Interested","Dead"]},"vetted":{"type":"boolean"},"vetted_reason":{"type":"string","maxLength":300,"description":"Required when vetted is sent."},"ideal_customer":{"type":["string","null"],"description":"A name from /criteria ideal_customers."},"next_follow_up_at":{"type":["string","null"],"format":"date"},"contact_type":{"type":"string","description":"One of the business's lead types."},"profile_status":{"type":"string","enum":["ok","private","missing"]},"full_name":{"type":"string"},"bio":{"type":"string"},"follower_count":{"type":["integer","string"]},"source_account":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"The updated lead.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}}}}}},"404":{"description":"No such lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A field needs fixing. Nothing was saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getLead","summary":"Get one lead","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The lead.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}}}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No lead with that id in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A workspace API key (starts with crsk_). 120 requests a minute per key."}},"schemas":{"LeadInput":{"type":"object","properties":{"instagram_username":{"type":"string","description":"Instagram username, with or without @. Required unless profile_url is sent.","example":"mayatorres"},"profile_url":{"type":"string","format":"uri","description":"instagram.com profile link. Used to fill instagram_username if it's missing.","example":"https://www.instagram.com/mayatorres/"},"full_name":{"type":"string","maxLength":200,"example":"Maya Torres"},"bio":{"type":"string","maxLength":2000,"description":"Their profile bio or a short summary.","example":"Miami · house music · yoga teacher"},"follower_count":{"type":["integer","string"],"description":"Whole number, or text like \"12.4k\".","example":12400},"source_account":{"type":"string","description":"The account, hashtag or place the lead was found through.","example":"reefrave"},"vetted":{"type":"boolean","description":"True once someone (or the agent) has checked they're a good fit.","example":false},"notes":{"type":"string","maxLength":5000,"description":"Added to the lead's notes. On an existing lead, appended once."}}},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"instagram_username":{"type":"string"},"profile_url":{"type":"string","format":"uri"},"full_name":{"type":"string"},"bio":{"type":["string","null"]},"follower_count":{"type":["integer","null"]},"source_account":{"type":["string","null"]},"vetted":{"type":"boolean"},"vetted_reason":{"type":["string","null"]},"vetted_at":{"type":["string","null"],"format":"date-time"},"vetted_by":{"type":["string","null"]},"profile_status":{"type":["string","null"],"enum":["ok","private","missing",null]},"ideal_customer":{"type":["string","null"]},"notes":{"type":["string","null"]},"status":{"type":"string","description":"Where they are with the team: New, Contacted, Interested…"},"location":{"type":["string","null"]},"last_contacted_at":{"type":["string","null"],"format":"date"},"next_follow_up_at":{"type":["string","null"],"format":"date"},"agent_batch":{"type":["string","null"]},"category":{"type":["string","null"]},"contact_type":{"type":["string","null"]},"source":{"type":["string","null"],"description":"How the lead got here: api, instagram, import or manual."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Criteria":{"type":"object","properties":{"looking_for":{"type":"array","items":{"type":"string"}},"areas":{"type":"array","items":{"type":"string"},"description":"First choice."},"also_areas":{"type":"array","items":{"type":"string"},"description":"Fine, lower priority."},"ages":{"type":"object","description":"For people only, not businesses.","properties":{"min":{"type":["integer","null"]},"max":{"type":["integer","null"]}}},"groups":{"type":"object","description":"What this business calls each group, e.g. Attendees and Sponsors.","properties":{"customer":{"type":"string"},"partner":{"type":"string"}}},"ideal_customers":{"type":"array","description":"In priority order.","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["customer","partner"],"description":"customer: people who buy or attend. partner: businesses that sponsor or partner."},"who":{"type":["string","null"]},"followers_min":{"type":["integer","null"]},"followers_max":{"type":["integer","null"]},"age_min":{"type":["integer","null"]},"age_max":{"type":["integer","null"]},"areas":{"type":"array","items":{"type":"string"}},"interests":{"type":"array","items":{"type":"string"}},"good_signs":{"type":"array","items":{"type":"string"}},"lead_type":{"type":["string","null"]}}}},"interests":{"type":"array","items":{"type":"string"}},"followers":{"type":"object","properties":{"min":{"type":["integer","null"]},"max":{"type":["integer","null"]}}},"good_signs":{"type":"array","items":{"type":"string"}},"red_flags":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"Note":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"logged_at":{"type":"string","format":"date-time"},"type":{"type":"string"},"note":{"type":["string","null"]},"actor":{"type":["string","null"],"description":"Who wrote it (an API key's name), or null for the team."},"batch":{"type":["string","null"]}}},"LeadSaved":{"type":"object","description":"One lead: { data, created }. A batch: { data: [lead + created], created, updated }.","properties":{"data":{},"created":{}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}