Contacts

Contacts of the company: profile fields, consent state, suppressions, custom fields, purposes of processing (consents), activities and GDPR export and erasure.

Technická referencia je v angličtine (rovnako ako strojovo čitateľný dokument OpenAPI). Celú skupinu pre AI agenta načítate z /api/openapi.json?tag=Contacts.

Prihlásenie: Authorization: Bearer pst_... alebo HTTP Basic (e-mail člena firmy a API kľúč).

Operácie#

List contacts (search, filters, paging)#

GET /api/v1/tenants/{tenant}/contacts

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: search_contacts

Searches contacts. Filters: q (e-mail, name or #id), tab (all, bounced, no_list, blacklisted, complained), status (pending, subscribed, unsubscribed, bounced, complained), engagement (A to E, N), shop. Paged, newest first.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Create a contact#

POST /api/v1/tenants/{tenant}/contacts

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: create_contact (cez MCP len s náhľadom a potvrdením)

Creates a contact by hand (like one import row). Needs a purpose of processing and consentConfirmed true (the user confirms a documented consent). Other profile fields by their API names: titleBefore, titleAfter, mobile, companyId, street, postalCode, country, nameDay, note, salutation, salutationFormal, vocativeFirstName, vocativeLastName, affiliateId.

Parametre

Telo požiadavky (application/json): Required by the server: email, shopId.

Odpovede

• 201 Created: application/json ContactDetail

Chyby

Start a bulk action over contacts in the background#

POST /api/v1/tenants/{tenant}/contacts/bulk

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

SE's bulk actions of the contacts grid as a background job (core/contacts_bulk.py, KG-08): body {action: add_to_list | blacklist | delete, contactIds: [ids] (the ticked rows) or all: true (every contact matching the grid filters given as the query string of GET /contacts), listIds for add_to_list}. Contacts on the blacklist are left out. 202 {jobId, count}; the end comes as the notification contacts_bulk_done.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json ContactsBulkStarted

Chyby

Find possible duplicate contacts#

GET /api/v1/tenants/{tenant}/contacts/duplicates

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Possible duplicates (core/contacts.possible_duplicates): groups of contacts with the same phone or the same name and company. A report only, nothing is merged.

Parametre

Odpovede

• 200 OK: application/json DuplicateReport

Chyby

Count contacts by status#

GET /api/v1/tenants/{tenant}/contacts/summary

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Odpovede

• 200 OK: application/json ContactSummary

Chyby

Get a contact#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: get_contact

Contact card: profile fields, status and consent, lists, last 90 days of e-mail activity, recent activities and orders (totals per currency).

Parametre

Odpovede

• 200 OK: application/json ContactDetail

Chyby

Update a contact#

PATCH /api/v1/tenants/{tenant}/contacts/{contact_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: update_contact (cez MCP len s náhľadom a potvrdením)

Changes profile fields and custom fields of a contact (never its e-mail, status or consent). Other profile fields by their API names: titleBefore, titleAfter, mobile, companyId, street, postalCode, country, nameDay, note, salutation, salutationFormal, vocativeFirstName, vocativeLastName, affiliateId.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json ContactDetail

Chyby

Delete a contact#

DELETE /api/v1/tenants/{tenant}/contacts/{contact_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: delete_contact (cez MCP len s náhľadom a potvrdením)

Deletes a contact (its suppression stays, so it is never mailed again by mistake). For a data erasure request use erase_contact.

204, 404, or 423 recently_sent: a campaign e-mail to the contact is queued or went out within 24 hours (SE's HTTP 423, core/contact_data.py RECENT_SEND).

Parametre

Odpovede

• 204 No content

Chyby

List activities of a contact#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/activities

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Add a manual activity (note) to a contact#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/activities

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: add_contact_activity

Adds a note, call, deal or other activity to a contact.

Parametre

Telo požiadavky (application/json): Required by the server: kind, title.

Odpovede

• 201 Created: application/json ContactActivity

Chyby

The real journey of a contact through the automations (runs and steps)#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/automation-runs

Oprávnenie: modul campaigns, úroveň read; kľúč s prístupom read alebo full

The real journey of one contact through the automations (contact card, tab Automatizace): its runs, newest first, each with {automation: {id, name, status}, nodes: {key: {type, name}}} and its real steps (outcome, branch, next node, reason). Paged. 404 for a contact of another tenant.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Blacklist a contact#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: blacklist_contact

Puts the contact on the blacklist (manual suppression: never mailed).

Card menu "Přidat na blacklist" (KK-02): 201 newly added, 200 already there (the note stays); 409 suppression_locked with params.reason when the address is suppressed for another reason.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: it already existed or nothing changed: application/json BlacklistResult
• 201 Created (200 when it already existed or nothing changed): application/json BlacklistResult

Chyby

Remove a contact from the blacklist#

DELETE /api/v1/tenants/{tenant}/contacts/{contact_id}/blacklist

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: unblacklist_contact (cez MCP len s náhľadom a potvrdením)

Takes the contact off the blacklist (it stays unsubscribed until it subscribes again).

Card menu "Odebrat z blacklistu": 204; 404 when the contact is not on the blacklist; 409 suppression_locked when its suppression has another reason (only a confirmed double opt-in lifts those).

Parametre

Odpovede

• 204 No content

Chyby

List coupons given to a contact#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/coupons

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

The codes of one contact (tab Slevové kupóny): code, stack, status, assigned and used.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Erase a contact (GDPR, irreversible)#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/erase

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: erase_contact (cez MCP len s náhľadom a potvrdením)

Erasure on request (GDPR): erases the person and their data, keeps only a keyed hash that blocks a new import.

Erasure on request: the tenant's data in the request's transaction, then the consent log as the platform role (only after the tenant transaction committed). When that second step fails, the same request again finishes it (review of batch 4): the contact is gone, but its consent log rows still name the address (cd.erasure_state); a contact that was never erased here stays 404.

Parametre

Telo požiadavky (application/json): Required by the server: confirm.

Odpovede

• 200 OK: application/json EraseResult

Chyby

Export all data of a contact (GDPR access)#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/export

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: export_contact_data

Everything stored about one contact (data access request), as JSON.

Parametre

Odpovede

• 200 OK: application/json map of any

Chyby

Previous and next contact of a filtered list#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/neighbors

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Odpovede

• 200 OK: application/json ContactNeighbors

Chyby

List consents (purposes) of a contact#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/purposes

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: get_contact_consents

Consents (purposes of processing) of a contact.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Record a consent (purpose) of a contact#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/purposes

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

Telo požiadavky (application/json): Required by the server: purposeId.

Odpovede

• 201 Created: application/json object

Chyby

Withdraw a consent of a contact#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/purposes/{consent_id}/withdraw

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

Parametre

Odpovede

• 200 OK: application/json object

Chyby

List segments a contact belongs to#

GET /api/v1/tenants/{tenant}/contacts/{contact_id}/segments

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Unsubscribe a contact from everything#

POST /api/v1/tenants/{tenant}/contacts/{contact_id}/unsubscribe

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: unsubscribe_contact (cez MCP len s náhľadom a potvrdením)

Unsubscribes a contact from all e-mails, as its own unsubscribe link would (only a new double opt-in subscribes it again).

Unsubscribes the contact from everything, as its own unsubscribe link would (store.unsubscribe: status unsubscribed, the address suppressed, queued e-mails skipped, the consent log). Only a new double opt-in subscribes it again. Body optional {note}: up to 500 characters for the consent log. Answers the contact detail.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json ContactDetail

Chyby

List custom fields#

GET /api/v1/tenants/{tenant}/custom-fields

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_custom_fields

Custom contact fields (id, name, type, options).

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Create a custom field#

POST /api/v1/tenants/{tenant}/custom-fields

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: create_custom_field

Creates a custom contact field.

Parametre

Telo požiadavky (application/json)

Odpovede

• 201 Created: application/json CustomField

Chyby

Update a custom field#

PATCH /api/v1/tenants/{tenant}/custom-fields/{field_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: update_custom_field

Renames a custom field or changes its options.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json CustomField

Chyby

Delete a custom field#

DELETE /api/v1/tenants/{tenant}/custom-fields/{field_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: delete_custom_field (cez MCP len s náhľadom a potvrdením)

Deletes a custom field and its values.

Parametre

Odpovede

• 204 No content

Chyby

List purposes of processing (consent types)#

GET /api/v1/tenants/{tenant}/purposes

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_purposes

Purposes of processing (consents) with legal basis and validity.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Create a purpose of processing#

POST /api/v1/tenants/{tenant}/purposes

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: create_purpose

Creates a purpose of processing.

Parametre

Telo požiadavky (application/json)

Odpovede

• 201 Created: application/json Purpose

Chyby

Update a purpose of processing#

PATCH /api/v1/tenants/{tenant}/purposes/{purpose_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: update_purpose

Changes a purpose of processing.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json Purpose

Chyby

Delete a purpose of processing#

DELETE /api/v1/tenants/{tenant}/purposes/{purpose_id}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: delete_purpose (cez MCP len s náhľadom a potvrdením)

Deletes an unused purpose of processing.

Parametre

Odpovede

• 204 No content

Chyby

Create a list of the contacts with a purpose#

POST /api/v1/tenants/{tenant}/purposes/{purpose_id}/to-contact-list

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

SE "Přidat ke kontaktům v seznamu": body {listId}; answers {count} of the consents added.

Parametre

Telo požiadavky (application/json): Required by the server: listId.

Odpovede

• 200 OK: application/json object

Chyby

Search contacts, campaigns, templates and more#

GET /api/v1/tenants/{tenant}/search

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: search

Quick search over contacts and lists (at least 2 characters).

Parametre

Odpovede

• 200 OK: application/json SearchResults

Chyby

List suppressed addresses#

GET /api/v1/tenants/{tenant}/suppressions

Oprávnenie: modul contacts, úroveň read; kľúč s prístupom read alebo full · Nástroj MCP: list_suppressions

Suppression list (addresses never mailed) with reason.

Parametre

Odpovede

• 200 OK: application/json object

Chyby

Suppress an address#

POST /api/v1/tenants/{tenant}/suppressions

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: add_suppression

Adds an address to the suppression list (manual blacklist), also when it is not a contact.

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: it already existed or nothing changed: application/json object
• 201 Created (200 when it already existed or nothing changed): application/json object

Chyby

Import addresses to the blacklist#

POST /api/v1/tenants/{tenant}/suppressions/blacklist-import

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full

SmartEmailing's blacklist on the tenant's blacklist (core/blacklist.py, migration 0180): body {contacts: the SmartEmailing backup list (blacklisted.json) or {emails: [addresses]}, apply: true to write (default: a dry run that writes nothing)}. Idempotent; nothing is sent, no automation starts, no other suppression or contact changes. 200 with the counts (never an address).

Parametre

Telo požiadavky (application/json)

Odpovede

• 200 OK: application/json object

Chyby

Remove one suppression#

DELETE /api/v1/tenants/{tenant}/suppressions/{email}

Oprávnenie: modul contacts, úroveň full; kľúč s prístupom full · Nástroj MCP: remove_suppression (cez MCP len s náhľadom a potvrdením)

Removes a manual suppression of an address (other reasons are locked).

Parametre

Odpovede

• 204 No content

Chyby

Schémy#

Activity#

ActivityDetail#

What the expanded activity card shows (SE: E-mail, Newsletter or Automatizace, Šablona, Zdroj); null = none.

ActivityType#

one of: other, unsubscribed, bounced, form, sent, opened, clicked, doi, order, status_change, web_tracking, note, call, deal

AutomationRunStatus#

one of: active, completed, exited

AutomationStatus#

one of: active, draft, paused

AutomationStepOutcome#

one of: expired, queued, failed, skipped, goal, reset, end, yes, no, entered, passed, variant, released, jumped

BlacklistResult#

A blacklist entry made from the contact card (POST /contacts/{id}/blacklist).

ConsentBasis#

one of: none, soft_opt_in_customer, double_opt_in, imported

ContactActivity#

ContactAutomationRun#

A run of one contact with its automation (contact card, tab Automatizace).

ContactConsent#

ContactCoupon#

ContactCreateInput#

A contact added by hand: like a one-row import (purpose and confirmation required).

ContactDetail#

ContactListItem#

ContactListMembership#

ContactNeighbors#

ContactOrder#

ContactPatch#

Profile changes; the address, state and consent never change here. A null custom field value removes it.

ContactSegment#

ContactSource#

one of: manual, shoptet, smartemailing, api, erp_order, signup_form, import

ContactSourceRecord#

One source record of a contact (provenance): what that source says about consent.

ContactStats#

ContactSummary#

ContactsBulkRequest#

ContactsBulkStarted#

CouponStatus#

one of: free, assigned, used

Currency#

one of: CZK, EUR

CustomActivityInput#

CustomField#

CustomFieldInput#

CustomFieldValue#

boolean or string or number or array of string

DuplicateGroup#

Possible duplicates: contacts with the same phone or the same name and company (a report, nothing is merged).

DuplicateReport#

EraseResult#

Error#

{
  "error": {
    "code": "validation",
    "message": "email"
  }
}

ListMembershipState#

one of: unsubscribed, confirmed, unconfirmed, removed

OrderItemPreview#

OrderStatus#

one of: cancelled, other, pending, completed

OrderTotal#

One row per currency. CZK and EUR are never added together or converted.

Purpose#

PurposeInput#

SearchResults#

ValidityLength#

Length of a purpose's validity as entered (months count 30 days and years 365 for the consent ends).