{ "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 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 absolute production URL in servers: https://app.apresly.com/api/public/v1. Request history in the panel covers the last 7 days and excludes payloads, emails and secrets; audit-storage outages may leave gaps." }, "servers": [ { "url": "https://app.apresly.com/api/public/v1", "description": "Apresly production API" } ], "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 . 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" } } } } } } } } }