Link Sharings API

It is generally the preferred method for transaction-based surveys. The system sending the request decides when to trigger the API to acquire the link. Once the API is triggered, the link is generated and provided. The ecosystem sending the request handles delivering survey link to the customer.

Before using the API, a link channel must be created within Pisano and a relevant flow must be assigned to it.

Endpoint Details

POST Method

https://<pisanoURL>/external/v1/link_sharings/<link_channel_id>/generate_link

Please contact Pisano support to learn your pisanoURL.

For on-premises customers, the pisanoURL information should be replaced by the system administrator, in the API configmap (ENV) within the api_host variable.

Parameters

Parameter	Value	Required
link_channel_id	Link channel ID (see the relevant section below)	Yes
customer	Customer specific fields. JSON Object	Yes (parameter itself is required but sub values array can be left empty altogether)
built_in_responses	Feedback-based data to be embedded in a survey URL. JSON Object	No
options	If you want to create a short link, you should select "true".	No

The "customer" fields are default and cannot be customized.

email: A customer E-Mail

phone_number: A customer phone number.

name: A customer name.

external_id: A customer number.

Pisano utilizes the below logic to create a unique entity within the software, called "Contact". Feedback left by the very same person can be collected under a unique contact.

find Customer by external_id
if not found continue

find Customer by email
if not found continue

find Customer by phone_number
if not found continue

if customer found
update customer
else
create new Customer

The data type of a "built_in_responses" value has to match the relevant schema's data type and code on Pisano. Please refer to the Customer Schema article to manage these details.

Headers (HTTP Header)

Header	Value
Content-Type	application/json
Authorization	API token

Example cURL Request

curl --location 'https://<pisanoURL>/external/v1/link_sharings/<link_channel_id>/generate_link' \
--header 'accept: application/json' \
--header 'authorization: <API token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customer": {
        "email": “<email_1>",
        "external_id": "<external_id1>"
    },
    "built_in_responses": {
        "Segment": "<Segment1>",
        "Location": "<Location1>",
        "TransactionDate": "<TransactionDate1>"
    },
    "options": {
        "shorten_url": true
    }
}'

For personalized links, a request should be made individually for each customer.

Throttle Limit: 20 requests in 8 seconds

In on-premise installations, email, SMS, push notification & link throttle limits can be increased or completely removed.

Throttle rules can be configured based on IP in on-premise installations.

Example Response

{
    "link": "https://pisanoURL/web_feedback?&responses=W10=&node_id=eea1caf7-eef7-40f9-a374-745bfd4250dc&ldi=391c7ed7-e255-4448-8acf-718d5fb09600&lci=c13d7898-1131-4119-aac4-2feefade59c2&creator_id=124017b4-95d0-4209-872c-533b3334ad95%22
}

{
    "link": "https://psn.vc/qtag1upm8"
}

Obtaining link_channel_id

Go to Channels > View my Link Channels and click "Edit".

link_channel_id is the last unique alphanumeric value in the URL on this screen.
For example:80e41df5-49fe-475c-986c-f003a59124af

Obtaining Token

For all API usages in Pisano, you must obtain a token..

API Response Codes

Response Status Code	Status	Status Code	Message
200	OK (Successful)
400	bad_request	13000	An error occured
401	unauthorized	13001	Wrong authentication token
404	NOT_FOUND	13002	Requested resource not found!
404	not_found	13003	Reset Token not found
404	not_found	13005	This node, nor any of their parent has any flow
403	forbidden	13007	It's not allowed to update Pisano node
400	bad_request	13008	Record could not be deleted
400	bad_request	13009	Updated question already has responses
404	not_found	13010	User not found
401	unauthorized	13011	User is inactive
409	conflict	13012	Password does not match the old password
403	forbidden	13013	Permission denied
400	bad_request	13014	Wrong activation code
400	bad_request	13015	Required field not present in params!
404	not_found	13016	Token not found
400	bad_request	13017	Duplicate value
404	not_found	13018	Response not found
404	not_found	13019	Activation token not found
400	bad_request	13020	You selected a reserved node type. Please choose another one.
400	bad_request	13024	Multiple responses given for a non-multiple choice question
400	bad_request	13026	Captcha is invalid
400	bad_request	13028	Invalid parameters
400	bad_request	13029	Invalid security hash
400	bad_request	13030	Invalid authentication token
400	bad_request	13031	Invalid proxy server parameters
409	conflict	13032	Wrong credentials
400	bad_request	13033	Invalid SDK credentials
400	bad_request	13034	Invalid Flow
404	not_found	13035	Node not found
403	forbidden	13036	Account locked
400	bad_request	13037	Malformatted CSV
400	bad_request	13038	Required customer identitiy keys not present in params!

Link Sharings API