Skip to content
Attune Docs

Identify participants with an external reference

By default, an Attune interview link asks each participant for an email address. With an external reference, you identify each participant yourself: you add an ID from your own system, such as a CRM contact ID, to the link, and Attune stores it with that participant’s response. Participants are never asked for an email address, and every response ties back to a record you already hold.

Section titled “Create a link that uses external references”

When you create a share link for a published interview, choose to identify participants by an external reference instead of by email. The choice is fixed for that link: an email link stays an email link, and a reference link stays a reference link.

If you create links through the Attune MCP server, call share_guide with participantIdentification set to external_ref.

Section titled “Add the reference to each participant’s link”

Take the link Attune gives you and add ?ref= followed by the participant’s ID:

<your Attune link>?ref=<participant ID>

For example, a participant with the ID c2f9b6e4-7d1a-4f0e-9a33-5b8e21d4c6a7 gets the link with ?ref=c2f9b6e4-7d1a-4f0e-9a33-5b8e21d4c6a7 on the end. Send every participant their own link, and never share one reference between two people: the second person to open it sees the interview as already completed.

A reference must follow these rules:

Rule Value
Length 1 to 128 characters
Allowed characters Letters A to Z and a to z, digits 0 to 9, dot (.), underscore (_), and hyphen (-)

A link with no reference, or with a reference that breaks these rules, does not start an interview.

Choose references that are random

Section titled “Choose references that are random”

Anyone who has your link and a reference can open the interview as that participant, and Attune does not check that a reference belongs to a particular person. So:

  • Use random, unguessable values. UUIDs, or other IDs of at least 16 random characters, work well. Never use sequential numbers such as 1001 and 1002, or anything else a person could guess by counting. A guesser could open other participants’ interviews or learn which of them have finished.
  • Never put personal data in a reference. Do not use an email address, a name, a phone number, or anything else that identifies a person on its own. References travel inside links, which end up in email threads and server logs, and Attune shows them next to each response.

What participants see

Section titled “What participants see”

Participants get the same interview as with any other link, including the consent step: a reference link never skips consent. Only the step that asks for an email address is skipped. Once the interview opens, Attune removes the reference from the browser’s address bar.

If a participant opens their link again after finishing, Attune shows that the interview is already completed and does not start another one. If they left before finishing, opening the link starts the interview again from the beginning.

Find the reference on responses

Section titled “Find the reference on responses”

Each response collected through a reference link shows its reference as External reference:

  • in the responses table;
  • on the participant card for the response;
  • in every CSV export: the consolidated export, the flat-file export, and the single-response export.

The cell is empty for responses collected through email links. The list_responses and get_response tools in the MCP server return the same value as externalRef.