Agenda kontakt

Contains the dealer's contacts of ads. A contact is a set of phones, e-mail and website that the dealer assigns to an ad and that is shown with the ad instead of the branch details. The address, the seller name (“Prodejce”) and the opening hours always remain those of the branch.

Phones as a whole: if the contact has at least one phone, only the contact's phones are shown with the ad (even a single one), otherwise all phones of the branch.
E-mail and website each separately: whatever the contact does not have filled in is taken from the branch.
The reply e-mail (emailOdpovedi) is not shown on the website. Enquiries from the form at the ad are sent to it; if it is not filled in, to the contact's e-mail, and only if the contact has no e-mail at all, to the branch e-mail.
An update of a contact takes effect immediately for all ads that use it.

Agenda features

Name	Options
Supported methods	`GET`, `PUT`/`POST`, `DELETE`
Support for detail levels	✔ The default is `summary` for the list and `full` for the contact detail
Support for filtering	✔
Support for full-text search	✘
Support for pagination	✔
Support for sorting	✔ The default sorting is by `id`
Support for external identifiers	✘ A contact is identified only by its ID
Support for `schemas`	https://api.tipmoto.com/schemas/kontakt-{export\|import}.{xsd\|rng}
Support for `?fail-on-warning`	✘ The agenda returns no warnings, invalid data are always an error
Support for dry-run	✔ For all writes including deletion
Returns `location`	✔ When a contact is created

Contact ID

The contact ID is unique across the whole system, not only within the dealer. A contact always belongs to one dealer, though, and cannot be read, changed or assigned to an ad through another dealer.
0 in an ad means the default contact of the branch (the ad shows the branch details). A contact with ID 0 does not exist in this agenda.
The number of a deleted contact is never reused.

Addresses and methods

Request	What it does
`GET /c/{dealer ID}/kontakt.{format}`	List of the dealer's contacts. The default detail level `summary` = `id` (with the `ref` attribute linking to the contact detail) and `nazev`; `detail=full` or `detail=custom:…` outputs further elements. Supports filtering, sorting and pagination. A dealer without contacts returns an empty list.
`GET /c/{dealer ID}/kontakt/{contact ID}.{format}`	Contact detail, default detail level `full`. Filtering, sorting and pagination parameters return the error `406` here.
`PUT`/`POST /c/{dealer ID}/kontakt.{format}`	Creates a contact (data without `id`). Returns `201 Created` and the `Location` header with the address of the new contact (can be switched off with the parameter `no-http-location`). With `id` in the data, it updates that contact.
`PUT`/`POST /c/{dealer ID}/kontakt/{contact ID}.{format}`	Updates the contact. A missing element remains unchanged, an empty element clears the value. If the ID in the address and in the data differ, returns `404`.
`DELETE /c/{dealer ID}/kontakt/{contact ID}.{format}?replace-with={ID}`	Deletes the contact. Ads that use the contact are switched to the contact `replace-with` – another contact of the same dealer, or `0` = default contact of the branch (the default if the parameter is missing). An `edit` change is recorded for every switched ad. The same is done by `PUT`/`POST` with the data `<kontakt action="delete" replace-with="{ID}"><id>{contact ID}</id></kontakt>`. An invalid `replace-with` (non-numeric, the ID of the contact being deleted, a contact the dealer does not have) returns `400` and nothing is deleted. The response contains `prepnutoInzeratu` = the number of switched ads.

With the parameter ?dry-run=true, all writes go through the full validation, but nothing is saved; for a deletion it returns prepnutoInzeratu = the number of ads that would be switched.

Agenda elements

Machine name	Name	Type	Information	rw	P	S	➀	➁
`id`	Contact ID	`integer`	Unique across the whole system. Leave empty when creating. In the list output it has the `ref` attribute linking to the contact detail.			✔	✔	✔
`nazev`	Name	`string 64`	Internal name of the contact for the selection in the ad in the administration; the customer does not see it. Must be unique within the dealer (regardless of upper and lower case).	✔	✔	✔		✔
`telefon1`, `telefon2`, `telefon3`	Phones	`string 16`	A phone must have at least 9 digits. When saved, the phones move up together with their notes (empty positions are skipped), so `telefon1` is always filled in if the contact has any phone.	✔		✔
`telefon1Text`, `telefon2Text`, `telefon3Text`	Notes to the phones	`string 16`	Note to the phone with the same number. A note without a phone is an error.	✔		✔
`email`	E-mail	`string 1024`	E-mail shown with the ad. Several addresses separated by commas, each must be valid; saved in lower case.	✔		✔
`emailOdpovedi`	Reply e-mail	`string 1024`	Not shown on the website; enquiries from the form at the ad are sent to it (order see the introduction). Several addresses separated by commas, each must be valid.	✔		✔
`url`	Website	`string 2048`	Several addresses separated by commas. An address must be `http://` or `https://`; without a scheme, `http://` is added.	✔		✔
`lastModified`	Last modified	`datetime`	Format `YYYY-MM-DD HH:MM:SS`, read only			✔

