Contacts

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

Technická reference je anglicky (stejně jako strojově čitelný dokument OpenAPI). Celou skupinu pro AI agenta načtete z /api/openapi.json?tag=Contacts.

Přihlášení: Authorization: Bearer pst_... nebo HTTP Basic (e-mail člena firmy a API klíč).

Operace#

List contacts (search, filters, paging)#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo 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.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Create a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: create_contact (přes MCP jen s náhledem a potvrzení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.

Parametry

Tělo požadavku (application/json): Required by the server: email, shopId.

Odpovědi

• 201 Created: application/json ContactDetail

Chyby

Start a bulk action over contacts in the background#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem 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.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json ContactsBulkStarted

Chyby

Find possible duplicate contacts#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo 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.

Parametry

Odpovědi

• 200 OK: application/json DuplicateReport

Chyby

Count contacts by status#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Odpovědi

• 200 OK: application/json ContactSummary

Chyby

Get a contact#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo 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).

Parametry

Odpovědi

• 200 OK: application/json ContactDetail

Chyby

Update a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: update_contact (přes MCP jen s náhledem a potvrzení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.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json ContactDetail

Chyby

Delete a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: delete_contact (přes MCP jen s náhledem a potvrzení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).

Parametry

Odpovědi

• 204 No content

Chyby

List activities of a contact#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Add a manual activity (note) to a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: add_contact_activity

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

Parametry

Tělo požadavku (application/json): Required by the server: kind, title.

Odpovědi

• 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ávnění: modul campaigns, úroveň read; klíč s přístupem read nebo 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.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Blacklist a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem 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.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 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ávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: unblacklist_contact (přes MCP jen s náhledem a potvrzení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).

Parametry

Odpovědi

• 204 No content

Chyby

List coupons given to a contact#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

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

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Erase a contact (GDPR, irreversible)#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: erase_contact (přes MCP jen s náhledem a potvrzení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.

Parametry

Tělo požadavku (application/json): Required by the server: confirm.

Odpovědi

• 200 OK: application/json EraseResult

Chyby

Export all data of a contact (GDPR access)#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: export_contact_data

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

Parametry

Odpovědi

• 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ávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Odpovědi

• 200 OK: application/json ContactNeighbors

Chyby

List consents (purposes) of a contact#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: get_contact_consents

Consents (purposes of processing) of a contact.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Record a consent (purpose) of a contact#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Tělo požadavku (application/json): Required by the server: purposeId.

Odpovědi

• 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ávnění: modul contacts, úroveň full; klíč s přístupem full

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

List segments a contact belongs to#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Unsubscribe a contact from everything#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: unsubscribe_contact (přes MCP jen s náhledem a potvrzení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.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json ContactDetail

Chyby

List custom fields#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_custom_fields

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

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Create a custom field#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: create_custom_field

Creates a custom contact field.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 201 Created: application/json CustomField

Chyby

Update a custom field#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: update_custom_field

Renames a custom field or changes its options.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json CustomField

Chyby

Delete a custom field#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: delete_custom_field (přes MCP jen s náhledem a potvrzením)

Deletes a custom field and its values.

Parametry

Odpovědi

• 204 No content

Chyby

List purposes of processing (consent types)#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_purposes

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

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Create a purpose of processing#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: create_purpose

Creates a purpose of processing.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 201 Created: application/json Purpose

Chyby

Update a purpose of processing#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: update_purpose

Changes a purpose of processing.

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json Purpose

Chyby

Delete a purpose of processing#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: delete_purpose (přes MCP jen s náhledem a potvrzením)

Deletes an unused purpose of processing.

Parametry

Odpovědi

• 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ávnění: modul contacts, úroveň full; klíč s přístupem full

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

Parametry

Tělo požadavku (application/json): Required by the server: listId.

Odpovědi

• 200 OK: application/json object

Chyby

Search contacts, campaigns, templates and more#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: search

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

Parametry

Odpovědi

• 200 OK: application/json SearchResults

Chyby

List suppressed addresses#

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

Oprávnění: modul contacts, úroveň read; klíč s přístupem read nebo full · Nástroj MCP: list_suppressions

Suppression list (addresses never mailed) with reason.

Parametry

Odpovědi

• 200 OK: application/json object

Chyby

Suppress an address#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: add_suppression

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

Parametry

Tělo požadavku (application/json)

Odpovědi

• 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ávnění: modul contacts, úroveň full; klíč s přístupem 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).

Parametry

Tělo požadavku (application/json)

Odpovědi

• 200 OK: application/json object

Chyby

Remove one suppression#

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

Oprávnění: modul contacts, úroveň full; klíč s přístupem full · Nástroj MCP: remove_suppression (přes MCP jen s náhledem a potvrzením)

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

Parametry

Odpovědi

• 204 No content

Chyby

Schémata#

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).