{"openapi":"3.1.0","info":{"title":"Buzzlist API","version":"1.1.0","description":"Search, filter values, bulk match, lists, reveal, Hive fit, Sales Briefs and Write & Send for your own Buzzlist account. Every call uses the same plan, credits and rules as the app. Credits are used only when usable contact details are found, and never twice for the same person. Every response carries X-Buzzlist-Cost and X-Buzzlist-Credits-Used. Errors are {\"error\":{\"code\",\"message\",\"requestId\"}}; a wrong filter value adds \"suggestions\" with the three nearest real values. Lists use cursor pagination: pass nextCursor back as cursor."},"servers":[{"url":"https://app.buzzlist.io"}],"paths":{"/api/v1/me":{"get":{"operationId":"me","summary":"Who this key belongs to","description":"The account, plan, contact credits left this period, and this key's name and scopes. Cost: Free. Uses no credits.","tags":["me"],"security":[{"bearer":[]}],"x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/filters":{"get":{"operationId":"filterOptions","summary":"Filter values","description":"Every filter and extra field search accepts, with its allowed values from the live filter catalog. Add counts=true for how many people have each value, where the search service can count it cheaply. Use filter to get one filter and q to find values by words, such as filter=industry&q=dental. Cost: Free. Uses no credits.","tags":["filters"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[{"name":"source","in":"query","required":false,"description":"directory (default) or professional.","schema":{"type":"string"}},{"name":"filter","in":"query","required":false,"description":"One filter key, such as industry. Leave out for all.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Words to find values by, nearest first.","schema":{"type":"string"}},{"name":"counts","in":"query","required":false,"description":"true adds live people counts for state, size, revenue, seniority, department and industry.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/people/count":{"post":{"operationId":"countPeople","summary":"Count a market","description":"How many people match a set of filters. One number only, never people. Cost: Free. Uses no credits.","tags":["people"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["directory","professional"],"default":"directory","description":"Buzzlist searches People. \"directory\" and \"professional\" are legacy values that are still accepted; both search People."},"filters":{"type":"object","additionalProperties":true,"description":"The same filters as Find: keyword, state (two letters, commas for several), city, postal, radius (miles), title, company, industry, size, revenue, seniority, department, locationScope, and true or false contact flags businessEmail, personalEmail, mobile, directPhone, companyPhone, email, phone, linkedin. Choice filters (industry, size, revenue, seniority, department, state) take one exact value from GET /api/v1/filters. A wrong value fails with the three nearest real values."},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Extra fields as column: [values], the same extra fields Find offers. GET /api/v1/filters lists the columns and their values."}},"additionalProperties":false},"example":{"source":"directory","filters":{"state":"FL","industry":"Software Development"}}}}}}},"/api/v1/people/search":{"post":{"operationId":"searchPeople","summary":"Search people","description":"Find people with the same filters and Hive fit as the Find page. Returns names, titles, companies and which contact details exist, never emails or phone numbers. Uses no credits. Quiet anti-bot protection prevents automated scraping without limiting normal browsing. Cost: Free. Uses no credits.","tags":["people"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["directory","professional"],"default":"directory","description":"Buzzlist searches People. \"directory\" and \"professional\" are legacy values that are still accepted; both search People."},"filters":{"type":"object","additionalProperties":true,"description":"The same filters as Find: keyword, state (two letters, commas for several), city, postal, radius (miles), title, company, industry, size, revenue, seniority, department, locationScope, and true or false contact flags businessEmail, personalEmail, mobile, directPhone, companyPhone, email, phone, linkedin. Choice filters (industry, size, revenue, seniority, department, state) take one exact value from GET /api/v1/filters. A wrong value fails with the three nearest real values."},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Extra fields as column: [values], the same extra fields Find offers. GET /api/v1/filters lists the columns and their values."},"matchHive":{"type":"boolean","default":false,"description":"Rank and gate people by your approved Hive, fits first."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"cursor":{"type":"string","description":"nextCursor from the previous page."}},"additionalProperties":false},"example":{"source":"directory","filters":{"state":"FL","title":"owner"},"matchHive":true,"limit":25}}}}}},"/api/v1/companies/search":{"post":{"operationId":"searchCompanies","summary":"Search companies","description":"Companies with people who match the filters, one row per company with its facts and a few person references to reveal or save. Built on the same search as Find. Uses no credits. Quiet anti-bot protection prevents automated scraping without limiting normal browsing. Cost: Free. Uses no credits.","tags":["companies"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["directory","professional"],"default":"directory","description":"Buzzlist searches People. \"directory\" and \"professional\" are legacy values that are still accepted; both search People."},"filters":{"type":"object","additionalProperties":true,"description":"The same filters as Find: keyword, state (two letters, commas for several), city, postal, radius (miles), title, company, industry, size, revenue, seniority, department, locationScope, and true or false contact flags businessEmail, personalEmail, mobile, directPhone, companyPhone, email, phone, linkedin. Choice filters (industry, size, revenue, seniority, department, state) take one exact value from GET /api/v1/filters. A wrong value fails with the three nearest real values."},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Extra fields as column: [values], the same extra fields Find offers. GET /api/v1/filters lists the columns and their values."},"matchHive":{"type":"boolean","default":false},"limit":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Companies to return."}},"additionalProperties":false},"example":{"source":"directory","filters":{"state":"TX","industry":"Software Development"},"limit":20}}}}}},"/api/v1/people":{"get":{"operationId":"getPerson","summary":"Get a person","description":"One person by reference. Contact fields stay locked unless this account already revealed the person. Cost: Free. Uses no credits.","tags":["people"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[{"name":"reference","in":"query","required":true,"description":"A person reference from a search or a list.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/people/reveal/estimate":{"post":{"operationId":"estimateReveal","summary":"Estimate a reveal or save","description":"What revealing or saving these people would cost, before anything is charged: how many are new with usable contact details (the most credits it can use), already revealed (free), with nothing usable (free), and the credits this account has left. Nothing is revealed. Cost: Free. Uses no credits.","tags":["people"],"security":[{"bearer":[]}],"x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"references":{"type":"array","items":{"type":"string","pattern":"^(list-)?[-a-f0-9]{36}:\\d{1,5}$"},"minItems":1,"maxItems":1000,"description":"Person references from a search or a list."}},"required":["references"],"additionalProperties":false},"example":{"references":["<reference>"]}}}}}},"/api/v1/people/reveal":{"post":{"operationId":"revealPerson","summary":"Reveal a person","description":"Reveal a person's email and phone, exactly like the Reveal button. Must be asked for explicitly with confirm true. Cost: One contact credit for a person with usable contact details this account has not revealed before. Revealing again is free. Free estimate first: POST /api/v1/people/reveal/estimate.","tags":["people"],"security":[{"bearer":["reveal"]}],"x-scope":"reveal","x-cost":"per_usable_email","x-estimate":"estimateReveal","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Any unique string up to 128 characters. Retrying with the same key returns the first result instead of repeating the action, so a retry never charges twice.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string"},"confirm":{"type":"boolean","const":true,"description":"Must be true. Spending a credit is never implied."}},"required":["reference","confirm"],"additionalProperties":false},"example":{"reference":"<reference>","confirm":true}}}}}},"/api/v1/match":{"post":{"operationId":"matchRecords","summary":"Match your records","description":"Match up to 500 of your own records (email, LinkedIn URL, or name with company domain) to Buzzlist people. Returns a Buzzlist ID (stable for your account) and a confidence of high or possible for each, in the same order. An email or LinkedIn URL alone is at most possible; send the name with it for high. Reveals nothing and uses no credits. Limited to 1,000 records a minute and 25,000 a day per account, and each company domain an email is checked against counts toward the daily limit. Cost: Free. Uses no credits.","tags":["match"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","description":"Work email. A personal mailbox needs a name and company domain too."},"linkedinUrl":{"type":"string","description":"A LinkedIn profile URL, linkedin.com/in/..."},"first":{"type":"string"},"last":{"type":"string"},"name":{"type":"string","description":"Full name, instead of first and last."},"domain":{"type":"string","description":"Company website domain, such as acme.com."},"company":{"type":"string","description":"Company name, when the domain is unknown. Lower confidence."}},"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["records"],"additionalProperties":false},"example":{"records":[{"email":"jane.doe@acme.com"},{"linkedinUrl":"https://www.linkedin.com/in/jane-doe"},{"first":"Sam","last":"Lee","domain":"coastalair.com"}]}}}}}},"/api/v1/companies/similar":{"post":{"operationId":"similarCompanies","summary":"Find similar companies","description":"Companies like one company (give its website) or like your booked meetings and won deals (wins true), with why each matches and a Find link. Never reveals or saves anyone. Cost: Free. Uses no credits.","tags":["companies"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Company website, such as acme.com."},"wins":{"type":"boolean","description":"true uses your wins as the seed instead of one company."},"source":{"type":"string","enum":["directory","professional"],"default":"directory","description":"Buzzlist searches People. \"directory\" and \"professional\" are legacy values that are still accepted; both search People."}},"additionalProperties":false},"example":{"domain":"acme.com"}}}}}},"/api/v1/lists":{"get":{"operationId":"listLists","summary":"List saved lists","description":"Your saved lists, newest first. Cost: Free. Uses no credits.","tags":["lists"],"security":[{"bearer":["lists:read"]}],"x-scope":"lists:read","x-cost":"free","parameters":[{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createList","summary":"Create a list","description":"Create a saved list with people from a search. Send an Idempotency-Key so a retry returns the same list. Cost: On paid plans, one contact credit per new person with usable contact details saved, as in the app. Free plan lists use no credits. Free estimate first: POST /api/v1/people/reveal/estimate.","tags":["lists"],"security":[{"bearer":["lists:write"]}],"x-scope":"lists:write","x-cost":"per_usable_email","x-estimate":"estimateReveal","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string up to 128 characters. Retrying with the same key returns the first result instead of repeating the action, so a retry never charges twice.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"references":{"type":"array","items":{"type":"string","pattern":"^(list-)?[-a-f0-9]{36}:\\d{1,5}$"},"minItems":1,"maxItems":1000,"description":"Person references from a search or a list."}},"required":["title","references"],"additionalProperties":false},"example":{"title":"Florida owners","references":["<reference>"]}}}}}},"/api/v1/lists/people":{"get":{"operationId":"readList","summary":"Read a list","description":"The people on one list. Revealed people include their contact details. Cost: Free. Uses no credits.","tags":["lists"],"security":[{"bearer":["lists:read"]}],"x-scope":"lists:read","x-cost":"free","parameters":[{"name":"id","in":"query","required":true,"description":"List id.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1 to 100, default 50.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lists/add":{"post":{"operationId":"addToList","summary":"Add people to a list","description":"Add people to an existing list. People already on it are not added twice, and people already revealed are never charged again. Cost: On paid plans, one contact credit per new person with usable contact details saved. People already revealed are free. Free estimate first: POST /api/v1/people/reveal/estimate.","tags":["lists"],"security":[{"bearer":["lists:write"]}],"x-scope":"lists:write","x-cost":"per_usable_email","x-estimate":"estimateReveal","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string up to 128 characters. Retrying with the same key returns the first result instead of repeating the action, so a retry never charges twice.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string"},"references":{"type":"array","items":{"type":"string","pattern":"^(list-)?[-a-f0-9]{36}:\\d{1,5}$"},"minItems":1,"maxItems":1000,"description":"Person references from a search or a list."}},"required":["listId","references"],"additionalProperties":false},"example":{"listId":"<list id>","references":["<reference>"]}}}}}},"/api/v1/fit":{"post":{"operationId":"checkFit","summary":"Check Hive fit","description":"Score up to 100 people of your own against your approved Hive: fit, worth a look, or left out and why. Cost: Free. Uses no credits.","tags":["fit"],"security":[{"bearer":["search:read"]}],"x-scope":"search:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"first":{"type":"string"},"last":{"type":"string"},"title":{"type":"string"},"company":{"type":"string"},"industry":{"type":"string"},"employees":{"type":"string","description":"Company size, such as \"11-50\""},"state":{"type":"string"},"city":{"type":"string"}},"additionalProperties":false},"minItems":1,"maxItems":100},"consumer":{"type":"boolean","default":false}},"required":["records"],"additionalProperties":false},"example":{"records":[{"title":"Owner","company":"Coastal Air","industry":"HVAC","employees":"11-50","state":"FL"}]}}}}}},"/api/v1/hive":{"get":{"operationId":"getHive","summary":"Read your Hiveprint","description":"Who you sell to (targeting), strong and weak fit patterns, and example customers. Cost: Free. Uses no credits.","tags":["hive"],"security":[{"bearer":["hive:read"]}],"x-scope":"hive:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lineup":{"get":{"operationId":"lineupStatus","summary":"Buzz lineup","description":"Who is being written, who is up next, what is ready, what went out today and what needs you. Read only. Cost: Free. Uses no credits.","tags":["lineup"],"security":[{"bearer":["lineup:read"]}],"x-scope":"lineup:read","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/briefs/estimate":{"post":{"operationId":"estimateBrief","summary":"Estimate a Sales Brief","description":"Whether this plan includes Sales Briefs and what one would use, before anything starts. Cost: Free. Uses no credits.","tags":["briefs"],"security":[{"bearer":[]}],"x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"website":{"type":"string"}},"additionalProperties":false},"example":{"website":"acme.com"}}}}}},"/api/v1/briefs":{"post":{"operationId":"startBrief","summary":"Start a Sales Brief","description":"Start a Sales Brief on a prospect company, written from your approved Company DNA. Returns a job id; check it with GET /api/v1/briefs?job=. Must be asked for explicitly with confirm true. Cost: One Sales Brief, exactly like Briefs in the app. Free estimate first: POST /api/v1/briefs/estimate.","tags":["briefs"],"security":[{"bearer":["briefs:write"]}],"x-scope":"briefs:write","x-cost":"per_brief","x-estimate":"estimateBrief","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Any unique string up to 128 characters. Retrying with the same key returns the first result instead of repeating the action, so a retry never charges twice.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"website":{"type":"string","maxLength":300},"contactName":{"type":"string","maxLength":200},"contactTitle":{"type":"string","maxLength":200},"meetingNotes":{"type":"string","maxLength":6000},"confirm":{"type":"boolean","const":true}},"required":["website","confirm"],"additionalProperties":false},"example":{"website":"acme.com","confirm":true}}}}},"get":{"operationId":"briefStatus","summary":"Sales Brief status","description":"One Sales Brief job: status, stage and, once ready, the brief id to open in Buzzlist. Cost: Free. Uses no credits.","tags":["briefs"],"security":[{"bearer":["briefs:write"]}],"x-scope":"briefs:write","x-cost":"free","parameters":[{"name":"job","in":"query","required":true,"description":"Job id from starting the brief.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/launches/estimate":{"post":{"operationId":"estimateLaunch","summary":"Estimate Write & Send","description":"What writing emails for this many people would cost before anything starts. Nothing is written or sent. Cost: Free. Uses no credits.","tags":["launches"],"security":[{"bearer":["emails:write"]}],"x-scope":"emails:write","x-cost":"free","parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":1000}},"required":["count"],"additionalProperties":false},"example":{"count":50}}}}}},"/api/v1/launches":{"post":{"operationId":"startLaunch","summary":"Start Write & Send","description":"Buzz writes emails for a saved list. With send false the launch stops at drafts for you to review in Buzzlist. With send true (needs the send scope) it sends automatically once the emails are ready, with every guard the app uses. Must be asked for explicitly with confirm true. Cost: Writing uses the plan's writing credits, charged per person as each email is written, exactly like Write & Send in the app. Free estimate first: POST /api/v1/launches/estimate.","tags":["launches"],"security":[{"bearer":["emails:write"]}],"x-scope":"emails:write","x-cost":"per_email_written","x-estimate":"estimateLaunch","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Any unique string up to 128 characters. Retrying with the same key returns the first result instead of repeating the action, so a retry never charges twice.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string"},"name":{"type":"string","maxLength":120},"count":{"type":"integer","minimum":1,"maximum":1000},"all":{"type":"boolean"},"send":{"type":"boolean","default":false},"confirm":{"type":"boolean","const":true}},"required":["listId","confirm"],"additionalProperties":false},"example":{"listId":"<list id>","count":50,"send":false,"confirm":true}}}}},"get":{"operationId":"launchStatus","summary":"Launch status","description":"One launch by id, or your launches when no id is given: status, people written, held and sent. Cost: Free. Uses no credits.","tags":["launches"],"security":[{"bearer":["emails:write"]}],"x-scope":"emails:write","x-cost":"free","parameters":[{"name":"id","in":"query","required":false,"description":"Launch id. Leave out to list launches.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-Buzzlist-Cost":{"description":"The cost model of this endpoint: free, per_usable_email, per_brief or per_email_written.","schema":{"type":"string"}},"X-Buzzlist-Credits-Used":{"description":"Contact credits this call used.","schema":{"type":"integer"}},"X-Buzzlist-Briefs-Used":{"description":"Sales Briefs this call used.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Quote this when asking for help.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request, invalid_filter_value, unknown_filter or confirmation_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope or plan_required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"in_progress, conflict or never_contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"idempotency_mismatch or hive_not_ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or cap_reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key from Account > Developers. Scopes: search:read, lists:read, lists:write, reveal, hive:read, lineup:read, briefs:write, emails:write, send"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"filter":{"type":"string","description":"invalid_filter_value and unknown_filter: the filter that was wrong."},"suggestions":{"type":"array","items":{"type":"string"},"description":"invalid_filter_value and unknown_filter: the nearest real values, closest first."},"retryAfterSeconds":{"type":"integer"}},"required":["code","message"]}},"required":["error"]}},"x-error-codes":{"invalid_request":"The request or its arguments are not valid.","invalid_filter_value":"A filter value is not one Buzzlist has. error.suggestions holds the three nearest real values.","unknown_filter":"A filter or field name does not exist. error.suggestions holds the nearest real names.","unauthorized":"The key is missing, revoked or expired.","insufficient_scope":"The key does not have the scope this endpoint needs.","plan_required":"The plan does not include this.","insufficient_credits":"No contact credits remain.","not_found":"Not found in this account.","rate_limited":"Too many calls. Wait and retry after the Retry-After seconds.","idempotency_mismatch":"This Idempotency-Key was used with a different request.","conflict":"The list changed at the same time. Retry.","in_progress":"A request with this Idempotency-Key is still running.","confirmation_required":"Pass confirm true to spend credits or start writing.","cap_reached":"This key's daily reveal cap is reached.","hive_not_ready":"Approve your Hive in Buzzlist first.","never_contact":"Everyone chosen is on a Never contact list or marked do not contact. Nothing was revealed, saved or charged.","unavailable":"Buzzlist could not finish this. Retry shortly."}}}