Skip to main content

Survey Links

A survey link is a URL that directs customers to a survey form.

info

Common mediums for sharing survey links include:

  • QR Codes: Generate a QR code that links to the survey, allowing customers to scan it with their mobile devices.
  • Social Media: Post the link on platforms like Instagram, Facebook, or Twitter to reach a wider audience.
  • POS Integration: Some POS systems allow you to send Harlyy survey links directly to customers after a transaction.

You can also manually create survey links using either of the following formats:

https://survey.harlyy.com/<business_id>/<survey_id>
https://survey.harlyy.com/<business_id>/<survey_id>/<location_id>

Preview links can be created, which are useful for testing before sharing with customers:

https://survey.harlyy.com/<business_id>/<survey_id>/preview

Replace <business_id>, <survey_id>, and <location_id> with the appropriate IDs from your Harlyy account.

Harlyy links also support powerful query parameters which make it easier for partners to integrate with Harlyy surveys.

text parameter​

The text parameter allows you to pre-fill the text field in a contact-step in the survey. This can be helpful in many use cases, for example, many of our POS partners use this to inject and order number in order to track submissions back to the order.

https://survey.harlyy.com/<business_id>/<survey_id>?text=<text>
https://survey.harlyy.com/<business_id>/<survey_id>/<location_id>?text=<text>

location:metadata parameter​

The location:metadata parameter allows you to infer the location that a survey link is being used for, based on an internal identifier that you can pass in the URL. In order to use this, a business' locations must have a metadata field setup with a <key>.<value> pair that matches the value you pass in the URL.

https://survey.harlyy.com/<business_id>/<survey_id>?location:metadata=<key>.<value>
https://survey.harlyy.com/<business_id>/<survey_id>/<location_id>?location:metadata=<key>.<value> (will default to <location_id> if no location is found)

For example, if you have an internal identifier for a location called store_id with a value of 12345, you can pass this in the URL like so:

https://survey.harlyy.com/<business_id>/<survey_id>?location:metadata=store_id.12345

and setup each location's metadata in the Harlyy dashboard like this:

Location Metadata Example

location:labels parameter​

The location:labels parameter allows you to filter or infer the location based on one or more label IDs assigned to your locations in Harlyy. Pass a comma-separated list of label IDs:

https://survey.harlyy.com/<business_id>/<survey_id>?location:labels=<label_id1>,<label_id2>

You can find a label's ID from the Labels page — press the three dots next to a label and click Copy ID.

Locations are matched using AND logic — only locations that have all of the provided labels are considered.

The behavior depends on how many locations match:

MatchesBehavior
Exactly 1Location is silently auto-assigned; the customer never sees the location step.
2 or moreThe location step shows only the matching locations, without the city dropdown.
0Falls back to the standard city-based location selection flow.

For example, to surface only locations tagged with two specific labels:

https://survey.harlyy.com/<business_id>/<survey_id>?location:labels=lb_6627f1a2e4b0d3c1a2b3c4d5,lb_6627f1a2e4b0d3c1a2b3c4d6

customer parameter​

The customer parameter allows you to associate a customer with the survey submission. This is useful when you already know the customer's ID and want to attribute the submission to them.

https://survey.harlyy.com/<business_id>/<survey_id>?customer=<customer_id>
warning

Don't send customer when your order webhook already carries the customer's contact details. Harlyy creates a customer from those details and links it to the order, and that customer is the one attached to the submission. A customer value in the URL is ignored whenever the linked order resolves to a customer of its own. See Customer Attribution.

POS Integration Order ID parameters​

Harlyy supports POS integrations that can pass order IDs to surveys for tracking and attribution. The canonical format for POS order ID parameters is {integration}.{integration}OrderId, where {integration} is the POS provider name.

Using {integration}.{integration}OrderId requires the order webhook to be set up for the business, including for custom integrations. Without it there is no order to look the ID up against, so use the text parameter instead.

https://survey.harlyy.com/<business_id>/<survey_id>?<integration>.<integration>OrderId=<order_id>

Examples:

IntegrationParameter FormatExample
Blinkblink.blinkOrderIdhttps://survey.harlyy.com/<business_id>/<survey_id>?blink.blinkOrderId=427516
Customcustom.customOrderIdhttps://survey.harlyy.com/<business_id>/<survey_id>?custom.customOrderId=12345

You can combine this with other parameters to create comprehensive survey links:

https://survey.harlyy.com/<business_id>/<survey_id>?location:metadata=branchId.003&custom.customOrderId=ORDER-789

POS Integration Location ID parameters​

If your POS stores don't use unique order IDs at the brand level, but instead use unique order IDs at the location level, you must pass the location alongside the order ID using {integration}.{integration}LocationId.

https://survey.harlyy.com/<business_id>/<survey_id>?<integration>.<integration>OrderId=<order_id>&<integration>.<integration>LocationId=<location_id>

The value must be the same externalLocationId you sent on the order webhook, matched exactly. 007 and 7 are different locations as far as the lookup is concerned.

This parameter only scopes the order lookup. It does not resolve which Harlyy location the submission belongs to, which is what location:metadata does. The two are independent and can be sent together.

If you omit {integration}.{integration}LocationId, Harlyy falls back to the location:metadata value for the order lookup. So if your survey has a location step and you are already resolving the location that way, there is no need to send the location twice, provided your location metadata is identical to the externalLocationId you send on the webhook. Where it is not, or where you are not using location:metadata at all, send {integration}.{integration}LocationId explicitly.

Order Lookup and Expansion​

When you pass a POS order ID parameter, Harlyy automatically looks up the corresponding order using:

  • order.source — must match the POS integration name (e.g., "custom" for the custom integration)
  • order.orderDetails.externalOrderId — must match the order ID from the URL parameter
  • order.orderDetails.externalLocationId — must match the location ID, when one is resolved from the link

This means your external POS system must populate these fields when creating orders. For example, when creating an order with externalOrderId: "ORDER-789", the order's source field must be set to "custom".

If no location is resolved from the link and the order ID matches orders at more than one location, Harlyy cannot tell which order the customer is giving feedback on and links no order to the submission rather than guessing.

Once linked, the order is available on the submission and can be accessed via the ?expand=order query parameter on the submission GET endpoint.

Customer Attribution​

If the order webhook included the customer's email or phone number, Harlyy creates or matches a customer from it and links that customer to the order. When a survey link resolves to such an order, that customer is attached to the submission automatically. You do not need to look the customer up or pass one yourself.

Where a link carries both a POS order ID and a customer parameter, and the two name different customers, the order's customer wins. It is derived from the details your POS sent with the order, and the submission is already tied to that order, so taking the URL's value instead would leave the submission attributed to one customer while its order points at another. For that reason we don't recommend sending customer at all when the order carries the customer's details, and a disagreement between the two is logged as a likely stale or mis-templated link.

Attributing the customer this way also feeds the rest of the platform: rewards are issued against a customer with an email address, incidents reference the customer, and a survey's contact step can be set to skip itself when the customer is already known, so the customer isn't asked for details you already have.