Server API

The server API lets your own backend invite someone to Streamiva through one of your signup links. Streamiva sends the invitation by e-mail; you never learn whether or as whom they signed up.

Use it when people give you their address on your own page or in your own app. If you only want a sign-up form on your site, the widget needs no server and no key.

Base URL

Every path below is under https://streamiva.net, for example https://streamiva.net/v1/partner/signups.

Testing against stage

https://stage.streamiva.net serves the same API under the same paths. It is the next release of Streamiva, so it may have changes that production does not have yet.

• Stage shares accounts with production. Your account, keys and signup links are the same on both, and there are no separate test keys.
• An invitation sent through stage is a real e-mail to a real address, and it counts toward the same limits. Its link opens Streamiva on stage.
• Invite only addresses you own while testing.

API keys

Sign in to Streamiva and open the developer dashboard (https://streamiva.net/en/developer). It opens once Streamiva approves your developer account. Create keys there. A key starts with sk_live_ and is shown once: keep it on your server, never in a web page or app.

You can have at most 2 active keys, so you can rotate without downtime. A paused key cannot be rotated.

Inviting someone

POST https://streamiva.net/v1/partner/signups
Authorization: Bearer sk_live_...
Content-Type: application/json

{"email": "viewer@example.com", "bundle_id": "<link code>", "ref": "newsletter", "locale": "he"}

• Give email. The API also takes phone (E.164, like +972501234567), but phone numbers are refused with 422 for now.
• bundle_id is the code of one of your live signup links: the <code> in https://streamiva.net/join/<code>. A link is live while it is active, unexpired and under its cap.
• ref (optional) tags the signup in the link's stats, as on the link itself: 1 to 40 letters, digits, _ or -. Any other value is dropped without an error, and the signup counts as no ref.
• locale (optional) is he, ru or en, he by default. It sets the language of the e-mail and of Streamiva when the person arrives.

The answer is 202 Accepted:

{"invitation_id": "inv_..."}

The answer is the same whether or not the address already has a Streamiva account. Keep invitation_id if you like: it is the reference to give Streamiva support about this invitation.

A full call against stage:

curl -i https://stage.streamiva.net/v1/partner/signups \
  -H "Authorization: Bearer $STREAMIVA_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "bundle_id": "<link code>", "ref": "test", "locale": "en"}'

What the person gets

Streamiva e-mails the address from signup@streamiva.net; you never see or send that e-mail. Expect delivery within a minute. Rarely, the same e-mail arrives twice.

The e-mail says one more step is left, has a "Finish signing up" button (in the e-mail's language), and says the link works for 7 days.

Opening the link signs the person in to Streamiva with that address, with no code to type. Then:

• A new account finishes setup and gets the link's Plugins. It counts in the link's stats as an account created, under the ref you sent.
• An existing account lands on the link's page, where it can add the Plugins to a Profile it picks. It does not count as an account created.

The link signs in once; a second open asks for a normal sign-in, with a code e-mailed to the address. After 7 days it can no longer be opened.

Errors

Every error is JSON with a detail. For a request body that does not fit the format above, detail is a list, one entry per problem:

{"detail": [{"type": "missing", "loc": ["body", "bundle_id"], "msg": "Field required", "input": {}}]}

That happens for a missing bundle_id, a locale other than he, ru or en, or a body that is not JSON. The body is checked before the key, so these answers come even without a key.

Every other error has detail as one message:

No answer carries a Retry-After header. A 5xx is Streamiva's fault and says nothing more; retrying is safe, but if the first call got through, the retry answers 429 This address was invited recently.

Limits

• 60 requests a minute per key.
• 500 invitations a day per developer.
• Each address at most once a day and 3 times in 30 days, from any developer.

The per-minute limit counts every request that gets past the key check, including ones refused with 422.

Keeping a key in good standing

If more than 5% of a key's invitations in a day bounce (once at least 20 were sent), or recipients mark 3 as spam within 30 days, the key is paused. Every call with it then answers 403 until Streamiva lifts the pause; you get no other notice.

• Invite only people who asked for it, on a form they filled in themselves.
• Protect that form from bots (a rate limit per visitor, a hidden field bots fill in), since every address you send costs you limit and reputation.
• Do not retry an address that bounced.

You get no per-person callbacks and no list of who signed up: invited signups show only as counts in the link's stats.