Pro přístup k API potřebujete chráněný klíč Vašeho Clipsan účtu.
Naleznete jej na stránce https://clipsan.com/cs/clipsan/securekey.
Výpis seznamu kontaktů
Base URL:
https://clipsan.com/api/lead/list/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
Volitelné parametry
- list – Hash ID skupiny, kterou exportujeme (k nalezení v Přehledu skupin).
- tag – Štítek, který exportujeme
- user – ID uživatele, jehož kontakty exportujeme
Příklad volání
https://clipsan.com/api/lead/list/key/VASKLIC/list/KODSKUPINY/tag/clipsan
https://clipsan.com/api/lead/list/?key=VASKLIC&list=KODSKUPINY&tag=clipsan
Příklad odpovědi
{"result":"ok","data":{"455554":{"id":455554,"pin":null,"email":"radekxxx@gmail.com","firstname":"Radek","surname":"Unic","gender":"unknown","state":"active","lifecycle":"subscriber","added":1417432404},"105019":{"id":105019,"pin":"521223115","email":null,"firstname":"Petra","surname":"Krásná","gender":"female","state":"active","lifecycle":"customer","added":1417430340}}}
Příklad volání (Neplatný seznam)
https://clipsan.com/api/lead/list/key/VASKLIC/list/aaa
https://clipsan.com/api/lead/list/?key=VASKLIC&list=aaa
Příklad odpovědi
{"result":"error","error":"invalid list"}
Vyhledávání kontaktů
Base URL:
https://clipsan.com/api/lead/search/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
- query – Vyhledávaná fráze – vyhledáváme ve jménu, příjmení
Příklad volání
https://clipsan.com/api/lead/search/key/VASKLIC/query/martin
https://clipsan.com/api/lead/search/?key=VASKLIC&query=martin
Příklad odpovědi
{"result":"ok","data":{"455554":{"id":455554,"pin":null,"email":"radekxxx@gmail.com","firstname":"Martin","surname":"Unic","gender":"unknown","state":"active","lifecycle":"subscriber","added":1417432404},"105019":{"id":105019,"pin":"521223115","email":null,"firstname":"Petra","surname":"Krásná","gender":"female","state":"active","lifecycle":"customer","added":1417430340}}}
Příklad volání (Neplatný dotaz)
https://clipsan.com/api/lead/list/key/VASKLIC/query/
https://clipsan.com/api/lead/list/?key=VASKLIC&query=
Příklad odpovědi
{"result":"error","error":"invalid query"}
Přidat nový kontakt / upravit stávající kontakt
Přidání nového kontaktu do databáze kontaktů. Při existenci kontaktu jsou jeho data aktualizována. Slouží i k přidání stávajícího kontaktu do nové skupiny nebo přidání štítku ke kontaktu.
Base URL:
https://clipsan.com/api/lead/add/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
- email – Email kontaktu
- pin – Rodné číslo (Buď email nebo rodné číslo)
Volitelné parametry
- user – ID uživatele, který má ke kontaktu získat přístup
- list – Hash ID skupiny, do které kontakt vkládáme (k nalezení v Přehledu skupin). Parametr může být i pole např. list[]=12345&list[]=67890
- tag – Štítek, kterým bude kontakt oštítkován
- firstname – Jméno kontaktu
- surname – Příjmení kontaktu
- phone – Telefonní číslo kontaktu
- ip – IP adresa kontaktu
- gender – Pohlaví kontaktu – akceptované hodnoty (m – muž, f – žena)
- notformal – Zapnout tykání
- referer – Referer adresa kontaktu (např. stránka, na které se registruje)
- state – stav odběru novinek (active, inactive, temp)
- lifecycle – stav kontaktu v marketingovém cyklu (subscriber, lead, qualified, saleslead, opportunity, customer, ambassador, other)
- funnel – ID automatu, který se má spustit (POZOR: Spouští se pouze pro nové kontakty, pro vynucení použijte parametr unique=1.)
- unique – (Hodnota 0/1 – Výchozí 0) Ber každé volání jako unikátní a odstartuj automat vždy
- mute – (Hodnota 0/1 – Výchozí 1) Neposílat informační email o novém kontaktu
Vlastní parametry
Ke kontaktům můžete přidávat další parametry z přednastavených nebo začít používat vlastní. Jejich nastavení a úpravu provádíte přímo v nastavení Clipsanu. Kódy přednastavených parametrů jsou tyto: lastcontact, email2, photo, url, countryId, social_gplus, social_linkedin, social_twitter, social_facebook, utm_source, utm_medium, utm_campaign, facebook, question, land, position, country, salute, contactphone, contactemail, contactname, vatid, companyid, city, zip, street, company. Při použití parametru je nutné přidat před jeho název předložku „data_“. Výsledný parametr pro poslední kontakt je tedy data_lastcontact, parametr pro zemi data_land apod.
Odpověď
{"result":"ok","action":"add|update","id":"ID nového kontaktu"}
Příklad volání (základní přidání kontaktu s emailovou adresou)
https://clipsan.com/api/lead/add/key/VASKLIC/email/vaclav.krajnak%40ciwire.biz
https://clipsan.com/api/lead/add/?key=VASKLIC&email=vaclav.krajnak%40ciwire.biz
Příklad odpovědi
{"result":"ok","action":"add","id":"1002"}
Příklad volání (základní přidání kontaktu s rodným číslem)
https://clipsan.com/api/lead/add/key/VASKLIC/pin/665317107
https://clipsan.com/api/lead/add/?key=VASKLIC&pin=665317107
Příklad odpovědi
{"result":"ok","action":"add","id":"1002"}
Příklad volání (Úprava kontaktu – přidání do skupiny a spuštění automatu)
https://clipsan.com/api/lead/add/key/VASKLIC/list/KODSKUPINY/email/vaclav%40clipsan.com/firstname/Vaclav/lastname/Gregor/gender/m/phone/123456789/ip/::1/funnel/IDAUTOMATU
https://clipsan.com/api/lead/add/?key=VASKLIC&list=KODSKUPINY&email=vaclav%40clipsan.com&firstname=Vaclav&lastname=Gregor&gender=m&phone=123456789&ip=::1&funnel=IDAUTOMATU
Příklad odpovědi
{"result":"ok","action":"update","id":"1002"}
Příklad volání (neexistující UŽIVATEL)
https://clipsan.com/api/lead/add/key/VASKLIC/email/vaclav%40clipsana.com/user/123
https://clipsan.com/api/lead/add/?key=VASKLIC&email=vaclav%40clipsana.com&user=123
Příklad odpovědi
{"result":"error","error":"user not found"}
Detail kontaktu
Base URL:
https://clipsan.com/api/lead/view/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
- id – ID kontaktu
- email – Email kontaktu
- pin – Rodné číslo (Buď ID nebo email nebo rodné číslo)
Odpověď
{"result":"ok","lead":{"id":12456,"pin":null,"email":"vaclav@clipsan.com","firstname":"krestni","surname":"prijmeni","gender":"male","state":"active","lifecycle":"subscriber","added":1368089154,"lists":[pole_skupin],"tags":[pole_stitku]}}
Příklad volání (data kontaktu s emailovou adresou)
https://clipsan.com/api/lead/view/key/VASKLIC/email/vaclav%40clipsan.com
https://clipsan.com/api/lead/view/?key=VASKLIC&email=vaclav%40clipsan.com
Příklad odpovědi
{"result":"ok","lead":{"id":12456,"pin":null,"email":"vaclav@clipsan.com","firstname":null,"surname":null,"gender":"male","state":"active","lifecycle":"subscriber","added":1368089154,"data_phone":"777123456","data_contactname":"Vaclav","data_salute":"V\u00e1clave","data_ip":"12.13.14.15","lists":["12345","56789"],"tags":["12345"]}}
Příklad volání (data kontaktu s rodným číslem)
https://clipsan.com/api/lead/view/key/VASKLIC/pin/665317107
https://clipsan.com/api/lead/view/?key=VASKLIC&pin=665317107
Příklad odpovědi
{"result":"ok","lead":{"id":12456,"pin":null,"email":"vaclav@clipsan.com","firstname":null,"surname":null,"gender":"male","state":"active","lifecycle":"subscriber","added":1368089154,"phone":"777123456","contactname":"Vaclav","salute":"V\u00e1clave","ip":"12.13.14.15"}}
Příklad volání (neexistující kontakt)
https://clipsan.com/api/lead/view/key/VASKLIC/email/vaclav%40clipsana.com
https://clipsan.com/api/lead/view/?key=VASKLIC&email=vaclav%40clipsana.com
Příklad odpovědi
{"result":"error","error":"lead not found"}
Odebrat kontakt ze skupiny, odebrat štítek
Slouží k odebrání vlastnosti stávajícího kontaktu např. odebrání ze stávající skupiny nebo odebrání štítku.
Base URL:
https://clipsan.com/api/lead/modify/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
- id – ID kontaktu
- email – Email kontaktu
- pin – Rodné číslo (Buď ID nebo email nebo rodné číslo)
Volitelné parametry
- list – Hash ID skupiny, ze které kontakt odebíráme (k nalezení v přehledu skupin https://clipsan.com/cs/marketing/list)
- tag – Štítek, který bude kontaktu odebrán
Odpověď
{"result":"ok","lead":{"id":12456,"pin":null,"email":"vaclav@clipsan.com","firstname":"krestni","surname":"prijmeni","gender":"male","state":"active","lifecycle":"subscriber","added":1368089154,"lists":["12345","56789"],"tags":["12345"]}}
Příklad volání (data kontaktu s emailovou adresou)
https://clipsan.com/api/lead/modify/key/VASKLIC/email/vaclav%40clipsan.com/list/12345
https://clipsan.com/api/lead/modify/?key=VASKLIC&email=vaclav%40clipsan.com&list=12345
Příklad odpovědi
{"result":"ok","lead":{"id":12456,"pin":null,"email":"vaclav@clipsan.com","firstname":null,"surname":null,"gender":"male","state":"active","lifecycle":"subscriber","added":1368089154,"data_phone":"777123456","data_contactname":"Vaclav","data_salute":"V\u00e1clave","data_ip":"12.13.14.15","lists["56789"],"tags":["12345"]}}
Příklad volání (neexistující kontakt)
https://clipsan.com/api/lead/modify/key/VASKLIC/email/vaclav%40clipsana.com/list/12345/
https://clipsan.com/api/lead/modify/?key=VASKLIC&email=vaclav%40clipsana.com&list=12345
Příklad odpovědi
{"result":"error","error":"lead not found"}
Příklad volání (neexistující SKUPINA)
https://clipsan.com/api/lead/modify/key/VASKLIC/email/vaclav%40clipsan.com/list/12345a/
https://clipsan.com/api/lead/modify/?key=VASKLIC&email=vaclav%40clipsan.com&list=12345a
Příklad odpovědi
{"result":"error","error":"list not found"}
Smazat kontakt
Base URL:
https://clipsan.com/api/lead/delete/
Vyžadované parametry
- key – Chráněný klíč Clipsan účtu
- id – ID kontaktu
- email – Email kontaktu
- pin – Rodné číslo (Buď ID nebo email nebo rodné číslo)
Odpověď
{"result":"ok"}
Příklad volání (smazání kontaktu s emailovou adresou)
https://clipsan.com/api/lead/delete/key/VASKLIC/email/vaclav%40clipsan.com
Příklad odpovědi
{"result":"ok"}
Příklad volání (smazání kontaktu s rodným číslem)
https://clipsan.com/api/lead/delete/key/VASKLIC/pin/665317107
Příklad odpovědi
{"result":"ok"}
Příklad volání (neexistující kontakt)
https://clipsan.com/api/lead/delete/key/VASKLIC/email/vaclav%40clipsana.com
Příklad odpovědi
{"result":"error","error":"lead not found"}
Upozornění při změně kontaktu
Adresu pro upozornění zaneste do údajů svého účtu v Clipsanu. Můžete použít následující speciální kódy pro generování odkazu. Kódy jsou automaticky přepsány do hodnot aktuálního kontaktu.
Upozornění je voláno nejdéle minutu po vytvoření či úpravě kontaktu uživatelem. Na úpravy přes API není upozorňováno.
Při změně emailové adresy nebo rodného čísla kontaktu jsou vyslána dvě upozornění. Jedno na starou hodnotu a jedno na novou hodnotu.
Doporučujeme chránit volání Vaší adresy pomocí ověření IP adresy volajícího. Server Clipsan má adresu 109.123.222.193.
Speciální kódy
- {id} – ID kontaktu
- {pin} – Rodné číslo kontaktu
- {email} – Emailová adresa kontaktu
- {time} – Časová značka
Příklad zadané adresy (pro synchronizaci pomocí rodného čísla)
http://www.mojeplatforma.cz/uprava-kontaktu?rodnecislo={pin}
Příklad reálné adresy
http://www.mojeplatforma.cz/uprava-kontaktu?rodnecislo=665317107
Příklad zadané adresy (pro synchronizaci pomocí emailu)
http://www.mojeplatforma.cz/uprava-kontaktu?email={email}&znacka={time}
Příklad reálné adresy
http://www.mojeplatforma.cz/uprava-kontaktu?email=vaclav%40clipsana.com&znacka=1417220223