Skip to content

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 creation

You 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" \
  -i
js
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=41
json
{
  "items": [],
  "next_cursor": null
}

Three things worth noticing, because they hold everywhere:

  • RateLimit is on every response, successes included, so you never have to count your own calls. See Rate limits.
  • Lists are cursor-paginated. next_cursor being null is 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" -i
json
{ "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:

Zefi API v1