Theme
How survey links behave
Worth knowing before you send one, because most of this cannot be undone.
A link is single-use
A link is reusable until someone submits an answer. On submit it is destroyed: the link stops working and the response is recorded.
Reopening a consumed link shows the same neutral "not available" page as an expired one. A respondent cannot tell the two apart, and neither can you from the outside — retrieve the link instead, which returns 404 once it is gone.
If you need to know whether a link was opened, read viewed before it is consumed. Afterwards there is nothing left to read.
Expiry
expires_at is optional and defaults to 30 days. It must be at least 60 seconds in the future and at most two years out, and it is RFC 3339 in UTC:
json
{ "expires_at": "2026-09-30T12:00:00.000Z" }Expired links render the same unavailable page. There is no grace period, and expiry cannot be extended — mint a new link.
Identity is set by the sender, not the recipient
author_name, author_email and author_url describe the person you sent the link to. They can only be set when the link is minted — never from the URL.
That distinction is deliberate. A query string is editable by whoever holds the link, so accepting identity from it would let a recipient attribute their answer to a colleague, and would leak the original recipient's address through a forwarded URL.
The account fields — customer_name, customer_id, customer_url — behave the same way: what you set when minting is what reaches Zefi.
Language
language sets the locale the survey renders in, as an ISO code:
json
{ "language": "it" }Both it and pt-BR are accepted. Anything that is not an ISO code is a validation failure rather than a silent fallback.
Personalising one survey per link
One survey can serve several brands, each with its own name, review page and privacy policy. The survey holds the text, with a variable wherever something changes. Each link holds the values for its respondent.
In the survey: write the variables
A variable is a name in double braces, such as {{brand}}. In the survey editor you can write one in a question, in the header, in the footer and in the redirect URL.
| Where | Written in the survey | What the respondent of the link below gets |
|---|---|---|
| Question | How likely are you to recommend {{brand}}? | How likely are you to recommend Example Brand? |
| Footer | A link to {{privacy_url}} | A link to Example Brand's privacy policy |
| Redirect URL | {{review_url}} | Sent to https://reviews.example.com/evaluate/AbCdEf123456 |
On each link: send the values
Add variables to the link, next to metadata:
json
{
"links": [
{
"reference": "booking-55120",
"language": "es",
"metadata": { "author_email": "ana@example.com" },
"variables": {
"brand": "Example Brand",
"review_url": "https://reviews.example.com/evaluate/AbCdEf123456",
"privacy_url": "https://www.example.com/privacy-policy"
}
}
]
}Names must match the survey's exactly, capitals included: Brand does not fill {{brand}}.
Two things work together with variables:
- Language. The header and the footer are written once per language in the survey editor.
languagepicks the text,variablesfill it in. - Redirect. The redirect only happens for respondents whose answers match the survey's redirect rule, for example a score of 9 or 10. The rule and its destination (
{{review_url}}above) are set in the survey editor. The value can be a personal link you created for that respondent, such as a review invitation.
When a value is missing
| Case | What happens |
|---|---|
| The link has no value for a variable | The survey's default for that variable is shown. Defaults are set in the survey editor. |
| No value and no default | Nothing is shown in its place. |
| The redirect URL fills in to nothing | No redirect. |
| The link has a value the survey does not use | The link is created and the value is ignored. |
Variables or segments?
They do different jobs, so the same information may go in both.
variables | metadata.segments | |
|---|---|---|
| What it is for | Changing what the respondent sees | Describing the respondent, to filter results |
| Shown in the survey | Yes | No |
| Saved with the answer | No | Yes |
To show the brand in the question and filter results by brand, send it in both.
Rules
| What | Rule |
|---|---|
| Name | Letters, digits and _. Up to 64 characters. Case-sensitive. |
| Value | Text, 1 to 500 characters. Leave a variable out rather than sending it empty. |
| Variables per link | Up to 20. |
| Total size | The whole variables object, as JSON, is at most 2,048 bytes. |
Name ending in _url | The value must be a full https:// or http:// address. |
A link that breaks a rule is not created, and its entry in the response says which variable and why:
json
{
"index": 0,
"reference": "booking-55120",
"status": "error",
"error": {
"code": "VALIDATION_FAILED",
"detail": "variables.privacy_url: privacy_url must be an http(s):// URL"
}
}So a mistyped privacy link is caught when you create the link, not by your respondent. The other links of the batch are still created: see Creating links in bulk.
What happens to the values
- Shown as text. HTML in a value is never rendered, and a redirect only ever goes to a web address.
- Set by the sender. Like identity, the values are fixed when the link is created. The survey never reads them from the URL, so the recipient cannot change them.
- Kept on the link only. The values stay on the link until it expires, and come back as
variableswhen you retrieve the link. They are never saved with the respondent's answer, so a personal review link does not end up in the response data. - Not editable. To change a value, revoke the link and create a new one.
Segments and size
segments accepts up to 50 entries of up to 100 characters each.
Metadata travels to the survey app inside a size-limited context. If yours is large enough to exceed it, segments are dropped and identity is kept — a response attributed to the right person with no segments is more useful than the reverse. Keep segments modest if you also care about them.
reference is yours, up to 128 characters, and Zefi never interprets it. It is echoed back on both successes and failures so you can match results to rows.
Unknown fields are rejected
The request schema is strict. A misspelled field is a 400, not a silently ignored one.
The path on an unrecognised-key issue points at the object that carried it — links.0, not links.0.metadaata — and the message names the offending key, so check the message and not only the path when you are hunting a typo.
That is the friendlier failure. A field quietly dropped becomes a batch of links missing the attribution you thought you had sent, discovered weeks later.
Revoking a link
DELETE on a link revokes it immediately: 204, and the link stops working. Deleting a link that never existed, or has already been consumed, returns 404.
Revoking is not reversible. Mint a new link instead.
