{"openapi":"3.1.0","info":{"title":"Jounce API","version":"1.0.0","description":"Manage your Jounce audience from your own code. Upserts are idempotent by email; an update never changes a contact’s status; suppression is honored on every write."},"servers":[{"url":"https://api.jounce.com/v1"}],"security":[{"bearer":[]},{"basic":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"jk_live_…"},"basic":{"type":"http","scheme":"basic","description":"API key as the username, blank password."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}},"SegmentRef":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Subscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained"]},"source":{"type":["string","null"],"enum":["manual","csv","form","api",null]},"first_name":{"type":"string"},"last_name":{"type":"string"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentRef"}},"custom_fields":{"type":"object","additionalProperties":{"type":["string","boolean"]}},"consent_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"SubscriberInput":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string","maxLength":256},"last_name":{"type":"string","maxLength":256},"custom_fields":{"type":"object","maxProperties":30,"additionalProperties":{"type":["string","boolean"]}},"segment_ids":{"type":"array","maxItems":50,"items":{"type":"string"}},"double_optin":{"type":"boolean","default":false,"description":"Create only — pending + confirmation email."},"optin_ip":{"type":"string"},"optin_timestamp":{"type":"string","format":"date-time"}}},"Segment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":["string","null"]},"subscribers_count":{"type":"integer"},"created_at":{"type":["string","null"],"format":"date-time"}}},"CustomField":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}},"Form":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"published":{"type":"boolean"},"type":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"}}},"Automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["subscriber.created","subscriber.updated","subscriber.unsubscribed","subscriber.bounced","subscriber.complained","subscriber.added_to_segment","subscriber.removed_from_segment","list.imported"]}},"disabled":{"type":"boolean"},"secret":{"type":"string","description":"Present ONLY in the creation response."},"created_at":{"type":["string","null"],"format":"date-time"},"last_success_at":{"type":["string","null"],"format":"date-time"},"last_failure_at":{"type":["string","null"],"format":"date-time"}}}}},"paths":{"/me":{"get":{"summary":"The account and key behind your credentials","responses":{"200":{"description":"OK"}}}},"/subscribers":{"get":{"summary":"List subscribers","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained"]}},{"name":"segment_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string"},"description":"Exact-match search. Returns the matching subscriber in data, or an empty data array — never 404. Other filters and pagination are ignored."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscriber"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}},"post":{"summary":"Create or update a subscriber by email","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriberInput"}}}},"responses":{"200":{"description":"Updated"},"201":{"description":"Created"},"422":{"description":"Refused (invalid_email, disposable_domain, no_confirmation_email…)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/subscribers/batch":{"post":{"summary":"Create or update up to 100 subscribers (per-item results)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscribers":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/SubscriberInput"}}}}}}},"responses":{"200":{"description":"Per-item results — one bad row never fails the batch"}}}},"/subscribers/{id_or_email}":{"get":{"summary":"One subscriber","parameters":[{"name":"id_or_email","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/subscribers/{id_or_email}/segments":{"post":{"summary":"Add to segments","parameters":[{"name":"id_or_email","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"segment_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Remove from segments","parameters":[{"name":"id_or_email","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/subscribers/{id_or_email}/unsubscribe":{"post":{"summary":"Unsubscribe from all sends (idempotent; records addresses not yet in Jounce)","parameters":[{"name":"id_or_email","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/segments":{"get":{"summary":"List segments","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}},"post":{"summary":"Create a segment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}}}}},"responses":{"201":{"description":"Created"}}}},"/segments/{id}":{"get":{"summary":"One segment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/custom-fields":{"get":{"summary":"List the custom-field registry","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}},"post":{"summary":"Register a custom field","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label"],"properties":{"label":{"type":"string"},"key":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}}},"/forms":{"get":{"summary":"List forms","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Form"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}}},"/forms/{id}":{"get":{"summary":"One form","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/automations":{"get":{"summary":"List automations (read-only)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}}},"/webhooks":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}}},"post":{"summary":"Create a webhook endpoint (the secret is returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["post_url","events"],"properties":{"name":{"type":"string"},"post_url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["subscriber.created","subscriber.updated","subscriber.unsubscribed","subscriber.bounced","subscriber.complained","subscriber.added_to_segment","subscriber.removed_from_segment","list.imported"]}}}}}}},"responses":{"201":{"description":"Created — includes `secret`"}}}},"/webhooks/{id}":{"get":{"summary":"One webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"put":{"summary":"Update a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Delete a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}}}}