rw = writable
P = required element
S = the element can be used for filtering and sorting
➀ = included in detail level id
➁ = included in detail level summary

Validation

The name is required and unique within the dealer.
The contact must have at least one phone, e-mail or website; the reply e-mail alone is not enough (the customer does not see it).
When saved, the phones move up together with their notes.
E-mails (email and emailOdpovedi): every address must be valid.
Website: every address must be http:// or https://.
Invalid data return 400 with the list of errors in chyby and nothing is saved.

Contact of the ad

In the agendas moto, dily and prislusenstvi, the ad contains the element <kontakt id="N" ref="/c/{dealer ID}/kontakt/N.xml"/>. It is output only for dealers with at least one contact, then with every ad; id="0" (default contact of the branch) has no ref, and a contact the dealer no longer has (e.g. a deleted one) is output as 0. You assign a contact by writing <kontakt id="N"/> in the ad import; details are on the pages of these agendas.

The API does not provide the number of ads that use a contact.

Hooks and changes

The agenda kontakt can be tracked with hooks (hook) and in the agenda change: creating, updating and deleting a contact records the change add, edit or delete. An update of a contact is not recorded as a change of the ads; deleting a contact also records an edit change for every switched ad (agenda moto, dily, prislusenstvi).

Examples

GET /c/95/kontakt.xml (list, detail level summary; explanatory comments of the output omitted):

<tipmoto>
  <kontakt>
    <id ref="/c/95/kontakt/15.xml">15</id>
    <nazev>R&amp;D</nazev>
  </kontakt>
</tipmoto>

GET /c/95/kontakt.xml?detail=full:

<tipmoto>
  <kontakt>
    <id ref="/c/95/kontakt/15.xml">15</id>
    <nazev>R&amp;D</nazev>
    <telefon1>777 333 444</telefon1>
    <telefon1Text>dílna</telefon1Text>
    <telefon2/>
    <telefon2Text/>
    <telefon3/>
    <telefon3Text/>
    <email>info@firma.cz</email>
    <emailOdpovedi>dily@firma.cz</emailOdpovedi>
    <url>http://www.firma.cz/?a=1&amp;b=2</url>
    <lastModified>2026-10-03 10:00:00</lastModified>
  </kontakt>
</tipmoto>

GET /c/95/kontakt/15.json (contact detail; id has no ref here):

{"tipmoto":{"kontakt":{"id":"15","nazev":"R&D","telefon1":"777 333 444","telefon1Text":"dílna","telefon2":"","telefon2Text":"","telefon3":"","telefon3Text":"","email":"info@firma.cz","emailOdpovedi":"dily@firma.cz","url":"http:\/\/www.firma.cz\/?a=1&b=2","lastModified":"2026-10-03 10:00:00"}}}

Creating – PUT /c/95/kontakt.xml, response 201 Created with the Location header:

<tipmoto><kontakt><nazev>Servis</nazev><telefon1>777 111 222</telefon1></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id ref="/c/95/kontakt/99.xml">99</id>
  </result>
</tipmoto>

Updating – PUT /c/95/kontakt/15.xml changes only telefon2, the other elements remain:

<tipmoto><kontakt><telefon2>777 111 333</telefon2></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id ref="/c/95/kontakt/15.xml">15</id>
  </result>
</tipmoto>

Invalid data – response 400 (message in English):

<tipmoto>
  <success>false</success>
  <chyby>
    <chyba>Invalid e-mail 'o'neil@x.cz'.</chyba>
  </chyby>
  <result/>
</tipmoto>

Trial deletion – DELETE /c/95/kontakt/15.xml?replace-with=0&dry-run=true; nothing is deleted, prepnutoInzeratu is the number of ads that would be switched:

<tipmoto>
  <success>true</success>
  <dryRun>true</dryRun>
  <result>
    <id>15</id>
    <prepnutoInzeratu>9</prepnutoInzeratu>
  </result>
</tipmoto>

Deletion via PUT /c/95/kontakt.xml; the ads are switched to the default contact of the branch:

<tipmoto><kontakt action="delete" replace-with="0"><id>15</id></kontakt></tipmoto>

<tipmoto>
  <success>true</success>
  <result>
    <id>15</id>
    <prepnutoInzeratu>6</prepnutoInzeratu>
  </result>
</tipmoto>

Errors

HTTP code	When
`400`	invalid contact data (list of errors in `chyby`), a name the dealer already has, an invalid `replace-with`, an invalid value of the parameter `dry-run`; nothing is saved or deleted
`402`	the login has no read permission (for writes, write permission) for the dealer's agendas, or the dealer does not have exports/imports allowed
`404`	the contact does not exist or does not belong to the dealer; the ID in the address and in the data differ; a deletion without a contact ID
`405`	a method other than `GET`, `PUT`/`POST`, `DELETE`
`406`	invalid XML/JSON or the `kontakt` structure is missing; an invalid `filter` parameter or filtering with detail level `id`; filtering, sorting or pagination for the contact detail; an invalid `xpath`