{"openapi":"3.1.0","info":{"title":"ripdr Public API","version":"1.0.0","description":"Programmatic access to ripdr contacts, ringless voicemail, campaigns, and sequences. Requires a Scale plan and an org API key. Hosted MCP at /api/mcp works with Cursor, Codex, Claude, and other MCP clients — see /docs/public-api."},"servers":[{"url":"https://ripdr.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Org API key (prefix ripdr_live_). Create keys in Settings → Developer."}},"schemas":{"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["unauthorized","forbidden","plan_required","insufficient_credits","feature_disabled","rate_limited","validation_error","not_found","conflict","internal_error"]},"details":{"type":"object","additionalProperties":true}}},"Credits":{"type":"object","properties":{"balance":{"type":"integer","description":"Voicemail credits remaining"},"low_balance":{"type":"boolean"}}},"Contact":{"type":"object","properties":{"id":{"type":"integer"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Group":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"contact_count":{"type":"integer"}}},"Recording":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"storage_ref":{"type":"string","description":"Pass as recording on drops and campaigns"}}},"PhoneNumber":{"type":"object","properties":{"id":{"type":"integer"},"phone_number":{"type":"string"},"area_code":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","pending_voice","disabled"]},"label":{"type":"string","nullable":true},"monthly_cost":{"type":"number"},"provisioned_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AvailablePhoneNumber":{"type":"object","properties":{"phone_number":{"type":"string"},"region":{"type":"string"},"monthly_cost":{"type":"number"}}},"Campaign":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","running","paused","completed","stopped"]},"total_targets":{"type":"integer"},"delivered":{"type":"integer"},"failed":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Sequence":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","active","paused","completed","archived"]},"step_count":{"type":"integer"},"enrolled_count":{"type":"integer"}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Optional idempotency key for outreach mutations (drops, campaign start, enroll)."}}},"paths":{"/credits":{"get":{"operationId":"getCredits","summary":"Get voicemail credit balance","tags":["Account"],"responses":{"200":{"description":"Credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credits"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","tags":["Contacts"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"list_id","in":"query","schema":{"type":"integer"},"description":"Filter by group id"}],"responses":{"200":{"description":"Paginated contacts","content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"total":{"type":"integer"}}}}}}}},"post":{"operationId":"createContact","summary":"Create a contact","tags":["Contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"company":{"type":"string"},"list_id":{"type":"integer","description":"Group to add the contact to"}}}}}},"responses":{"201":{"description":"Contact created"}}}},"/contacts/{id}":{"get":{"operationId":"getContact","summary":"Get a contact","tags":["Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"description":"Not found"}}}},"/groups":{"get":{"operationId":"listGroups","summary":"List contact groups","tags":["Contacts"],"responses":{"200":{"description":"Groups","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}}}}}}},"/numbers":{"get":{"operationId":"listNumbers","summary":"List outbound phone numbers","tags":["Account"],"responses":{"200":{"description":"Phone numbers","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/PhoneNumber"}},"active_count":{"type":"integer"},"numbers_included":{"type":"integer"},"max_numbers":{"type":"integer"},"extra_numbers":{"type":"integer"}}}}}}}},"post":{"operationId":"provisionNumber","summary":"Provision an outbound phone number","tags":["Account"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"E.164 or NANP number from search_available_numbers"},"accept_billing":{"type":"boolean","description":"Required true when adding a billable extra number beyond plan included count"}}}}}},"responses":{"201":{"description":"Number provisioned"},"400":{"description":"Validation error or billing acceptance required"},"403":{"description":"Plan number limit reached"},"409":{"description":"Number already provisioned"}}}},"/numbers/available":{"get":{"operationId":"searchAvailableNumbers","summary":"Search available phone numbers to provision","tags":["Account"],"parameters":[{"name":"area_code","in":"query","schema":{"type":"string","pattern":"^\\d{3}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Available numbers","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/AvailablePhoneNumber"}},"phone_country":{"type":"string","enum":["US","CA"]}}}}}}}}},"/recordings":{"get":{"operationId":"listRecordings","summary":"List voicemail recordings","tags":["Recordings"],"responses":{"200":{"description":"Recordings","content":{"application/json":{"schema":{"type":"object","properties":{"recordings":{"type":"array","items":{"$ref":"#/components/schemas/Recording"}}}}}}}}}},"/drops":{"post":{"operationId":"sendDrop","summary":"Send a ringless voicemail to one contact","tags":["Outreach"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id","recording"],"properties":{"contact_id":{"type":"integer"},"recording":{"type":"string","description":"storage_ref from list recordings"}}}}}},"responses":{"200":{"description":"Drop dispatched"},"402":{"description":"Insufficient credits"}}}},"/missed-calls":{"post":{"operationId":"sendMissedCall","summary":"Send a missed-call touch to one contact","tags":["Outreach"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"integer"}}}}}},"responses":{"200":{"description":"Missed call dispatched"}}}},"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","tags":["Campaigns"],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}}}}}},"post":{"operationId":"createCampaign","summary":"Create a draft campaign","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"list_id":{"type":"integer"},"contact_ids":{"type":"array","items":{"type":"integer"}},"recording":{"type":"string"},"script_id":{"type":"integer"},"delay_seconds":{"type":"integer","default":30},"max_per_day":{"type":"integer","default":200},"start_hour":{"type":"integer","default":9},"end_hour":{"type":"integer","default":17},"timezone":{"type":"string"},"campaign_type":{"type":"string","enum":["voicemail","missed_call"]}}}}}},"responses":{"201":{"description":"Campaign created"}}}},"/campaigns/{id}":{"get":{"operationId":"getCampaign","summary":"Get campaign detail","tags":["Campaigns"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"include","in":"query","schema":{"type":"string","enum":["stats"]}}],"responses":{"200":{"description":"Campaign"}}}},"/campaigns/{id}/control":{"post":{"operationId":"controlCampaign","summary":"Start, pause, or stop a campaign","tags":["Campaigns"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["start","pause","stop","cancel_schedule"]}}}}}},"responses":{"200":{"description":"Campaign updated"}}}},"/sequences":{"get":{"operationId":"listSequences","summary":"List sequences","tags":["Sequences"],"responses":{"200":{"description":"Sequences","content":{"application/json":{"schema":{"type":"object","properties":{"sequences":{"type":"array","items":{"$ref":"#/components/schemas/Sequence"}}}}}}}}},"post":{"operationId":"createSequence","summary":"Create a draft sequence","tags":["Sequences"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","steps"],"properties":{"name":{"type":"string"},"list_id":{"type":"integer"},"steps":{"type":"array","items":{"type":"object","properties":{"step_type":{"type":"string","enum":["ringless_vm","missed_call","automated_email"]},"offset_days":{"type":"integer"},"recording":{"type":"string"},"email_subject":{"type":"string","description":"Required for automated_email"},"message":{"type":"string","description":"Email body for automated_email"}}}}}}}}},"responses":{"201":{"description":"Sequence created"}}}},"/sequences/{id}":{"get":{"operationId":"getSequence","summary":"Get sequence detail","tags":["Sequences"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Sequence"}}},"patch":{"operationId":"updateSequence","summary":"Update sequence or change status (activate/pause)","tags":["Sequences"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"Sequence updated"}}}},"/sequences/{id}/enroll":{"post":{"operationId":"enrollSequence","summary":"Enroll contacts into a sequence","tags":["Sequences"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"integer"}},"use_sequence_list":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"Enrollment summary"}}}}},"tags":[{"name":"Account","description":"Credits, phone numbers, and account status"},{"name":"Contacts","description":"CRM contacts and groups"},{"name":"Recordings","description":"Voicemail recordings library"},{"name":"Outreach","description":"Single-contact drops and missed calls"},{"name":"Campaigns","description":"Batch ringless voicemail campaigns"},{"name":"Sequences","description":"Multi-step voicemail cadences (Scale)"}]}