{"openapi":"3.1.0","info":{"title":"Comvo API","version":"2.1.8","description":"With the Comvo API you can create personalized survey invitations, send surveys automatically from transaction events, read responses and metrics, sync your organization structure and receive events via webhooks.\n\n## Quick Start\n\n1. In the panel, create a key on the **Ayarlar › API Anahtarları** (Settings › API Keys) screen. Make your first attempts with an `sk_test_` key: invitations and responses created with a test key are kept separate from live data and do not appear in reports.\n2. Verify the key:\n\n```bash\ncurl https://my.comvo.com.tr/api/me \\\n  -H \"Authorization: Bearer sk_test_...\"\n```\n\n3. Get a personalized survey link for a transaction (an order, a service record):\n\n```bash\ncurl -X POST https://my.comvo.com.tr/api/invitations \\\n  -H \"Authorization: Bearer sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: siparis-98123\" \\\n  -d '{\n    \"survey\": \"srv_...\",\n    \"org_unit\": \"IST-034\",\n    \"transaction_ref\": \"98123\",\n    \"contact\": { \"external_id\": \"C-5521\", \"name\": \"Ayşe Yılmaz\", \"email\": \"ayse@example.com\" }\n  }'\n# 201 { \"id\": \"inv_...\", \"url\": \"https://my.comvo.com.tr/s/...\", ... }\n```\n\nThe `url` in the response is the single-use link to send to the contact, and it is returned only in this response. Every field in the context (unit, transaction number, customer number, contact details, custom fields) must be covered by the brand's current privacy notice; otherwise the request is rejected with the `privacy_notice_not_covering` error.\n\n## Authentication\n\nSend the `Authorization: Bearer sk_live_...` header with every request. A key can only use the scopes selected when it was created; a key restricted to a unit sees only that unit and the units below it. Test keys (`sk_test_`) cannot access live data.\n\n## Idempotency\n\nSend an `Idempotency-Key` header with write requests. The same request arriving with the same key within 24 hours is not processed again; the first response is returned with the `Idempotent-Replayed: true` header. If the same key arrives with a different body, 422 is returned.\n\n## Pagination\n\nLists are cursor-based. Send the `next_cursor` value from the response with the `?cursor=` parameter; when `has_more` is `false`, the list has ended. `limit` is at most 100.\n\n## Rate Limit\n\nEach key can make 600 requests per minute, and 30 requests per minute on bulk endpoints. Watch the `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers; when you receive a 429 response, wait for the `Retry-After` period.\n\n## Time, IDs and Personal Data\n\nTimes are in ISO 8601 format and in UTC. IDs are prefixed: `srv_` (survey), `inv_` (invitation), `rsp_` (response), `org_` (unit). Name, email and phone appear in responses only with the `responses:pii` scope; if the contact chose to stay anonymous, they never appear.\n\n## Webhooks\n\nTo receive events, add an address in the panel on the **Ayarlar › Webhook'lar** (Settings › Webhooks) screen or with the `/webhook-endpoints` endpoint. Every request is signed with this header:\n\n```\nWebhook-Signature: t=<timestamp>,v1=<HMAC-SHA256(secret, \"timestamp.body\")>\n```\n\nIn the panel, the **Teknik Rehber** (Technical Guide) tab of each webhook contains verification code for PHP, Node.js and Python along with a sample payload. Respond to the request with a 2xx within 10 seconds; otherwise it is retried according to the webhook's failure policy.\n\n## Error Codes\n\nErrors use the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` format. Base your handling on the `code` field; the `detail` field is meant for humans.\n\n```json\n{ \"type\": \"https://my.comvo.com.tr/developers#errors-validation_failed\", \"title\": \"Doğrulama hatası\", \"status\": 422,\n  \"code\": \"validation_failed\", \"detail\": \"...\", \"errors\": { \"survey\": [\"Anket bulunamadı.\"] } }\n```\n\n| Code | Status | Meaning and what to do |\n| --- | --- | --- |\n| `unauthenticated` | 401 | The Authorization header is missing or malformed. |\n| `invalid_key` | 401 | The key was not found, has been revoked or has expired. Create a new key in the panel. |\n| `insufficient_scope` | 403 | The key does not have the scope for this operation (given in the required_scope field). Create the key again with the new scope. |\n| `outside_scope` | 403 | A key restricted to a unit cannot access this record or a tenant-wide operation. |\n| `forbidden` | 403 | The operation is not permitted. |\n| `not_found` | 404 | The record does not exist or is outside the key's access area (unit, live/test mode). |\n| `method_not_allowed` | 405 | This address does not support this HTTP method. |\n| `invitation_completed` | 409 | An invitation that has been answered cannot be cancelled. |\n| `idempotency_in_progress` | 409 | The first request with the same Idempotency-Key is still being processed; try again shortly. |\n| `invalid_idempotency_key` | 400 | The Idempotency-Key is empty or longer than 255 characters. |\n| `idempotency_mismatch` | 422 | The same Idempotency-Key was used with a different body. |\n| `validation_failed` | 422 | The submitted data contains errors; field-level details are in errors. |\n| `survey_not_live` | 422 | The survey is not live; an invitation cannot be opened. |\n| `unknown_context_field` | 422 | A field in the context is not defined in the panel under KVKK ve Veri > Alanlar (KVKK and Data > Fields; KVKK is Turkey's Personal Data Protection Law, No. 6698) (fields). |\n| `privacy_notice_not_covering` | 422 | The fields are not covered by the brand's current privacy notice (fields). Add them to the notice and publish it. |\n| `invalid_assignee` | 422 | The member to be assigned does not exist or is not authorized to manage this response. |\n| `invalid_level` | 422 | The level name was not found, or no level is defined below the parent unit. |\n| `range_too_long` | 422 | The metric range is at most 366 days. |\n| `rate_limited` | 429 | The rate limit was exceeded; wait for the Retry-After period. |\n| `server_error` | 500 | Unexpected error. You can safely retry with an Idempotency-Key. |"},"servers":[{"url":"https://my.comvo.com.tr/api"}],"tags":[{"name":"Identity"},{"name":"Surveys"},{"name":"Events"},{"name":"Invitations"},{"name":"Contacts"},{"name":"Responses"},{"name":"Organization"},{"name":"Metrics"},{"name":"Webhooks"}],"paths":{"/me":{"get":{"tags":["Identity"],"summary":"Key Information","security":[{"bearer":[]}],"x-scope":"","description":"For testing your integration: whether the key is valid and which scopes it has.","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getMe"}},"/surveys":{"get":{"tags":["Surveys"],"summary":"List Surveys","security":[{"bearer":[]}],"x-scope":"surveys:read","description":"\n\nScope: `surveys:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listSurveys","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/surveys/{id}":{"get":{"tags":["Surveys"],"summary":"Survey and Its Questions","security":[{"bearer":[]}],"x-scope":"surveys:read","description":"\n\nScope: `surveys:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Survey"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getSurvey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"srv_..."}]}},"/events":{"post":{"tags":["Events"],"summary":"Send Event","security":[{"bearer":[]}],"x-scope":"events:write","description":"Send transaction events (order delivered, service record closed, call ended). For every active trigger linked to this type in the panel, the following are checked: whether the survey is live, whether the contact has opted out, the frequency limit and the channel (based on the contact's email/phone details); if all conditions are met, an invitation is opened and a delayed message is scheduled. Use `Idempotency-Key` to avoid sending the same event twice.\n\nScope: `events:write`","responses":{"202":{"description":"Accepted; returns which trigger will send a survey, when and through which channel, or why it was skipped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"$ref":"#/components/responses/E400"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createEvent","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventInput"}}}}}},"/events/batch":{"post":{"tags":["Events"],"summary":"Bulk Events (up to 500)","security":[{"bearer":[]}],"x-scope":"events:write","description":"\n\nScope: `events:write`","responses":{"202":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBatchResult"}}}},"400":{"$ref":"#/components/responses/E400"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createEventBatch","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["events"],"properties":{"events":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/EventInput"}}}}}}}}},"/events/{id}":{"get":{"tags":["Events"],"summary":"Event Result","security":[{"bearer":[]}],"x-scope":"events:write","description":"\n\nScope: `events:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getEvent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"evt_..."}]}},"/contacts/{external_id}":{"get":{"tags":["Contacts"],"summary":"Contact","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"\n\nScope: `contacts:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your customer number"}]},"put":{"tags":["Contacts"],"summary":"Create or Update Contact","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"With `opted_out: true` the contact is removed from survey messages (to sync with your own consent management).\n\nScope: `contacts:write`","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your customer number"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}}},"delete":{"tags":["Contacts"],"summary":"KVKK: Delete Contact","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"The contact record and contact details are deleted; their responses are detached from the contact and anonymized (they remain in statistics), personal context fields and contact answers are deleted, and pending messages are cancelled. This cannot be undone.\n\nScope: `contacts:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactErasure"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"eraseContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your customer number"}]}},"/contacts/{external_id}/export":{"get":{"tags":["Contacts"],"summary":"KVKK: Export Contact Data","security":[{"bearer":[]}],"x-scope":"contacts:write","description":"For a right of access request: contact, invitations, messages and responses.\n\nScope: `contacts:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactExport"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"exportContact","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your customer number"}]}},"/invitations":{"post":{"tags":["Invitations"],"summary":"Create Invitation","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"A personalized single-use link. Every field in the context must be covered by the current privacy notice; otherwise `privacy_notice_not_covering` (422).\n\nScope: `invitations:write`","responses":{"201":{"description":"Created; `url` is the link to send to the contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"400":{"$ref":"#/components/responses/E400"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createInvitation","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationInput"}}}}}},"/invitations/batch":{"post":{"tags":["Invitations"],"summary":"Bulk Invitations (up to 1000)","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"A faulty item does not stop the others; results are returned in item order.\n\nScope: `invitations:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"$ref":"#/components/responses/E400"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createInvitationBatch","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invitations"],"properties":{"invitations":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/InvitationInput"}}}}}}}}},"/invitations/{id}":{"get":{"tags":["Invitations"],"summary":"Invitation Status","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"\n\nScope: `invitations:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getInvitation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"inv_..."}]}},"/invitations/{id}/cancel":{"post":{"tags":["Invitations"],"summary":"Cancel Invitation","security":[{"bearer":[]}],"x-scope":"invitations:write","description":"\n\nScope: `invitations:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"cancelInvitation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"inv_..."},{"$ref":"#/components/parameters/idempotency"}]}},"/responses":{"get":{"tags":["Responses"],"summary":"List Responses","security":[{"bearer":[]}],"x-scope":"responses:read","description":"Only completed responses, according to the key's mode (live/test) and unit restriction. Personal data only with the `responses:pii` scope.\n\nScope: `responses:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseList"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listResponses","parameters":[{"name":"survey","in":"query","required":false,"schema":{"type":"string"},"description":"Survey ID"},{"name":"org_unit","in":"query","required":false,"schema":{"type":"string"},"description":"Unit code or ID (including the subtree)"},{"name":"touchpoint","in":"query","required":false,"schema":{"type":"string"},"description":"Touchpoint key"},{"name":"transaction_ref","in":"query","required":false,"schema":{"type":"string"},"description":"Transaction number (order, receipt)"},{"name":"case_status","in":"query","required":false,"schema":{"enum":["new","in_progress","resolved"]},"description":"Case status"},{"name":"priority","in":"query","required":false,"schema":{"enum":["normal","high","critical"]},"description":"Priority"},{"name":"completed_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Completed after this time"},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Changed after this time (for syncing)"},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"]},"description":"Sort order (default desc)"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/responses/{id}":{"get":{"tags":["Responses"],"summary":"Response","security":[{"bearer":[]}],"x-scope":"responses:read","description":"\n\nScope: `responses:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getResponse","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."}]},"patch":{"tags":["Responses"],"summary":"Change Case Status, Priority or Assignee","security":[{"bearer":[]}],"x-scope":"responses:write","description":"The change is written to the case history as \"API: key name\", and a case.* event is sent to subscribed webhooks.\n\nScope: `responses:write`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"updateResponse","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseUpdate"}}}}}},"/responses/{id}/notes":{"post":{"tags":["Responses"],"summary":"Add Note to Case","security":[{"bearer":[]}],"x-scope":"responses:write","description":"\n\nScope: `responses:write`","responses":{"201":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Note"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createNote","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"rsp_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":5000}}}}}}}},"/org-units":{"get":{"tags":["Organization"],"summary":"List Units","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nScope: `org:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnitList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listOrgUnits","parameters":[{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Changed after this time"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/org-units/{code}":{"get":{"tags":["Organization"],"summary":"Unit","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nScope: `org:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getOrgUnit","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Unit code or ID"}]},"put":{"tags":["Organization"],"summary":"Create or Update Unit by Code","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nScope: `org:write`","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnit"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putOrgUnit","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Unit code in the external system (letters, digits, . _ -)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUnitInput"}}}}}},"/people/{code}":{"put":{"tags":["Organization"],"summary":"Create or Update Staff Member by Code","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nScope: `org:write`","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putPerson","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"},"description":"Staff code"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"org_unit":{"type":"string"},"email":{"type":"string","format":"email"},"is_active":{"type":"boolean"}}}}}}}},"/touchpoints":{"get":{"tags":["Organization"],"summary":"List Touchpoints","security":[{"bearer":[]}],"x-scope":"org:read","description":"\n\nScope: `org:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TouchpointList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listTouchpoints","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/touchpoints/{key}":{"put":{"tags":["Organization"],"summary":"Create or Update Touchpoint by Key","security":[{"bearer":[]}],"x-scope":"org:write","description":"\n\nScope: `org:write`","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Touchpoint"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Touchpoint"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"putTouchpoint","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Key (lowercase letters, digits, _)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"is_active":{"type":"boolean"}}}}}}}},"/metrics":{"get":{"tags":["Metrics"],"summary":"CSAT, NPS, CES and Breakdown","security":[{"bearer":[]}],"x-scope":"reports:read","description":"Calculated the same way as panel reports: live, completed, non-suspicious responses; days in the tenant's time zone.\n\nScope: `reports:read`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metrics"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getMetrics","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","required":false,"schema":{"enum":["org_unit","touchpoint","person","channel","survey","day"]},"description":"Breakdown"},{"name":"level","in":"query","required":false,"schema":{"type":"string"},"description":"Level name for group_by=org_unit (e.g. Region)"},{"name":"survey","in":"query","required":false,"schema":{"type":"string"},"description":"Survey ID"},{"name":"org_unit","in":"query","required":false,"schema":{"type":"string"},"description":"Unit code (subtree)"},{"name":"touchpoint","in":"query","required":false,"schema":{"type":"string"},"description":"Touchpoint ID"},{"name":"channel","in":"query","required":false,"schema":{"type":"string"},"description":"qr, email, sms, link"}]}},"/webhook-endpoints":{"get":{"tags":["Webhooks"],"summary":"List Webhooks","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listWebhookEndpoints","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]},"post":{"tags":["Webhooks"],"summary":"Create Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"201":{"description":"Created; `secret` only in this response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"createWebhookEndpoint","parameters":[{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}}},"/webhook-endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"getWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."}]},"patch":{"tags":["Webhooks"],"summary":"Update Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"$ref":"#/components/responses/E404"},"422":{"$ref":"#/components/responses/E422"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"updateWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."},{"$ref":"#/components/parameters/idempotency"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete Webhook","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"deleteWebhookEndpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whk_..."}]}},"/webhook-deliveries":{"get":{"tags":["Webhooks"],"summary":"Delivery Log","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"listWebhookDeliveries","parameters":[{"name":"endpoint","in":"query","required":false,"schema":{"type":"string"},"description":"whk_..."},{"name":"status","in":"query","required":false,"schema":{"enum":["pending","sending","retrying","succeeded","failed"]},"description":"Status"},{"name":"event","in":"query","required":false,"schema":{"type":"string"},"description":"Event"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}]}},"/webhook-deliveries/{id}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Resend","security":[{"bearer":[]}],"x-scope":"webhooks:manage","description":"\n\nScope: `webhooks:manage`","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"404":{"$ref":"#/components/responses/E404"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"operationId":"redeliverWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"whd_..."},{"$ref":"#/components/parameters/idempotency"}]}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_... / sk_test_..."}},"parameters":{"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"The next_cursor value of the previous page"},"idempotency":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Prevents the same request from being processed twice (24 hours)"}},"responses":{"E400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E401":{"description":"Authentication failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E403":{"description":"Insufficient scope or outside the access area","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E404":{"description":"Not found (or outside the key's access area)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E422":{"description":"Validation or business rule error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E429":{"description":"Rate limit exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string","description":"Machine-readable error code"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"fields":{"type":"array","items":{"type":"string"}},"required_scope":{"type":"string"}}},"Me":{"type":"object","required":["object","id","name","tenant","scopes","org_unit","livemode","expires_at"],"additionalProperties":false,"properties":{"object":{"const":"api_key"},"id":{"type":"string","pattern":"^key_[0-9a-z]{26}$","examples":["key_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"tenant":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","pattern":"^ten_[0-9a-z]{26}$","examples":["ten_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"scopes":{"type":"array","items":{"enum":["surveys:read","invitations:write","events:write","contacts:write","responses:read","responses:pii","responses:write","org:read","org:write","reports:read","webhooks:manage"]}},"org_unit":{"type":["string","null"]},"livemode":{"type":"boolean"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"Survey":{"type":"object","required":["object","id","name","status","live","version","locales","touchpoint","created_at","updated_at"],"additionalProperties":false,"properties":{"object":{"const":"survey"},"id":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"status":{"enum":["draft","active","paused","archived"]},"live":{"type":"boolean"},"version":{"type":["integer","null"]},"locales":{"type":"array","items":{"type":"string"}},"touchpoint":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"questions":{"type":"array","items":{"type":"object","required":["key","type","title","metric","required","options"],"properties":{"key":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"metric":{"type":["string","null"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","required":["key","label"],"properties":{"key":{"type":"string"},"label":{"type":"string"}}}}}}}}},"InvitationInput":{"type":"object","required":["survey"],"additionalProperties":false,"properties":{"survey":{"type":"string","description":"Survey ID (srv_...)"},"org_unit":{"type":"string","description":"Unit code (e.g. IST-034) or ID"},"person":{"type":"string","description":"Staff code"},"touchpoint":{"type":"string","description":"Touchpoint key; if omitted, the survey's own"},"transaction_ref":{"type":"string","maxLength":128,"description":"Order, receipt or service record number"},"contact":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"locale":{"enum":["tr","en","ar","ru","de"]}}},"context":{"type":"object","description":"Context fields defined in the panel; must be covered by the privacy notice","additionalProperties":{"type":["string","number","boolean"]}},"max_uses":{"type":"integer","minimum":1,"maximum":100,"default":1},"expires_at":{"type":"string","format":"date-time","description":"Default 30 days"}}},"Invitation":{"type":"object","required":["object","id","survey","status","url","channel","org_unit","person","touchpoint","contact","transaction_ref","context","max_uses","uses","expires_at","livemode","created_at"],"additionalProperties":false,"properties":{"object":{"const":"invitation"},"id":{"type":"string","pattern":"^inv_[0-9a-z]{26}$","examples":["inv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"status":{"enum":["pending","sent","started","responded","cancelled","expired"]},"url":{"type":["string","null"],"format":"uri","description":"Personalized link. Filled only in the create response; the system does not store the token."},"channel":{"type":"string"},"org_unit":{"type":["string","null"]},"person":{"type":["string","null"]},"touchpoint":{"type":["string","null"]},"contact":{"type":["object","null"],"required":["id","external_id"],"properties":{"id":{"type":"string","pattern":"^con_[0-9a-z]{26}$","examples":["con_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"external_id":{"type":["string","null"]}}},"transaction_ref":{"type":["string","null"]},"context":{"type":"object"},"max_uses":{"type":"integer"},"uses":{"type":"integer"},"expires_at":{"type":["string","null"],"format":"date-time"},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"BatchResult":{"type":"object","required":["object","created","failed","results"],"properties":{"object":{"const":"batch_result"},"created":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["index","ok"],"properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"invitation":{"$ref":"#/components/schemas/Invitation"},"error":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}}}},"Response":{"type":"object","required":["object","id","survey","unit","touchpoint","person","channel","locale","completed_at","transaction_ref","scores","case","anonymous","contact","answers","panel_url"],"additionalProperties":false,"properties":{"object":{"const":"response"},"id":{"type":"string","pattern":"^rsp_[0-9a-z]{26}$","examples":["rsp_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"object","required":["id","name","version"],"properties":{"id":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"version":{"type":"integer"}}},"unit":{"type":["object","null"],"required":["id","name","code","level"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^org_[0-9a-z]{26}$","examples":["org_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"code":{"type":["string","null"]},"level":{"type":["string","null"]}}},"touchpoint":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^tch_[0-9a-z]{26}$","examples":["tch_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"person":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^per_[0-9a-z]{26}$","examples":["per_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"channel":{"type":"string"},"locale":{"type":"string"},"completed_at":{"type":["string","null"],"format":"date-time"},"transaction_ref":{"type":["string","null"]},"scores":{"type":"object","required":["csat","ces","nps"],"properties":{"csat":{"type":["number","null"]},"ces":{"type":["number","null"]},"nps":{"type":["integer","null"]}}},"case":{"type":"object","required":["status","priority","flagged","assignee","due_at"],"properties":{"status":{"enum":["new","in_progress","resolved"]},"priority":{"enum":["normal","high","critical"]},"flagged":{"type":"boolean"},"assignee":{"type":["object","null"],"required":["id","name"],"additionalProperties":false,"properties":{"id":{"type":"string","pattern":"^mem_[0-9a-z]{26}$","examples":["mem_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"}}},"due_at":{"type":["string","null"],"format":"date-time"},"resolution_code":{"type":["string","null"],"description":"Closure code selected on resolution (Vaka Ayarları (Case Settings) in the panel)"},"follow_up_result":{"enum":["resolved","partly","not_resolved",null],"description":"The customer's answer in the resolution satisfaction survey"}}},"anonymous":{"type":"boolean"},"contact":{"type":["object","null"],"description":"Only with the `responses:pii` scope and if the contact is not anonymous","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"external_id":{"type":["string","null"]}}},"answers":{"type":"array","items":{"type":"object","required":["key","type","title","metric","value","label"],"additionalProperties":false,"properties":{"key":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"metric":{"type":["string","null"]},"value":{"description":"Number, option key, array of keys or text"},"label":{"description":"Option label (may be an array) or null"}}}},"panel_url":{"type":"string","format":"uri"}}},"ResponseUpdate":{"type":"object","additionalProperties":false,"properties":{"case_status":{"enum":["new","in_progress","resolved"]},"priority":{"enum":["normal","high","critical"]},"assignee":{"type":["string","null"],"description":"Member ID (mem_...); null = remove the assignment"},"resolution_code":{"type":["string","null"],"description":"Closure code key, with case_status=resolved"}}},"Note":{"type":"object","required":["object","id","response","body","created_at"],"properties":{"object":{"const":"note"},"id":{"type":"string","pattern":"^act_[0-9a-z]{26}$","examples":["act_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"response":{"type":"string","pattern":"^rsp_[0-9a-z]{26}$","examples":["rsp_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"OrgUnit":{"type":"object","required":["object","id","code","name","level","depth","parent","city","address","is_active","updated_at"],"additionalProperties":false,"properties":{"object":{"const":"org_unit"},"id":{"type":"string","pattern":"^org_[0-9a-z]{26}$","examples":["org_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"code":{"type":["string","null"]},"name":{"type":"string"},"level":{"type":["string","null"]},"depth":{"type":["integer","null"]},"parent":{"type":["string","null"]},"city":{"type":["string","null"]},"address":{"type":["string","null"]},"is_active":{"type":"boolean"},"updated_at":{"type":"string","format":"date-time"}}},"OrgUnitInput":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string"},"parent":{"type":["string","null"],"description":"Parent unit code; if it changes, the unit is moved"},"level":{"type":"string","description":"Level name; if omitted, one level below the parent"},"city":{"type":"string"},"address":{"type":"string"},"review_url":{"type":"string","format":"uri"},"is_active":{"type":"boolean"}}},"Person":{"type":"object","required":["object","id","code","name","org_unit","is_active"],"additionalProperties":false,"properties":{"object":{"const":"person"},"id":{"type":"string","pattern":"^per_[0-9a-z]{26}$","examples":["per_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"code":{"type":["string","null"]},"name":{"type":"string"},"org_unit":{"type":["string","null"]},"is_active":{"type":"boolean"}}},"Touchpoint":{"type":"object","required":["object","id","key","name","description","is_active"],"additionalProperties":false,"properties":{"object":{"const":"touchpoint"},"id":{"type":"string","pattern":"^tch_[0-9a-z]{26}$","examples":["tch_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"is_active":{"type":"boolean"}}},"MetricSet":{"type":"object","required":["count","csat","satisfied","ces","nps","promoters","detractors","nps_count","critical"],"properties":{"count":{"type":"integer"},"csat":{"type":["number","null"]},"satisfied":{"type":["number","null"],"description":"Percentage of CSAT >= 4"},"ces":{"type":["number","null"]},"nps":{"type":["integer","null"]},"promoters":{"type":["number","null"]},"detractors":{"type":["number","null"]},"nps_count":{"type":"integer"},"critical":{"type":"integer"},"review_offered":{"type":"integer","description":"Shown the Google review invitation"},"review_clicked":{"type":"integer","description":"Clicked the invitation"}}},"Metrics":{"type":"object","required":["object","range","summary","previous"],"properties":{"object":{"const":"metrics"},"range":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"summary":{"$ref":"#/components/schemas/MetricSet"},"previous":{"$ref":"#/components/schemas/MetricSet","description":"Previous period of the same length"},"groups":{"type":"array","items":{"type":"object","required":["key","name","count","csat"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"},"csat":{"type":["number","null"]},"satisfied":{"type":["number","null"]},"nps":{"type":["integer","null"]},"critical":{"type":"integer"},"delta":{"type":["number","null"]}}}}}},"WebhookEndpoint":{"type":"object","required":["object","id","name","url","events","filters","include_pii","header_names","is_active","retry_every_minutes","give_up_after_minutes","notify_on_failure","notify_emails","disable_after_failures","disabled_reason","created_at"],"properties":{"object":{"const":"webhook_endpoint"},"id":{"type":"string","pattern":"^whk_[0-9a-z]{26}$","examples":["whk_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["response.completed","response.flagged","case.assigned","case.status_changed","case.resolved","case.escalated"]}},"filters":{"type":"object","properties":{"surveys":{"type":"array","items":{"type":"string"}},"unit":{"type":"string"},"min_priority":{"enum":["high","critical"]}}},"include_pii":{"type":"boolean"},"header_names":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"retry_every_minutes":{"type":"integer"},"give_up_after_minutes":{"type":"integer","description":"0 = no retries"},"notify_on_failure":{"type":"boolean"},"notify_emails":{"type":"array","items":{"type":"string"}},"disable_after_failures":{"type":["integer","null"]},"disabled_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Only in the create response"}}},"WebhookEndpointInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["response.completed","response.flagged","case.assigned","case.status_changed","case.resolved","case.escalated"]}},"filters":{"type":"object"},"include_pii":{"type":"boolean"},"headers":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"value":{"type":["string","null"]}}}},"retry_every_minutes":{"type":"integer","minimum":1,"maximum":1440,"default":5},"give_up_after_minutes":{"type":"integer","minimum":0,"maximum":10080,"default":1440},"notify_on_failure":{"type":"boolean"},"notify_emails":{"type":"array","items":{"type":"string","format":"email"}},"disable_after_failures":{"type":["integer","null"]},"is_active":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","required":["object","id","endpoint","event","event_id","status","attempts","last_status_code","last_error","next_attempt_at","created_at"],"additionalProperties":false,"properties":{"object":{"const":"webhook_delivery"},"id":{"type":"string","pattern":"^whd_[0-9a-z]{26}$","examples":["whd_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"endpoint":{"type":"string","pattern":"^whk_[0-9a-z]{26}$","examples":["whk_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"event":{"type":"string"},"event_id":{"type":"string"},"status":{"enum":["pending","sending","retrying","succeeded","failed"]},"attempts":{"type":"integer"},"last_status_code":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"EventInput":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","pattern":"^[a-z0-9][a-z0-9_.]{0,63}$","description":"Event type; triggers linked to this type in the panel run (e.g. order_delivered)"},"occurred_at":{"type":"string","format":"date-time","description":"Time of the event; the delay is added to it. If omitted, now."},"contact":{"type":"object","additionalProperties":false,"properties":{"external_id":{"type":"string","description":"Your customer number (recommended)"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","description":"+90 5xx... or 05xx..."},"locale":{"enum":["tr","en","ar","ru","de"]}}},"org_unit":{"type":"string"},"person":{"type":"string"},"touchpoint":{"type":"string"},"transaction_ref":{"type":"string","maxLength":128},"context":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}}}},"Event":{"type":"object","required":["object","id","type","occurred_at","matched_triggers","scheduled","skipped","livemode","created_at"],"additionalProperties":false,"properties":{"object":{"const":"event"},"id":{"type":"string","pattern":"^evt_[0-9a-z]{26}$","examples":["evt_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"type":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"matched_triggers":{"type":"integer"},"scheduled":{"type":"array","items":{"type":"object","required":["trigger","survey","invitation","message","channel","send_at"],"properties":{"trigger":{"type":"string","pattern":"^trg_[0-9a-z]{26}$","examples":["trg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"survey":{"type":"string","pattern":"^srv_[0-9a-z]{26}$","examples":["srv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"invitation":{"type":"string","pattern":"^inv_[0-9a-z]{26}$","examples":["inv_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"message":{"type":"string","pattern":"^msg_[0-9a-z]{26}$","examples":["msg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"channel":{"enum":["email","sms"]},"send_at":{"type":"string","format":"date-time"}}}},"skipped":{"type":"array","items":{"type":"object","required":["trigger","reason","detail"],"properties":{"trigger":{"type":"string","pattern":"^trg_[0-9a-z]{26}$","examples":["trg_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"detail":{"type":"string"},"reason":{"type":"string","description":"survey_not_live, opted_out, frequency_trigger, frequency_global, no_recipient, privacy_notice_not_covering, unknown_context_field, validation_failed"}}}},"livemode":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"EventBatchResult":{"type":"object","required":["object","created","failed","results"],"properties":{"object":{"const":"batch_result"},"created":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["index","ok"],"properties":{"index":{"type":"integer"},"ok":{"type":"boolean"},"event":{"$ref":"#/components/schemas/Event"},"error":{"type":"object"}}}}}},"Contact":{"type":"object","required":["object","id","external_id","name","email","phone","locale","opted_out","created_at"],"additionalProperties":false,"properties":{"object":{"const":"contact"},"id":{"type":"string","pattern":"^con_[0-9a-z]{26}$","examples":["con_01k7x9q2m5c8v3n4b6z1t0r2w8"]},"external_id":{"type":["string","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"locale":{"type":["string","null"]},"opted_out":{"type":"boolean","description":"Does not want to receive survey messages"},"created_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"locale":{"enum":["tr","en","ar","ru","de"]},"opted_out":{"type":"boolean","description":"true: no survey messages are sent to this contact"}}},"ContactExport":{"type":"object","required":["object","contact","invitations","messages","responses","exported_at"],"properties":{"object":{"const":"contact_export"},"contact":{"$ref":"#/components/schemas/Contact"},"invitations":{"type":"array"},"messages":{"type":"array"},"responses":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string","format":"date-time"}}},"ContactErasure":{"type":"object","required":["object","erased","responses_anonymized"],"properties":{"object":{"const":"contact_erasure"},"erased":{"const":true},"responses_anonymized":{"type":"integer"}}},"SurveyList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Survey"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"InvitationList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"ResponseList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Response"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"OrgUnitList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgUnit"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"TouchpointList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Touchpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"WebhookEndpointList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"WebhookDeliveryList":{"type":"object","required":["object","data","has_more","next_cursor"],"additionalProperties":false,"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}}