{ "openapi": "3.1.0", "info": { "title": "Convs API", "version": "1.0.0", "description": "REST API of Convs (app.convs.io): contacts, Meta leads, server-to-server conversions, campaign and creative reports, background jobs and webhooks. Authenticate with an organisation API key: `Authorization: Bearer cvs_live_…`.", "x-pl-description": "REST API Convs (app.convs.io): osoby, leady Meta, konwersje serwer–serwer, raporty kampanii i kreacji, zadania w tle oraz webhooki. Uwierzytelnianie kluczem API organizacji: `Authorization: Bearer cvs_live_…`.", "contact": { "name": "Convs", "url": "https://convs.io" }, "x-generated-by": "scripts/gen-openapi.py" }, "servers": [ { "url": "https://app.convs.io/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Keys", "description": "The calling key.", "x-pl-description": "Używany klucz." }, { "name": "Contacts", "description": "People of the Klienci page.", "x-pl-description": "Osoby ze strony Klienci." }, { "name": "Leads", "description": "Meta Instant Forms leads.", "x-pl-description": "Leady z formularzy Meta." }, { "name": "Events", "description": "Conversions sent to Meta and their deliveries.", "x-pl-description": "Konwersje wysyłane do Meta i ich wysyłki." }, { "name": "Reports", "description": "Campaign and creative numbers.", "x-pl-description": "Liczby kampanii i kreacji." }, { "name": "Jobs", "description": "Background work.", "x-pl-description": "Prace w tle." }, { "name": "Webhooks", "description": "Events pushed to your server.", "x-pl-description": "Zdarzenia wysyłane na Twój serwer." } ], "paths": { "/me": { "get": { "tags": [ "Keys" ], "operationId": "getMe", "summary": "Describe the calling key", "description": "Organisation, key name, scopes and expiry. A safe first call to check a new key; needs no scope.", "x-pl": { "summary": "Opis używanego klucza", "description": "Organizacja, nazwa klucza, uprawnienia i termin ważności. Bezpieczne pierwsze wywołanie do sprawdzenia nowego klucza; nie wymaga uprawnień." }, "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKey": [] } ] } }, "/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "summary": "List contacts", "description": "People of the Klienci page (merged cards are left out). Filter by stage, tag, exact e-mail or phone, or the ad they came from.", "x-pl": { "summary": "Lista osób", "description": "Osoby ze strony Klienci (scalone karty są pominięte). Filtruj po etapie, tagu, dokładnym e-mailu lub telefonie albo reklamie, z której przyszły." }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "stage", "in": "query", "required": false, "description": "Stage.", "x-pl-description": "Etap.", "schema": { "type": "string", "enum": [ "new", "contacted", "qualified", "sold", "rejected" ] } }, { "name": "tag", "in": "query", "required": false, "description": "Tag.", "x-pl-description": "Tag.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Exact e-mail (matched by hash).", "x-pl-description": "Dokładny e-mail (dopasowanie po skrócie).", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": false, "description": "Exact phone (matched by hash).", "x-pl-description": "Dokładny telefon (dopasowanie po skrócie).", "schema": { "type": "string" } }, { "name": "campaign", "in": "query", "required": false, "description": "People with a lead from this Meta campaign id.", "x-pl-description": "Osoby ze zgłoszeniem z tej kampanii Meta.", "schema": { "type": "string" } }, { "name": "adset", "in": "query", "required": false, "description": "…from this ad set id.", "x-pl-description": "…z tego zestawu reklam.", "schema": { "type": "string" } }, { "name": "ad", "in": "query", "required": false, "description": "…from this ad id.", "x-pl-description": "…z tej reklamy.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "contacts:read", "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Contacts" ], "operationId": "createContact", "summary": "Create a contact", "description": "Adds a person like „Dodaj osobę” in the panel (round robin owner when it is on).", "x-pl": { "summary": "Dodaj osobę", "description": "Dodaje osobę jak „Dodaj osobę” w panelu (opiekun z round robin, gdy jest włączony)." }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created", "x-pl-description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } } } } }, "/contacts/{id}": { "get": { "tags": [ "Contacts" ], "operationId": "getContact", "summary": "Get a contact", "description": "A merged card answers 409 `contact_merged` with `details.merged_into`.", "x-pl": { "summary": "Pobierz osobę", "description": "Scalona karta zwraca 409 `contact_merged` z `details.merged_into`." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-required-scope": "contacts:read", "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Contacts" ], "operationId": "updateContact", "summary": "Update a contact", "description": "Changes name, phone, e-mail or tags; every change is a history line.", "x-pl": { "summary": "Zmień dane osoby", "description": "Zmienia imię, telefon, e-mail lub tagi; każda zmiana to wpis w historii." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" } } } } } }, "/contacts/{id}/stage": { "post": { "tags": [ "Contacts" ], "operationId": "setContactStage", "summary": "Set the stage", "description": "Moves the person and, in the same transaction, every open lead of the current cycle; leads with an active flow get a Meta conversion event queued. The same path as „Zmień etap” in the panel; stage automations start.", "x-pl": { "summary": "Zmień etap", "description": "Przesuwa osobę i w tej samej transakcji wszystkie otwarte zgłoszenia bieżącego cyklu; zgłoszenia z aktywnym przepływem dostają zdarzenie konwersji Meta w kolejce. Ta sama ścieżka co „Zmień etap” w panelu; uruchamiają się automatyzacje etapu." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageChange" } } } } } }, "/contacts/{id}/notes": { "post": { "tags": [ "Contacts" ], "operationId": "addContactNote", "summary": "Add a note", "description": "Adds a note, call or meeting to the person's history.", "x-pl": { "summary": "Dodaj notatkę", "description": "Dodaje notatkę, telefon lub spotkanie do historii osoby." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created", "x-pl-description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" } } } } } }, "/contacts/{id}/tags": { "post": { "tags": [ "Contacts" ], "operationId": "changeContactTags", "summary": "Add or remove tags", "description": "Adds and removes tags without sending the whole list.", "x-pl": { "summary": "Dodaj lub usuń tagi", "description": "Dodaje i usuwa tagi bez wysyłania całej listy." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagsChange" } } } } } }, "/contacts/{id}/sms-optout": { "post": { "tags": [ "Contacts" ], "operationId": "setContactOptout", "summary": "Block or allow SMS", "description": "Keeps the „nie wysyłaj” list and every person with the same phone in step.", "x-pl": { "summary": "Zablokuj lub dopuść SMS-y", "description": "Utrzymuje listę „nie wysyłaj” i wszystkie osoby z tym samym telefonem w zgodzie." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "contacts:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptoutChange" } } } } } }, "/leads": { "get": { "tags": [ "Leads" ], "operationId": "listLeads", "summary": "List leads", "description": "Meta Instant Forms leads. `answers` are included only for keys with `leads:answers`.", "x-pl": { "summary": "Lista zgłoszeń", "description": "Leady z formularzy Meta. `answers` są dołączane tylko dla kluczy z `leads:answers`." }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "form", "in": "query", "required": false, "description": "Convs form (source) id.", "x-pl-description": "Identyfikator formularza (źródła) w Convs.", "schema": { "type": "string" } }, { "name": "campaign", "in": "query", "required": false, "description": "Meta campaign id.", "x-pl-description": "Identyfikator kampanii Meta.", "schema": { "type": "string" } }, { "name": "adset", "in": "query", "required": false, "description": "Meta ad set id.", "x-pl-description": "Identyfikator zestawu reklam.", "schema": { "type": "string" } }, { "name": "ad", "in": "query", "required": false, "description": "Meta ad id.", "x-pl-description": "Identyfikator reklamy.", "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "description": "Contact id.", "x-pl-description": "Identyfikator osoby.", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "required": false, "description": "Stage.", "x-pl-description": "Etap.", "schema": { "type": "string", "enum": [ "new", "contacted", "qualified", "sold", "rejected" ] } }, { "name": "from", "in": "query", "required": false, "description": "Submitted on or after (YYYY-MM-DD in the organisation's zone, or ISO 8601).", "x-pl-description": "Wysłane tego dnia lub później (RRRR-MM-DD w strefie organizacji albo ISO 8601).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Submitted on or before.", "x-pl-description": "Wysłane tego dnia lub wcześniej.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "leads:read", "security": [ { "apiKey": [] } ] } }, "/leads/{id}": { "get": { "tags": [ "Leads" ], "operationId": "getLead", "summary": "Get a lead", "description": "One lead; `answers` only with `leads:answers`.", "x-pl": { "summary": "Pobierz zgłoszenie", "description": "Jedno zgłoszenie; `answers` tylko z `leads:answers`." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "leads:read", "security": [ { "apiKey": [] } ] } }, "/events": { "post": { "tags": [ "Events" ], "operationId": "createEvent", "summary": "Send a conversion", "description": "Server-to-server conversion ingest. The source's active flows map `status` to Meta events and queue one delivery per dataset; dedupe rules are unchanged. Answers 202: queued, not yet sent.", "x-pl": { "summary": "Wyślij konwersję", "description": "Przyjmowanie konwersji serwer–serwer. Aktywne przepływy źródła mapują `status` na zdarzenia Meta i dodają jedną wysyłkę na dataset; zasady deduplikacji bez zmian. Odpowiedź 202: w kolejce, jeszcze nie wysłane." }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Accepted into the queue", "x-pl-description": "Przyjęto do kolejki", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "events:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCreate" } } } } }, "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "List events", "description": "Conversions with their deliveries; payloads are never returned.", "x-pl": { "summary": "Lista zdarzeń", "description": "Konwersje z wysyłkami; treść zdarzeń nigdy nie jest zwracana." }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "source", "in": "query", "required": false, "description": "Source id.", "x-pl-description": "Identyfikator źródła.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Your status.", "x-pl-description": "Twój status.", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "required": false, "description": "Your record id.", "x-pl-description": "Twój identyfikator rekordu.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "events:read", "security": [ { "apiKey": [] } ] } }, "/events/{id}": { "get": { "tags": [ "Events" ], "operationId": "getEvent", "summary": "Get an event", "description": "One conversion with the status of each delivery.", "x-pl": { "summary": "Pobierz zdarzenie", "description": "Jedna konwersja ze statusem każdej wysyłki." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "events:read", "security": [ { "apiKey": [] } ] } }, "/deliveries": { "get": { "tags": [ "Events" ], "operationId": "listDeliveries", "summary": "List deliveries", "description": "Delivery status to Meta, e.g. `status=failed&updated_since=…` to follow failures.", "x-pl": { "summary": "Lista wysyłek", "description": "Status wysyłek do Meta, np. `status=failed&updated_since=…`, by śledzić błędy." }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "status", "in": "query", "required": false, "description": "Delivery status.", "x-pl-description": "Status wysyłki.", "schema": { "type": "string", "enum": [ "pending", "sending", "retry", "accepted", "failed", "cancelled" ] } }, { "name": "event", "in": "query", "required": false, "description": "Event id.", "x-pl-description": "Identyfikator zdarzenia.", "schema": { "type": "string" } }, { "name": "target", "in": "query", "required": false, "description": "Receiver id.", "x-pl-description": "Identyfikator odbiorcy.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "events:read", "security": [ { "apiKey": [] } ] } }, "/campaigns/report": { "get": { "tags": [ "Reports" ], "operationId": "campaignReport", "summary": "Campaign report", "description": "Spend, leads, qualified leads, sales and costs per campaign, ad set or ad — the numbers of the Kampanie page.", "x-pl": { "summary": "Raport kampanii", "description": "Wydatki, zgłoszenia, zakwalifikowane, sprzedaż i koszty na kampanię, zestaw lub reklamę — liczby ze strony Kampanie." }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day YYYY-MM-DD (default: 30 days ago).", "x-pl-description": "Pierwszy dzień RRRR-MM-DD (domyślnie 30 dni temu).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Last day YYYY-MM-DD (range up to 366 days).", "x-pl-description": "Ostatni dzień RRRR-MM-DD (zakres do 366 dni).", "schema": { "type": "string" } }, { "name": "level", "in": "query", "required": false, "description": "Row level.", "x-pl-description": "Poziom wierszy.", "schema": { "type": "string", "enum": [ "campaign", "adset", "ad" ], "default": "campaign" } }, { "name": "campaign", "in": "query", "required": false, "description": "Only this campaign (for adset/ad level).", "x-pl-description": "Tylko ta kampania (dla poziomu adset/ad).", "schema": { "type": "string" } }, { "name": "adset", "in": "query", "required": false, "description": "Only this ad set (ad level).", "x-pl-description": "Tylko ten zestaw (poziom ad).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "campaigns:read", "security": [ { "apiKey": [] } ] } }, "/creatives/report": { "get": { "tags": [ "Reports" ], "operationId": "creativeReport", "summary": "Creative report", "description": "Metrics per creative group with weekly momentum and the fatigue rule — the numbers of the Kreacje page.", "x-pl": { "summary": "Raport kreacji", "description": "Metryki na grupę kreacji z trendem tygodniowym i regułą zmęczenia — liczby ze strony Kreacje." }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day YYYY-MM-DD.", "x-pl-description": "Pierwszy dzień RRRR-MM-DD.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Last day YYYY-MM-DD.", "x-pl-description": "Ostatni dzień RRRR-MM-DD.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Creative format.", "x-pl-description": "Format kreacji.", "schema": { "type": "string" } }, { "name": "campaign", "in": "query", "required": false, "description": "Meta campaign id.", "x-pl-description": "Identyfikator kampanii Meta.", "schema": { "type": "string" } }, { "name": "ad_account", "in": "query", "required": false, "description": "Ad account id.", "x-pl-description": "Identyfikator konta reklamowego.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Tag filter `dimension:value` (hook, creator, offer).", "x-pl-description": "Filtr tagu `wymiar:wartość` (hook, creator, offer).", "schema": { "type": "string" } }, { "name": "weeks", "in": "query", "required": false, "description": "Weeks of momentum, 4–8.", "x-pl-description": "Liczba tygodni trendu, 4–8.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreativeReport" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "creatives:read", "security": [ { "apiKey": [] } ] } }, "/jobs": { "get": { "tags": [ "Jobs" ], "operationId": "listJobs", "summary": "List background jobs", "description": "Lead imports, spend syncs, sheet syncs and other background work of the organisation.", "x-pl": { "summary": "Lista zadań w tle", "description": "Importy leadów, synchronizacje wydatków, arkuszy i inne prace w tle organizacji." }, "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" }, { "name": "status", "in": "query", "required": false, "description": "Job status.", "x-pl-description": "Status zadania.", "schema": { "type": "string", "enum": [ "queued", "running", "done", "failed", "cancelled" ] } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "jobs:read", "security": [ { "apiKey": [] } ] } }, "/jobs/{number}": { "get": { "tags": [ "Jobs" ], "operationId": "getJob", "summary": "Get a job", "description": "One job by its number.", "x-pl": { "summary": "Pobierz zadanie", "description": "Jedno zadanie po numerze." }, "parameters": [ { "name": "number", "in": "path", "required": true, "description": "Job number.", "x-pl-description": "Numer zadania.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "jobs:read", "security": [ { "apiKey": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhooks", "description": "Webhook subscriptions of the organisation (up to 10).", "x-pl": { "summary": "Lista webhooków", "description": "Subskrypcje webhooków organizacji (do 10)." }, "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "webhooks:read", "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Create a webhook", "description": "Subscribes an HTTPS URL to events. The signing `secret` is returned only here.", "x-pl": { "summary": "Dodaj webhook", "description": "Subskrybuje adres HTTPS na zdarzenia. Sekret podpisu `secret` jest zwracany tylko tutaj." }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created", "x-pl-description": "Utworzono", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "webhooks:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "summary": "Get a webhook", "description": "One subscription with its last result.", "x-pl": { "summary": "Pobierz webhook", "description": "Jedna subskrypcja z ostatnim wynikiem." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "webhooks:read", "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update a webhook", "description": "Changes URL, events, description or pauses it; resuming resets the failure count.", "x-pl": { "summary": "Zmień webhook", "description": "Zmienia adres, zdarzenia, opis lub wstrzymuje; wznowienie zeruje licznik błędów." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/TooLarge" } }, "x-required-scope": "webhooks:write", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook", "description": "Removes the subscription and its queued deliveries.", "x-pl": { "summary": "Usuń webhook", "description": "Usuwa subskrypcję i jej wysyłki w kolejce." }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "responses": { "204": { "description": "Deleted", "x-pl-description": "Usunięto" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "webhooks:write", "security": [ { "apiKey": [] } ] } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a test ping", "description": "Queues a signed `ping` event to check your endpoint and signature verification.", "x-pl": { "summary": "Wyślij próbny ping", "description": "Dodaje do kolejki podpisane zdarzenie `ping`, by sprawdzić odbiornik i weryfikację podpisu." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Queued", "x-pl-description": "W kolejce", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "webhooks:write", "security": [ { "apiKey": [] } ] } }, "/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Replaces the signing secret at once; the new `secret` is returned only here. Deliveries still queued are signed with the new secret.", "x-pl": { "summary": "Wymień sekret podpisu", "description": "Od razu wymienia sekret podpisu; nowy `secret` jest zwracany tylko tutaj. Wysyłki czekające w kolejce zostaną podpisane nowym sekretem." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" } }, "x-required-scope": "webhooks:write", "security": [ { "apiKey": [] } ] } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "description": "Recent attempts (kept 30 days), newest first.", "x-pl": { "summary": "Lista wysyłek webhooka", "description": "Ostatnie próby (przechowywane 30 dni), od najnowszych." }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/updated_since" } ], "responses": { "200": { "description": "OK", "x-pl-description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-required-scope": "webhooks:read", "security": [ { "apiKey": [] } ] } } }, "webhooks": { "contact.created": { "post": { "summary": "contact.created", "description": "A person was added (form lead, manual, API, automation).", "x-pl": { "summary": "contact.created", "description": "Dodano osobę (lead z formularza, ręcznie, przez API, automatyzacją)." }, "x-example": { "contact_id": "abc123", "stage": "new", "first_source": "Formularz kontaktowy" }, "parameters": [ { "name": "X-Convs-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + hex HMAC-SHA256 of `{X-Convs-Timestamp}.{raw body}` with the webhook secret.", "x-pl-description": "`sha256=` + hex HMAC-SHA256 z `{X-Convs-Timestamp}.{surowa treść}` kluczem sekretu webhooka." }, { "name": "X-Convs-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds of the attempt; reject values older than 5 minutes.", "x-pl-description": "Sekundy Unix próby; odrzucaj starsze niż 5 minut." }, { "name": "X-Convs-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type.", "x-pl-description": "Typ zdarzenia." }, { "name": "X-Convs-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (changes per webhook, stays across retries).", "x-pl-description": "Identyfikator wysyłki (inny dla każdego webhooka, ten sam przy ponowieniach)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 15 s acknowledges the delivery; anything else is retried up to 8 times over about 2 days (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h).", "x-pl-description": "Dowolny kod 2xx w ciągu 15 s potwierdza odbiór; inaczej ponawiamy do 8 razy w ciągu ok. 2 dni (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h)." } } } }, "contact.stage_changed": { "post": { "summary": "contact.stage_changed", "description": "A person moved to another stage.", "x-pl": { "summary": "contact.stage_changed", "description": "Osoba przeszła do innego etapu." }, "x-example": { "contact_id": "abc123", "from": "new", "to": "qualified", "cycle": 1, "meta_events_queued": 1, "leads_without_send": 0 }, "parameters": [ { "name": "X-Convs-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + hex HMAC-SHA256 of `{X-Convs-Timestamp}.{raw body}` with the webhook secret.", "x-pl-description": "`sha256=` + hex HMAC-SHA256 z `{X-Convs-Timestamp}.{surowa treść}` kluczem sekretu webhooka." }, { "name": "X-Convs-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds of the attempt; reject values older than 5 minutes.", "x-pl-description": "Sekundy Unix próby; odrzucaj starsze niż 5 minut." }, { "name": "X-Convs-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type.", "x-pl-description": "Typ zdarzenia." }, { "name": "X-Convs-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (changes per webhook, stays across retries).", "x-pl-description": "Identyfikator wysyłki (inny dla każdego webhooka, ten sam przy ponowieniach)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 15 s acknowledges the delivery; anything else is retried up to 8 times over about 2 days (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h).", "x-pl-description": "Dowolny kod 2xx w ciągu 15 s potwierdza odbiór; inaczej ponawiamy do 8 razy w ciągu ok. 2 dni (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h)." } } } }, "lead.created": { "post": { "summary": "lead.created", "description": "A Meta Instant Forms lead was stored.", "x-pl": { "summary": "lead.created", "description": "Zapisano lead z formularza Meta." }, "x-example": { "lead_id": "l123", "meta_lead_id": "1234567890", "form_id": "src123", "contact_id": "abc123", "campaign_id": "120200000", "adset_id": "", "ad_id": "", "created_at": "2026-10-08T10:00:00Z" }, "parameters": [ { "name": "X-Convs-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + hex HMAC-SHA256 of `{X-Convs-Timestamp}.{raw body}` with the webhook secret.", "x-pl-description": "`sha256=` + hex HMAC-SHA256 z `{X-Convs-Timestamp}.{surowa treść}` kluczem sekretu webhooka." }, { "name": "X-Convs-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds of the attempt; reject values older than 5 minutes.", "x-pl-description": "Sekundy Unix próby; odrzucaj starsze niż 5 minut." }, { "name": "X-Convs-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type.", "x-pl-description": "Typ zdarzenia." }, { "name": "X-Convs-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (changes per webhook, stays across retries).", "x-pl-description": "Identyfikator wysyłki (inny dla każdego webhooka, ten sam przy ponowieniach)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 15 s acknowledges the delivery; anything else is retried up to 8 times over about 2 days (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h).", "x-pl-description": "Dowolny kod 2xx w ciągu 15 s potwierdza odbiór; inaczej ponawiamy do 8 razy w ciągu ok. 2 dni (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h)." } } } }, "delivery.failed": { "post": { "summary": "delivery.failed", "description": "A conversion delivery to Meta failed for good.", "x-pl": { "summary": "delivery.failed", "description": "Wysyłka konwersji do Meta ostatecznie się nie powiodła." }, "x-example": { "delivery_id": "d123", "event_id": "e123", "target_id": "t123", "dataset_id": "123456789", "event_name": "Lead", "mode": "live", "error": "Połącz konto Meta ponownie lub sprawdź token." }, "parameters": [ { "name": "X-Convs-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + hex HMAC-SHA256 of `{X-Convs-Timestamp}.{raw body}` with the webhook secret.", "x-pl-description": "`sha256=` + hex HMAC-SHA256 z `{X-Convs-Timestamp}.{surowa treść}` kluczem sekretu webhooka." }, { "name": "X-Convs-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds of the attempt; reject values older than 5 minutes.", "x-pl-description": "Sekundy Unix próby; odrzucaj starsze niż 5 minut." }, { "name": "X-Convs-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type.", "x-pl-description": "Typ zdarzenia." }, { "name": "X-Convs-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (changes per webhook, stays across retries).", "x-pl-description": "Identyfikator wysyłki (inny dla każdego webhooka, ten sam przy ponowieniach)." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 15 s acknowledges the delivery; anything else is retried up to 8 times over about 2 days (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h).", "x-pl-description": "Dowolny kod 2xx w ciągu 15 s potwierdza odbiór; inaczej ponawiamy do 8 razy w ciągu ok. 2 dni (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h)." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "cvs_live_…", "x-scopes": [ { "name": "contacts:read", "pii": true }, { "name": "contacts:write", "pii": true }, { "name": "leads:read", "pii": false }, { "name": "leads:answers", "pii": true }, { "name": "events:read", "pii": false }, { "name": "events:write", "pii": false }, { "name": "campaigns:read", "pii": false }, { "name": "creatives:read", "pii": false }, { "name": "jobs:read", "pii": false }, { "name": "webhooks:read", "pii": false }, { "name": "webhooks:write", "pii": false } ], "description": "Organisation API key created in the panel (Konfiguracja → API).", "x-pl-description": "Klucz API organizacji utworzony w panelu (Konfiguracja → API)." } }, "parameters": { "limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100 (default 25).", "x-pl-description": "Rozmiar strony, 1–100 (domyślnie 25).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "cursor": { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "x-pl-description": "`next_cursor` z poprzedniej strony.", "schema": { "type": "string" } }, "order": { "name": "order", "in": "query", "required": false, "description": "Sort by `updated_at` (then id): `desc` newest first (default) or `asc`.", "x-pl-description": "Sortowanie po `updated_at` (potem id): `desc` od najnowszych (domyślnie) lub `asc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, "updated_since": { "name": "updated_since", "in": "query", "required": false, "description": "Only records changed at or after this ISO 8601 time.", "x-pl-description": "Tylko rekordy zmienione w tym czasie ISO 8601 lub później.", "schema": { "type": "string", "format": "date-time" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key (1–255 visible ASCII characters). Repeating a POST with the same key and body within 24 hours returns the stored response with `Idempotent-Replayed: true`.", "x-pl-description": "Unikalny klucz (1–255 widocznych znaków ASCII). Powtórzenie POST z tym samym kluczem i treścią w ciągu 24 godzin zwraca zapisaną odpowiedź z `Idempotent-Replayed: true`.", "schema": { "type": "string", "maxLength": 255 } }, "id": { "name": "id", "in": "path", "required": true, "description": "Record id.", "x-pl-description": "Identyfikator rekordu.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Invalid input (`validation_error`, `invalid_json`, `invalid_cursor`).", "x-pl-description": "Nieprawidłowe dane (`validation_error`, `invalid_json`, `invalid_cursor`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, unknown, revoked or expired key (`unauthorized`, `key_revoked`, `key_expired`).", "x-pl-description": "Brak, nieznany, unieważniony lub wygasły klucz (`unauthorized`, `key_revoked`, `key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the scope (`insufficient_scope`, `details.required_scope`).", "x-pl-description": "Klucz nie ma uprawnienia (`insufficient_scope`, `details.required_scope`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such record in your organisation (`not_found`).", "x-pl-description": "Brak takiego rekordu w Twojej organizacji (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflicts with the current state (`conflict`, `contact_exists`, `contact_merged`, `stage_conflict`, `event_conflict`, `source_paused`, `idempotency_in_progress`).", "x-pl-description": "Konflikt z aktualnym stanem (`conflict`, `contact_exists`, `contact_merged`, `stage_conflict`, `event_conflict`, `source_paused`, `idempotency_in_progress`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Idempotency-Key reused with a different body (`idempotency_key_reused`).", "x-pl-description": "Idempotency-Key użyty z inną treścią (`idempotency_key_reused`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooLarge": { "description": "Body over 64 KB (`payload_too_large`).", "x-pl-description": "Treść ponad 64 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Over 120 requests per minute for this key (`rate_limited`); wait `Retry-After` seconds.", "x-pl-description": "Ponad 120 żądań na minutę tym kluczem (`rate_limited`); odczekaj `Retry-After` sekund.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Stable machine-readable code, e.g. `validation_error`. Never translated.", "x-pl-description": "Stały kod błędu do obsługi w programie, np. `validation_error`. Nigdy nie jest tłumaczony.", "type": "string" }, "message": { "description": "Human-readable message in the language from `Accept-Language` (Polish by default, `en` for English).", "x-pl-description": "Opis dla człowieka w języku z nagłówka `Accept-Language` (domyślnie polski, `en` — angielski).", "type": "string" }, "details": { "description": "Extra machine-readable context, e.g. `required_scope` or `contact_id`.", "x-pl-description": "Dodatkowe dane, np. `required_scope` albo `contact_id`.", "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "AdSource": { "type": "object", "properties": { "platform": { "description": "Placement platform reported by Meta (facebook, instagram…).", "x-pl-description": "Platforma emisji podana przez Meta (facebook, instagram…).", "type": "string" }, "campaign_id": { "description": "Meta campaign id.", "x-pl-description": "Identyfikator kampanii Meta.", "type": "string" }, "campaign_name": { "description": "Campaign name.", "x-pl-description": "Nazwa kampanii.", "type": "string" }, "adset_id": { "description": "Meta ad set id.", "x-pl-description": "Identyfikator zestawu reklam Meta.", "type": "string" }, "adset_name": { "description": "Ad set name.", "x-pl-description": "Nazwa zestawu reklam.", "type": "string" }, "ad_id": { "description": "Meta ad id.", "x-pl-description": "Identyfikator reklamy Meta.", "type": "string" }, "ad_name": { "description": "Ad name.", "x-pl-description": "Nazwa reklamy.", "type": "string" } }, "description": "The Meta ad a lead or a person came from.", "x-pl-description": "Reklama Meta, z której przyszło zgłoszenie lub osoba." }, "Contact": { "type": "object", "properties": { "id": { "description": "Contact id.", "x-pl-description": "Identyfikator osoby.", "type": "string" }, "name": { "description": "Full name.", "x-pl-description": "Imię i nazwisko.", "type": "string" }, "phone": { "description": "Phone in E.164 form, empty when unknown.", "x-pl-description": "Telefon w formacie E.164, pusty gdy nieznany.", "type": "string" }, "email": { "description": "E-mail, empty when unknown.", "x-pl-description": "E-mail, pusty gdy nieznany.", "type": "string" }, "stage": { "description": "Sales stage.", "x-pl-description": "Etap sprzedaży.", "type": "string", "enum": [ "new", "contacted", "qualified", "sold", "rejected" ] }, "cycle": { "description": "Sales cycle number; a new lead for a closed person opens the next cycle.", "x-pl-description": "Numer cyklu sprzedaży; nowe zgłoszenie zamkniętej osoby otwiera kolejny cykl.", "type": "integer" }, "tags": { "description": "Tags.", "x-pl-description": "Tagi.", "type": "array", "items": { "type": "string" } }, "sms_optout": { "description": "True when SMS to this person are blocked.", "x-pl-description": "Prawda, gdy SMS-y do tej osoby są zablokowane.", "type": "boolean" }, "first_source": { "description": "Where the person first came from (form name, \"Ręcznie\"…).", "x-pl-description": "Skąd osoba przyszła po raz pierwszy (nazwa formularza, „Ręcznie”…).", "type": "string" }, "first_ad": { "oneOf": [ { "$ref": "#/components/schemas/AdSource" }, { "type": "null" } ], "description": "The first ad the person came from, null for organic or unknown.", "x-pl-description": "Pierwsza reklama, z której przyszła osoba; null dla ruchu organicznego lub nieznanego." }, "owner_id": { "description": "User id of the person's owner (opiekun).", "x-pl-description": "Identyfikator użytkownika — opiekuna osoby.", "type": [ "string", "null" ] }, "last_activity_at": { "description": "Last activity time.", "x-pl-description": "Czas ostatniej aktywności.", "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change; use with `updated_since`.", "x-pl-description": "Ostatnia zmiana; używaj z `updated_since`.", "type": "string", "format": "date-time" } } }, "ContactList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "ContactCreate": { "type": "object", "properties": { "name": { "description": "Full name (up to 200 characters).", "x-pl-description": "Imię i nazwisko (do 200 znaków).", "type": "string", "maxLength": 200 }, "phone": { "description": "Phone with a country code, e.g. +48 600 857 482, or 9 digits (Poland).", "x-pl-description": "Telefon z numerem kierunkowym, np. +48 600 857 482, albo 9 cyfr.", "type": "string" }, "email": { "description": "E-mail address.", "x-pl-description": "Adres e-mail.", "type": "string", "maxLength": 254 }, "tags": { "description": "Tags.", "x-pl-description": "Tagi.", "type": "array", "items": { "type": "string" } } }, "description": "A phone or an e-mail is required. A person with the same phone or e-mail is not duplicated: the answer is 409 `contact_exists` with `details.contact_id`.", "x-pl-description": "Wymagany jest telefon lub e-mail. Osoba z tym samym telefonem lub e-mailem nie jest dublowana: odpowiedź to 409 `contact_exists` z `details.contact_id`.", "additionalProperties": false }, "ContactUpdate": { "type": "object", "properties": { "name": { "description": "Full name.", "x-pl-description": "Imię i nazwisko.", "type": "string" }, "phone": { "description": "Phone; an empty string removes it (a phone or an e-mail must remain).", "x-pl-description": "Telefon; pusty tekst usuwa go (musi zostać telefon lub e-mail).", "type": "string" }, "email": { "description": "E-mail; an empty string removes it.", "x-pl-description": "E-mail; pusty tekst usuwa go.", "type": "string" }, "tags": { "description": "Replaces all tags.", "x-pl-description": "Zastępuje wszystkie tagi.", "type": "array", "items": { "type": "string" } } }, "description": "Only the fields you send change. Each change is written to the person's history.", "x-pl-description": "Zmieniają się tylko wysłane pola. Każda zmiana trafia do historii osoby.", "additionalProperties": false }, "StageChange": { "type": "object", "properties": { "stage": { "description": "Target stage.", "x-pl-description": "Docelowy etap.", "type": "string", "enum": [ "new", "contacted", "qualified", "sold", "rejected" ] }, "value": { "description": "Sale value (for `sold`); counted once, on the newest lead whose Meta event is queued.", "x-pl-description": "Wartość sprzedaży (dla `sold`); liczona raz, na najnowszym zgłoszeniu, którego zdarzenie Meta trafia do kolejki.", "type": "number" }, "currency": { "description": "ISO 4217 currency of `value`, e.g. PLN.", "x-pl-description": "Waluta ISO 4217 dla `value`, np. PLN.", "type": "string" } }, "required": [ "stage" ], "additionalProperties": false }, "StageResult": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "meta_events_queued": { "description": "Meta conversion events queued for open leads (the queue sends them; this is not a confirmation from Meta).", "x-pl-description": "Zdarzenia konwersji Meta dodane do kolejki dla otwartych zgłoszeń (kolejka je wyśle; to nie jest potwierdzenie od Meta).", "type": "integer" }, "leads_without_send": { "description": "Open leads moved without a Meta event (no active flow for the stage).", "x-pl-description": "Otwarte zgłoszenia przesunięte bez zdarzenia Meta (brak aktywnego przepływu dla etapu).", "type": "integer" } } }, "NoteCreate": { "type": "object", "properties": { "kind": { "description": "Entry kind.", "x-pl-description": "Rodzaj wpisu.", "type": "string", "enum": [ "note", "call", "meeting" ], "default": "note" }, "text": { "description": "Text, 1–5000 characters.", "x-pl-description": "Treść, 1–5000 znaków.", "type": "string", "maxLength": 5000 }, "time": { "description": "When it happened (default: now); not in the future.", "x-pl-description": "Kiedy to było (domyślnie teraz); nie w przyszłości.", "type": "string", "format": "date-time" } }, "required": [ "text" ], "additionalProperties": false }, "Note": { "type": "object", "properties": { "id": { "description": "History entry id.", "x-pl-description": "Identyfikator wpisu historii.", "type": "string" }, "contact_id": { "description": "Contact id.", "x-pl-description": "Identyfikator osoby.", "type": "string" }, "kind": { "description": "Entry kind.", "x-pl-description": "Rodzaj wpisu.", "type": "string" }, "text": { "description": "Text.", "x-pl-description": "Treść.", "type": "string" }, "time": { "description": "Entry time.", "x-pl-description": "Czas wpisu.", "type": "string", "format": "date-time" } } }, "TagsChange": { "type": "object", "properties": { "add": { "description": "Tags to add.", "x-pl-description": "Tagi do dodania.", "type": "array", "items": { "type": "string" } }, "remove": { "description": "Tags to remove.", "x-pl-description": "Tagi do usunięcia.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "OptoutChange": { "type": "object", "properties": { "sms_optout": { "description": "True blocks SMS to the person's phone (for every person sharing it), false allows them again.", "x-pl-description": "true blokuje SMS-y na telefon osoby (dla wszystkich osób z tym numerem), false ponownie je dopuszcza.", "type": "boolean" } }, "required": [ "sms_optout" ], "additionalProperties": false }, "LeadAnswer": { "type": "object", "properties": { "key": { "description": "Field key (also the automation variable).", "x-pl-description": "Klucz pola (także zmienna automatyzacji).", "type": "string" }, "label": { "description": "Question as shown in the form.", "x-pl-description": "Pytanie jak w formularzu.", "type": "string" }, "values": { "description": "Answers.", "x-pl-description": "Odpowiedzi.", "type": "array", "items": { "type": "string" } } } }, "Lead": { "type": "object", "properties": { "id": { "description": "Lead id in Convs.", "x-pl-description": "Identyfikator zgłoszenia w Convs.", "type": "string" }, "meta_lead_id": { "description": "Lead id in Meta.", "x-pl-description": "Identyfikator leada w Meta.", "type": "string" }, "form_id": { "description": "Convs source (form) id; use as `form` filter.", "x-pl-description": "Identyfikator źródła (formularza) w Convs; filtr `form`.", "type": "string" }, "form_name": { "description": "Form name.", "x-pl-description": "Nazwa formularza.", "type": "string" }, "meta_form_id": { "description": "Meta form id.", "x-pl-description": "Identyfikator formularza w Meta.", "type": "string" }, "meta_page_id": { "description": "Meta Page id.", "x-pl-description": "Identyfikator strony w Meta.", "type": "string" }, "stage": { "description": "Lead stage.", "x-pl-description": "Etap zgłoszenia.", "type": "string", "enum": [ "new", "contacted", "qualified", "sold", "rejected" ] }, "cycle": { "description": "Sales cycle of the person this lead belongs to.", "x-pl-description": "Cykl sprzedaży osoby, do której należy zgłoszenie.", "type": "integer" }, "contact_id": { "description": "The person (contact) of this lead.", "x-pl-description": "Osoba (kontakt) tego zgłoszenia.", "type": [ "string", "null" ] }, "fetch_status": { "description": "`ready` when the lead data is stored.", "x-pl-description": "`ready`, gdy dane leada są zapisane.", "type": "string" }, "ad": { "oneOf": [ { "$ref": "#/components/schemas/AdSource" }, { "type": "null" } ], "description": "Ad the lead came from, null for organic or unknown.", "x-pl-description": "Reklama zgłoszenia; null dla organicznych lub nieznanych." }, "stages": { "description": "Stage history.", "x-pl-description": "Historia etapów.", "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "meta_event_queued": { "type": "boolean" } } } }, "answers": { "description": "Form answers. Only for keys with `leads:answers`.", "x-pl-description": "Odpowiedzi z formularza. Tylko dla kluczy z `leads:answers`.", "type": "array", "items": { "$ref": "#/components/schemas/LeadAnswer" } }, "created_at": { "description": "When the lead was submitted.", "x-pl-description": "Kiedy zgłoszenie zostało wysłane.", "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "LeadList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "EventCreate": { "type": "object", "properties": { "source": { "description": "Id of a Google Sheets or Shoper source of your organisation (Połączenia → source details).", "x-pl-description": "Identyfikator źródła Arkusz Google lub Shoper Twojej organizacji (Połączenia → szczegóły źródła).", "type": "string" }, "external_id": { "description": "Your id of the record (order, lead…), max 128 characters.", "x-pl-description": "Twój identyfikator rekordu (zamówienia, leada…), do 128 znaków.", "type": "string", "maxLength": 128 }, "status": { "description": "Your status mapped to a Meta event by the source's flow, e.g. QUALIFIED or purchase.", "x-pl-description": "Twój status zamapowany na zdarzenie Meta przez przepływ źródła, np. QUALIFIED albo purchase.", "type": "string", "maxLength": 80 }, "consent": { "description": "Must be true: you confirm a legal basis for sending the data.", "x-pl-description": "Musi być true: potwierdzasz podstawę prawną przesłania danych.", "type": "boolean" }, "event_time": { "description": "Unix seconds or ISO 8601; at most 7 days old.", "x-pl-description": "Sekundy Unix lub ISO 8601; najwyżej 7 dni wstecz.", "oneOf": [ { "type": "integer" }, { "type": "string", "format": "date-time" } ] }, "event_id": { "description": "Meta deduplication id; generated from source + external_id + status when omitted.", "x-pl-description": "Identyfikator deduplikacji Meta; bez niego powstaje z source + external_id + status.", "type": "string" }, "email": { "description": "Customer e-mail (hashed with SHA-256 before storage).", "x-pl-description": "E-mail klienta (haszowany SHA-256 przed zapisem).", "type": "string" }, "phone": { "description": "Customer phone in E.164 (hashed).", "x-pl-description": "Telefon klienta w E.164 (haszowany).", "type": "string" }, "lead_id": { "description": "Meta lead id, when the conversion closes a Meta lead.", "x-pl-description": "Identyfikator leada Meta, gdy konwersja zamyka lead Meta.", "type": "string" }, "user_id": { "description": "Your customer id (hashed as external_id).", "x-pl-description": "Twój identyfikator klienta (haszowany jako external_id).", "type": "string" }, "fbp": { "description": "_fbp cookie.", "x-pl-description": "Ciasteczko _fbp.", "type": "string" }, "fbc": { "description": "_fbc cookie.", "x-pl-description": "Ciasteczko _fbc.", "type": "string" }, "event_source_url": { "description": "Page URL of the conversion.", "x-pl-description": "Adres strony konwersji.", "type": "string" }, "tracking_id": { "description": "Collector tracking id (Shoper).", "x-pl-description": "Identyfikator śledzenia kolektora (Shoper).", "type": "string" }, "client_ip_address": { "description": "Customer IP.", "x-pl-description": "IP klienta.", "type": "string" }, "client_user_agent": { "description": "Customer user agent.", "x-pl-description": "User agent klienta.", "type": "string" }, "value": { "description": "Conversion value (required for Purchase).", "x-pl-description": "Wartość konwersji (wymagana dla Purchase).", "type": "number" }, "currency": { "description": "ISO 4217 currency (required with value).", "x-pl-description": "Waluta ISO 4217 (wymagana z wartością).", "type": "string" }, "content_ids": { "description": "Product ids.", "x-pl-description": "Identyfikatory produktów.", "type": "array", "items": { "type": "string" } } }, "required": [ "source", "external_id", "status", "consent" ], "description": "The same rules as source ingest: dedupe on source + external_id + status, an event with the same identity and different data is refused (409 `event_conflict`).", "x-pl-description": "Te same zasady co przyjmowanie przez źródło: deduplikacja po source + external_id + status, zdarzenie o tej samej tożsamości z innymi danymi jest odrzucane (409 `event_conflict`).", "additionalProperties": false }, "EventAccepted": { "type": "object", "properties": { "event_id": { "description": "Convs event id.", "x-pl-description": "Identyfikator zdarzenia w Convs.", "type": "string" }, "deliveries_created": { "description": "New deliveries queued for Meta datasets.", "x-pl-description": "Nowe wysyłki dodane do kolejki dla datasetów Meta.", "type": "integer" }, "duplicates": { "description": "Deliveries skipped as duplicates.", "x-pl-description": "Wysyłki pominięte jako duplikaty.", "type": "integer" }, "sending_enabled": { "description": "False when the server does not send to Meta (queued only).", "x-pl-description": "false, gdy serwer nie wysyła do Meta (tylko kolejka).", "type": "boolean" } } }, "Delivery": { "type": "object", "properties": { "id": { "description": "Delivery id.", "x-pl-description": "Identyfikator wysyłki.", "type": "string" }, "event_id": { "description": "Convs event id.", "x-pl-description": "Identyfikator zdarzenia w Convs.", "type": "string" }, "target_id": { "description": "Meta receiver (dataset connection) id.", "x-pl-description": "Identyfikator odbiorcy Meta (połączenia z datasetem).", "type": "string" }, "dataset_id": { "description": "Meta dataset (pixel) id.", "x-pl-description": "Identyfikator datasetu (piksela) Meta.", "type": "string" }, "event_name": { "description": "Meta event name, e.g. Lead, Purchase.", "x-pl-description": "Nazwa zdarzenia Meta, np. Lead, Purchase.", "type": "string" }, "meta_event_id": { "description": "event_id sent to Meta.", "x-pl-description": "event_id wysłane do Meta.", "type": "string" }, "mode": { "description": "`test` or `live`.", "x-pl-description": "`test` albo `live`.", "type": "string" }, "status": { "description": "Delivery status.", "x-pl-description": "Status wysyłki.", "type": "string", "enum": [ "pending", "sending", "retry", "accepted", "failed", "cancelled" ] }, "attempts": { "description": "Attempts so far.", "x-pl-description": "Dotychczasowe próby.", "type": "integer" }, "last_error": { "description": "Last error, empty when none.", "x-pl-description": "Ostatni błąd, pusty gdy brak.", "type": "string" }, "accepted_at": { "description": "When Meta accepted it (receipt, not proof of attribution).", "x-pl-description": "Kiedy Meta przyjęła wysyłkę (odbiór, nie dowód atrybucji).", "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "description": "Next attempt.", "x-pl-description": "Następna próba.", "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "DeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "Event": { "type": "object", "properties": { "id": { "description": "Event id.", "x-pl-description": "Identyfikator zdarzenia.", "type": "string" }, "source_id": { "description": "Source id.", "x-pl-description": "Identyfikator źródła.", "type": "string" }, "external_id": { "description": "Your record id.", "x-pl-description": "Twój identyfikator rekordu.", "type": "string" }, "status": { "description": "Your status.", "x-pl-description": "Twój status.", "type": "string" }, "meta_event_id": { "description": "Meta deduplication id.", "x-pl-description": "Identyfikator deduplikacji Meta.", "type": "string" }, "event_time": { "description": "Event time.", "x-pl-description": "Czas zdarzenia.", "type": [ "string", "null" ], "format": "date-time" }, "value": { "description": "Value.", "x-pl-description": "Wartość.", "type": [ "number", "null" ] }, "currency": { "description": "Currency.", "x-pl-description": "Waluta.", "type": "string" }, "deliveries": { "description": "Deliveries of this event.", "x-pl-description": "Wysyłki tego zdarzenia.", "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "created_at": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "EventList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "CampaignReport": { "type": "object", "properties": { "from": { "description": "First day (organisation time zone).", "x-pl-description": "Pierwszy dzień (strefa czasowa organizacji).", "type": "string" }, "to": { "description": "Last day.", "x-pl-description": "Ostatni dzień.", "type": "string" }, "level": { "description": "Row level.", "x-pl-description": "Poziom wierszy.", "type": "string", "enum": [ "campaign", "adset", "ad" ] }, "totals": { "description": "Totals per currency: `current` and the `previous` period of the same length.", "x-pl-description": "Sumy w każdej walucie: `current` i poprzedni okres tej samej długości (`previous`).", "type": "array", "items": { "type": "object" } }, "rows": { "description": "One row per campaign / ad set / ad with `metrics` (spend, meta_leads, leads, qualified, rejected, sales, revenue, cost_per_lead, cost_per_qualified, cost_per_sale, revenue_per_spend; costs are null when the divisor is 0).", "x-pl-description": "Wiersz na kampanię / zestaw / reklamę z `metrics` (spend, meta_leads, leads, qualified, rejected, sales, revenue, cost_per_lead, cost_per_qualified, cost_per_sale, revenue_per_spend; koszty są null przy zerowym dzielniku).", "type": "array", "items": { "type": "object" } }, "organic": { "description": "Leads without a known ad.", "x-pl-description": "Zgłoszenia bez znanej reklamy.", "type": "object" }, "syncs": { "description": "Spend sync state per ad account.", "x-pl-description": "Stan synchronizacji wydatków na konto reklamowe.", "type": "array", "items": { "type": "object" } }, "maturing": { "description": "True when the range includes the last 30 days (sales may still come).", "x-pl-description": "Prawda, gdy zakres obejmuje ostatnie 30 dni (sprzedaże mogą jeszcze dojść).", "type": "boolean" }, "unattributed": { "description": "Leads of the period with a known source but no id at this level.", "x-pl-description": "Zgłoszenia z okresu ze znanym źródłem, ale bez identyfikatora na tym poziomie.", "type": "integer" } }, "description": "The same numbers as the Kampanie page. Leads are counted by lead date (cohort), a sale once per person and cycle.", "x-pl-description": "Te same liczby co na stronie Kampanie. Zgłoszenia liczone są według daty zgłoszenia (kohorta), sprzedaż raz na osobę i cykl." }, "CreativeReport": { "type": "object", "properties": { "from": { "description": "First day.", "x-pl-description": "Pierwszy dzień.", "type": "string" }, "to": { "description": "Last day.", "x-pl-description": "Ostatni dzień.", "type": "string" }, "weeks": { "description": "Week ranges used for momentum.", "x-pl-description": "Zakresy tygodni użyte do trendu.", "type": "array", "items": { "type": "array" } }, "rows": { "description": "One row per creative group (same video, image or creative) with metrics, weekly trend, fatigue verdict and tags.", "x-pl-description": "Wiersz na grupę kreacji (ten sam film, obraz lub kreacja) z metrykami, trendem tygodniowym, oceną zmęczenia i tagami.", "type": "array", "items": { "type": "object" } }, "totals": { "description": "Totals per currency.", "x-pl-description": "Sumy w każdej walucie.", "type": "array", "items": { "type": "object" } }, "syncs": { "description": "Spend sync state per ad account.", "x-pl-description": "Stan synchronizacji wydatków na konto reklamowe.", "type": "array", "items": { "type": "object" } }, "unattributed": { "description": "Leads without a known creative.", "x-pl-description": "Zgłoszenia bez znanej kreacji.", "type": "integer" } }, "description": "The same numbers as the Kreacje page.", "x-pl-description": "Te same liczby co na stronie Kreacje." }, "Job": { "type": "object", "properties": { "number": { "description": "Job number within the organisation.", "x-pl-description": "Numer zadania w organizacji.", "type": "integer" }, "kind": { "description": "Job kind, e.g. lead_import, ad_spend, sheets_sync.", "x-pl-description": "Rodzaj zadania, np. lead_import, ad_spend, sheets_sync.", "type": "string" }, "label": { "description": "Description.", "x-pl-description": "Opis.", "type": "string" }, "status": { "description": "Status.", "x-pl-description": "Status.", "type": "string", "enum": [ "queued", "running", "done", "failed", "cancelled" ] }, "priority": { "description": "`user` or `background`.", "x-pl-description": "`user` albo `background`.", "type": "string" }, "trigger": { "description": "What started it.", "x-pl-description": "Co je uruchomiło.", "type": "string" }, "progress": { "description": "`done` count and `text`.", "x-pl-description": "Licznik `done` i opis `text`.", "type": "object" }, "attempts": { "description": "Attempts.", "x-pl-description": "Próby.", "type": "integer" }, "error": { "description": "Error text of a failed job.", "x-pl-description": "Błąd nieudanego zadania.", "type": "string" }, "summary": { "description": "Result summary.", "x-pl-description": "Podsumowanie wyniku.", "type": "string" }, "run_after": { "description": "Not before.", "x-pl-description": "Nie wcześniej niż.", "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "description": "Start.", "x-pl-description": "Start.", "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "description": "End.", "x-pl-description": "Koniec.", "type": [ "string", "null" ], "format": "date-time" }, "created": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "JobList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "Webhook": { "type": "object", "properties": { "id": { "description": "Webhook id.", "x-pl-description": "Identyfikator webhooka.", "type": "string" }, "url": { "description": "HTTPS endpoint that receives POSTs.", "x-pl-description": "Adres HTTPS, który odbiera POST-y.", "type": "string" }, "description": { "description": "Your note.", "x-pl-description": "Twój opis.", "type": "string" }, "events": { "description": "Subscribed events.", "x-pl-description": "Subskrybowane zdarzenia.", "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.stage_changed", "lead.created", "delivery.failed" ] } }, "active": { "description": "False pauses deliveries.", "x-pl-description": "false wstrzymuje wysyłki.", "type": "boolean" }, "last_status": { "description": "HTTP status of the last attempt (0 = no answer).", "x-pl-description": "Status HTTP ostatniej próby (0 = brak odpowiedzi).", "type": "integer" }, "last_error": { "description": "Last error.", "x-pl-description": "Ostatni błąd.", "type": "string" }, "last_delivery_at": { "description": "Last attempt.", "x-pl-description": "Ostatnia próba.", "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "description": "Failed attempts in a row.", "x-pl-description": "Nieudane próby z rzędu.", "type": "integer" }, "created_at": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "description": "Signing secret (`whsec_…`). Shown only in this response — store it.", "x-pl-description": "Sekret podpisu (`whsec_…`). Widoczny tylko w tej odpowiedzi — zapisz go.", "type": "string" } }, "required": [ "secret" ] } ] }, "WebhookList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "WebhookCreate": { "type": "object", "properties": { "url": { "description": "HTTPS URL (no credentials, no private or local addresses).", "x-pl-description": "Adres HTTPS (bez loginu i hasła, bez adresów prywatnych i lokalnych).", "type": "string", "maxLength": 2000 }, "events": { "description": "Events to receive.", "x-pl-description": "Zdarzenia do odbierania.", "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.stage_changed", "lead.created", "delivery.failed" ] } }, "description": { "description": "Your note.", "x-pl-description": "Twój opis.", "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ], "additionalProperties": false }, "WebhookUpdate": { "type": "object", "properties": { "url": { "description": "New URL.", "x-pl-description": "Nowy adres.", "type": "string" }, "events": { "description": "New event list.", "x-pl-description": "Nowa lista zdarzeń.", "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.stage_changed", "lead.created", "delivery.failed" ] } }, "description": { "description": "Your note.", "x-pl-description": "Twój opis.", "type": "string" }, "active": { "description": "Pause or resume.", "x-pl-description": "Wstrzymaj lub wznów.", "type": "boolean" } }, "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "description": "Delivery id (header X-Convs-Delivery).", "x-pl-description": "Identyfikator wysyłki (nagłówek X-Convs-Delivery).", "type": "string" }, "webhook_id": { "description": "Webhook id.", "x-pl-description": "Identyfikator webhooka.", "type": "string" }, "event": { "description": "Event type.", "x-pl-description": "Typ zdarzenia.", "type": "string" }, "event_id": { "description": "Event id (`evt_…`, the same for every webhook of one event).", "x-pl-description": "Identyfikator zdarzenia (`evt_…`, ten sam dla wszystkich webhooków jednego zdarzenia).", "type": "string" }, "status": { "description": "Status.", "x-pl-description": "Status.", "type": "string", "enum": [ "pending", "sending", "retry", "delivered", "failed", "cancelled" ] }, "attempts": { "description": "Attempts.", "x-pl-description": "Próby.", "type": "integer" }, "response_status": { "description": "HTTP status of the last attempt.", "x-pl-description": "Status HTTP ostatniej próby.", "type": "integer" }, "last_error": { "description": "Last error.", "x-pl-description": "Ostatni błąd.", "type": "string" }, "next_attempt_at": { "description": "Next attempt.", "x-pl-description": "Następna próba.", "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "description": "Delivered at.", "x-pl-description": "Dostarczono.", "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "description": "Creation time.", "x-pl-description": "Czas utworzenia.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last change.", "x-pl-description": "Ostatnia zmiana.", "type": "string", "format": "date-time" } } }, "WebhookDeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "description": "Pass as `cursor` to get the next page; null on the last page.", "x-pl-description": "Przekaż jako `cursor`, by pobrać następną stronę; null na ostatniej stronie.", "type": [ "string", "null" ] }, "has_more": { "description": "True when another page exists.", "x-pl-description": "Prawda, gdy istnieje kolejna strona.", "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "description": "Event id `evt_…`; use it to ignore repeats (delivery is at least once).", "x-pl-description": "Identyfikator `evt_…`; użyj go, by pominąć powtórzenia (dostarczanie co najmniej raz).", "type": "string" }, "type": { "description": "Event type.", "x-pl-description": "Typ zdarzenia.", "type": "string", "enum": [ "contact.created", "contact.stage_changed", "lead.created", "delivery.failed", "ping" ] }, "created_at": { "description": "When it happened.", "x-pl-description": "Kiedy to się stało.", "type": "string", "format": "date-time" }, "organization_id": { "description": "Organisation id.", "x-pl-description": "Identyfikator organizacji.", "type": "string" }, "data": { "description": "Ids and states only — read names, phones and e-mails with GET using your key.", "x-pl-description": "Tylko identyfikatory i stany — imiona, telefony i e-maile pobierz przez GET swoim kluczem.", "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "created_at", "organization_id", "data" ] }, "WebhookTest": { "type": "object", "properties": { "delivery_id": { "description": "Queued delivery of a `ping` event.", "x-pl-description": "Wysyłka zdarzenia `ping` dodana do kolejki.", "type": "string" } } }, "Me": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "rate_limit": { "type": "object", "properties": { "per_minute": { "type": "integer" } } } } } } } }