Theme
Quickstart
Make your first authenticated call in about five minutes, and pick up the four things every Zefi endpoint has in common while you do it.
1. Get a key
Keys are created in the platform, not through the API. Open Settings → API Keys in the workspace you want to act on, grant survey_links:read, and copy the secret — it is shown once.
Scopes and expiry are covered in Authentication.
bash
export ZEFI_API_KEY="…" # copied at creationYou do not choose a workspace
A key is bound to one workspace when it is created, and every request carries that binding. Nothing in a URL or a body selects a workspace — the key is the only thing that decides.
2. Make a request
Every call goes to the same base URL, versioned in the path, with the key as a bearer token. This one lists the survey links on a campaign — a read, so it changes nothing while you find your feet.
Take a campaign id from the platform: open a campaign under Surveys and copy the UUID from the page URL.
bash
export CAMPAIGN_ID="…"
curl "https://public.eu.zefi.ai/v1/campaigns/$CAMPAIGN_ID/links?limit=5" \
-H "Authorization: Bearer $ZEFI_API_KEY" \
-ijs
const res = await fetch(
`https://public.eu.zefi.ai/v1/campaigns/${process.env.CAMPAIGN_ID}/links?limit=5`,
{ headers: { Authorization: `Bearer ${process.env.ZEFI_API_KEY}` } },
);
console.log(res.status, res.headers.get('RateLimit'));
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
const { items, next_cursor } = await res.json();
console.log(items.length, 'links,', next_cursor ? 'more pages' : 'that is all');python
import os, requests
res = requests.get(
f"https://public.eu.zefi.ai/v1/campaigns/{os.environ['CAMPAIGN_ID']}/links",
headers={"Authorization": f"Bearer {os.environ['ZEFI_API_KEY']}"},
params={"limit": 5},
timeout=10,
)
print(res.status_code, res.headers.get("RateLimit"))
res.raise_for_status()
body = res.json()
print(len(body["items"]), "links,", "more pages" if body["next_cursor"] else "that is all")3. Read the response
http
HTTP/1.1 200 OK
Content-Type: application/json
RateLimit: limit=600, remaining=599, reset=41json
{
"items": [],
"next_cursor": null
}Three things worth noticing, because they hold everywhere:
RateLimitis on every response, successes included, so you never have to count your own calls. See Rate limits.- Lists are cursor-paginated.
next_cursorbeingnullis the only signal that a listing is exhausted — a short page does not mean the last one. - Timestamps are RFC 3339 in UTC, and ids are opaque UUIDs.
All of it is in Requests and responses.
4. Read a failure
Break the call on purpose. First, a bad credential:
bash
curl "https://public.eu.zefi.ai/v1/campaigns/$CAMPAIGN_ID/links" \
-H "Authorization: Bearer not-a-real-key" -ijson
{ "message": "Forbidden" }Now break it a different way — ask for a page size the API will not accept:
json
{
"type": "about:blank",
"title": "Validation failed",
"status": 400,
"code": "VALIDATION_FAILED",
"detail": "One or more fields are invalid.",
"errors": [{ "path": "limit", "message": "Too big: expected number to be <=100" }]
}That second shape is every failure the service produces: an RFC 9457 problem document with a stable code. Branch on code — not on status, which is coarser, and not on type, which is always about:blank.
The bare {"message":"Forbidden"} is the exception: credentials are rejected at the gateway, before the service runs, so that response has no code and no problem shape. Errors covers both.
Next
You now have the whole contract — auth, responses, pagination, budgets and failures. Pick a resource and build:
- Survey links — what they are, how they expire, and what a recipient cannot change
- Creating links in bulk — up to 50 per call, and what a
207means - API reference — every endpoint, field and response
