{"openapi":"3.1.0","info":{"title":"Apresly Public API","version":"1.0.0","description":"Start in Integrations → API: publish a campaign, create a named key, copy the secret once, list campaigns, register an email, then use lookup for reminders. Keys can be renamed and independently revoked; revocation does not invalidate previously issued offer links. API access is included in every plan, while existing countdown-tool availability and suspended-account restrictions still apply.\n\nSend Authorization: Bearer <YOUR_API_KEY> from your server only. Never put keys in query strings, browser code, or logs. The request body and personalized response contain email identity: handle them privately. API requests do not send emails. Test with your own published campaign and test email: this is a real registration, not a sandbox.\n\nDefault limit: 120 authorized requests per UTC minute per account across all keys. Page size: 1–100 (default 50). JSON body maximum: 16 KiB. For 429 respect Retry-After; for 503/timeouts retry with increasing backoff. A timeout does not imply rollback. The created field does not guarantee exactly-once email sending in your system.\n\nOffer links personalize the existing CTA and are not secret single-use tokens: forwarding can share identity. CTA redirects to the configured page/proxy, and the existing installed widget enforces HIDE/ZERO/REDIRECT according to campaign settings. The API does not replace the widget. Constructing URLs does not activate an offer; opening a GIF or CTA follows existing campaign behavior. Published timer URLs use the requested en/pl language. Changes to campaign pages/settings can change links in later responses.\n\nUse the host serving this document with the relative /api/public/v1 server path. Request history in the panel covers the last 7 days and excludes payloads, emails and secrets; audit-storage outages may leave gaps."},"servers":[{"url":"/api/public/v1","description":"Current Apresly server"}],"security":[{"ApiKey":[]}],"paths":{"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List your campaigns","description":"Available in every plan. Lists drafts and published campaigns by ascending id; each API key covers all campaigns of its owning account. Use nextAfterId as afterId for the next page.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"afterId","in":"query","schema":{"type":"integer","minimum":1}},{"name":"isDraft","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Campaign page","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"},"example":{"items":[{"id":42,"name":"Post-purchase upsell","type":{"id":1,"name":"Campaign type"},"isDraft":false}],"nextAfterId":null}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}},"/campaigns/{campaignId}/leads":{"post":{"operationId":"registerLead","summary":"Register an email in a published campaign","description":"Uses standard Apresly registration, shared with existing channels. Campaign settings determine the deadline, retries, resets and cycles; the API does not override them. Drafts return 409 without registration. No email is sent automatically. A lost response may follow a successful registration; retrying uses the same campaign identity.","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"description":"JSON body, maximum 16 KiB. Unknown properties are rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadInput"},"examples":{"defaultLanguage":{"value":{"email":"customer+upsell@example.test"}},"polish":{"value":{"email":"customer+upsell@example.test","language":"pl"}}}}}},"responses":{"200":{"description":"Existing lead; standard campaign logic applied.","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRegistrationResult"},"example":{"campaignId":42,"email":"customer+upsell@example.test","registeredAt":"2026-09-12T12:00:00.000Z","deadline":"2026-09-14T12:00:00.000Z","timeZone":"Europe/Warsaw","offerLinks":[],"mailTimerUrl":null,"warnings":["NO_OFFER_PAGES","NO_MAIL_TIMER"],"created":false}}}},"201":{"description":"New lead registered and committed.","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadRegistrationResult"},"example":{"campaignId":42,"email":"customer+upsell@example.test","registeredAt":"2026-09-12T12:00:00.000Z","deadline":"2026-09-14T12:00:00.000Z","timeZone":"Europe/Warsaw","offerLinks":[],"mailTimerUrl":null,"warnings":["NO_OFFER_PAGES","NO_MAIL_TIMER"],"created":true}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"409":{"$ref":"#/components/responses/409"},"413":{"$ref":"#/components/responses/413"},"415":{"$ref":"#/components/responses/415"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}},"/campaigns/{campaignId}/leads/lookup":{"post":{"operationId":"lookupLead","summary":"Read an existing lead offer","description":"Read-only for business data: does not register, activate, renew or fetch any GIF/CTA. Uses POST to keep the email out of the URL. Expired deadlines can be returned. Historical leads in drafts return no links and CAMPAIGN_NOT_PUBLISHED. Missing lead returns 404 LEAD_NOT_FOUND. Authentication, rate limits and request history still apply.","parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"description":"JSON body, maximum 16 KiB. Unknown properties are rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadInput"},"examples":{"defaultLanguage":{"value":{"email":"customer+upsell@example.test"}},"polish":{"value":{"email":"customer+upsell@example.test","language":"pl"}}}}}},"responses":{"200":{"description":"Existing offer without business writes.","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadOffer"},"example":{"campaignId":42,"email":"customer+upsell@example.test","registeredAt":"2026-09-12T12:00:00.000Z","deadline":"2026-09-14T12:00:00.000Z","timeZone":"Europe/Warsaw","offerLinks":[],"mailTimerUrl":null,"warnings":["NO_OFFER_PAGES","NO_MAIL_TIMER"]}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"403":{"$ref":"#/components/responses/403"},"404":{"$ref":"#/components/responses/404"},"413":{"$ref":"#/components/responses/413"},"415":{"$ref":"#/components/responses/415"},"422":{"$ref":"#/components/responses/422"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"apresly_{uuid}.{secret}","description":"Named key generated in Integrations → API. Header example: Authorization: Bearer <YOUR_API_KEY>. All keys access only their owning account."}},"schemas":{"LeadInput":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"pattern":"^\\S(?:.*\\S)?$","description":"Exact email identity. Leading/trailing whitespace is rejected. Case and plus aliases are preserved."},"language":{"type":"string","enum":["en","pl"],"default":"en"}}},"CampaignSummary":{"type":"object","additionalProperties":false,"required":["id","name","type","isDraft"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"},"type":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"integer","minimum":1},"name":{"type":"string"}}},"isDraft":{"type":"boolean"}}},"OfferLink":{"type":"object","additionalProperties":false,"required":["pageId","pageUrl","url"],"properties":{"pageId":{"type":"integer","minimum":1},"pageUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}},"Error":{"type":"object","additionalProperties":false,"required":["status","code","message","requestId"],"properties":{"status":{"type":"string","enum":["error"]},"code":{"type":"string","enum":["INVALID_JSON","INVALID_CURSOR","UNAUTHORIZED","ACCOUNT_SUSPENDED","CAMPAIGN_NOT_FOUND","LEAD_NOT_FOUND","NOT_FOUND","CAMPAIGN_NOT_PUBLISHED","PAYLOAD_TOO_LARGE","UNSUPPORTED_MEDIA_TYPE","VALIDATION_ERROR","RATE_LIMITED","SERVICE_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}},"CampaignList":{"type":"object","additionalProperties":false,"required":["items","nextAfterId"],"properties":{"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CampaignSummary"}},"nextAfterId":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]}}},"LeadOffer":{"type":"object","additionalProperties":false,"required":["campaignId","email","registeredAt","deadline","timeZone","offerLinks","mailTimerUrl","warnings"],"properties":{"campaignId":{"type":"integer","minimum":1},"email":{"type":"string","format":"email","maxLength":254,"pattern":"^\\S(?:.*\\S)?$","description":"Exact email identity. Leading/trailing whitespace is rejected. Case and plus aliases are preserved."},"registeredAt":{"type":"string","format":"date-time","description":"First retained identifiable registration or activation, not the response time."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Actual deadline from the existing campaign mechanism; null when no deadline is determined."},"timeZone":{"type":"string","description":"Campaign time zone."},"offerLinks":{"type":"array","items":{"$ref":"#/components/schemas/OfferLink"},"description":"One link per eligible page, ordered by pageId ascending. May be empty."},"mailTimerUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"warnings":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["CAMPAIGN_NOT_PUBLISHED","COUNTDOWN_TOOLS_UNAVAILABLE","NO_OFFER_PAGES","NO_MAIL_TIMER","NO_DEADLINE"]},"description":"Ordered: CAMPAIGN_NOT_PUBLISHED for a draft; otherwise COUNTDOWN_TOOLS_UNAVAILABLE, or NO_OFFER_PAGES then NO_MAIL_TIMER for missing resources. NO_DEADLINE is appended independently when deadline is null."}}},"LeadRegistrationResult":{"type":"object","additionalProperties":false,"required":["campaignId","email","registeredAt","deadline","timeZone","offerLinks","mailTimerUrl","warnings","created"],"properties":{"campaignId":{"type":"integer","minimum":1},"email":{"type":"string","format":"email","maxLength":254,"pattern":"^\\S(?:.*\\S)?$","description":"Exact email identity. Leading/trailing whitespace is rejected. Case and plus aliases are preserved."},"registeredAt":{"type":"string","format":"date-time","description":"First retained identifiable registration or activation, not the response time."},"deadline":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Actual deadline from the existing campaign mechanism; null when no deadline is determined."},"timeZone":{"type":"string","description":"Campaign time zone."},"offerLinks":{"type":"array","items":{"$ref":"#/components/schemas/OfferLink"},"description":"One link per eligible page, ordered by pageId ascending. May be empty."},"mailTimerUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"warnings":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["CAMPAIGN_NOT_PUBLISHED","COUNTDOWN_TOOLS_UNAVAILABLE","NO_OFFER_PAGES","NO_MAIL_TIMER","NO_DEADLINE"]},"description":"Ordered: CAMPAIGN_NOT_PUBLISHED for a draft; otherwise COUNTDOWN_TOOLS_UNAVAILABLE, or NO_OFFER_PAGES then NO_MAIL_TIMER for missing resources. NO_DEADLINE is appended independently when deadline is null."},"created":{"type":"boolean","description":"True only if no identifiable lead existed before this request. Does not guarantee exactly-once delivery in the external system."}}}},"responses":{"400":{"description":"INVALID_JSON, INVALID_CURSOR","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INVALID_JSON":{"value":{"status":"error","code":"INVALID_JSON","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}},"INVALID_CURSOR":{"value":{"status":"error","code":"INVALID_CURSOR","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"401":{"description":"UNAUTHORIZED","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}},"WWW-Authenticate":{"schema":{"type":"string","pattern":"^Bearer(?: .+)?$"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHORIZED":{"value":{"status":"error","code":"UNAUTHORIZED","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"403":{"description":"ACCOUNT_SUSPENDED","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ACCOUNT_SUSPENDED":{"value":{"status":"error","code":"ACCOUNT_SUSPENDED","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"404":{"description":"CAMPAIGN_NOT_FOUND, LEAD_NOT_FOUND, NOT_FOUND","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"CAMPAIGN_NOT_FOUND":{"value":{"status":"error","code":"CAMPAIGN_NOT_FOUND","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}},"LEAD_NOT_FOUND":{"value":{"status":"error","code":"LEAD_NOT_FOUND","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}},"NOT_FOUND":{"value":{"status":"error","code":"NOT_FOUND","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"409":{"description":"CAMPAIGN_NOT_PUBLISHED","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"CAMPAIGN_NOT_PUBLISHED":{"value":{"status":"error","code":"CAMPAIGN_NOT_PUBLISHED","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"413":{"description":"PAYLOAD_TOO_LARGE","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"PAYLOAD_TOO_LARGE":{"value":{"status":"error","code":"PAYLOAD_TOO_LARGE","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"value":{"status":"error","code":"UNSUPPORTED_MEDIA_TYPE","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"422":{"description":"VALIDATION_ERROR","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_ERROR":{"value":{"status":"error","code":"VALIDATION_ERROR","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"429":{"description":"RATE_LIMITED","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds remaining in the fixed UTC minute window. Retry after this delay.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"value":{"status":"error","code":"RATE_LIMITED","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"value":{"status":"error","code":"INTERNAL_ERROR","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}},"503":{"description":"SERVICE_UNAVAILABLE","headers":{"X-Request-Id":{"description":"Identifier for support and request history.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"SERVICE_UNAVAILABLE":{"value":{"status":"error","code":"SERVICE_UNAVAILABLE","message":"Request could not be completed.","requestId":"00000000-0000-4000-8000-000000000001"}}}}}}}}}