Employer API

How It Works

The API works with the speed test links you make on your workspace page: each link is for one role, with the minimum download and upload speeds you need.

Getting a Key

• The workspace owner creates keys on the workspace page, under API keys.
• A key is shown once, when it is created: copy it then. Keys start with somhire_live_.
• Keep it secret. A key sends invitations in your workspace's name and reads your applicants, so use it from your server, never in a web page or an app you hand out.
• Revoking a key on the same page stops it at once and removes the webhooks it added.

Making Requests

Send every request to the base URL, https://speedof.me/for-employers/api/v1, with your key in the Authorization header as a Bearer token. Request bodies and answers are JSON, and times are UTC, in ISO 8601.

curl https://speedof.me/for-employers/api/v1/me \
  -H "Authorization: Bearer $SPEEDOFME_KEY"

Routes

• GET/meYour workspace
• GET/linksYour speed test links
• POST/invitesInvite an applicant
• GET/applicantsYour latest applicants
• POST/hooksAdd a webhook
• DELETE/hooks/{id}Remove a webhook

{
  "workspace": {
    "org": "Acme Support",
    "plan": "team",
    "livemode": true
  }
}

{
  "data": [
    {
      "slug": "support-agent-7kq4m",
      "url": "https://speedof.me/test/support-agent-7kq4m",
      "role": "Support Agent",
      "min_download_mbps": 25,
      "min_upload_mbps": 5,
      "active": true
    }
  ]
}

curl https://speedof.me/for-employers/api/v1/invites \
  -H "Authorization: Bearer $SPEEDOFME_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "link": "support-agent-7kq4m",
    "email": "jane@example.com",
    "reference": "cand-123"
  }'

{
  "url": "https://speedof.me/test/support-agent-7kq4m?...",
  "reference": "cand-123",
  "expires_at": "2026-12-12T20:00:00Z",
  "emailed": true
}

curl "https://speedof.me/for-employers/api/v1/applicants?reference=cand-123" \
  -H "Authorization: Bearer $SPEEDOFME_KEY"

{
  "data": [
    {
      "id": 4567,
      "reference": "cand-123",
      "submitted_at": "2026-11-12T20:30:00Z",
      "link": {
        "slug": "support-agent-7kq4m",
        "role": "Support Agent",
        "min_download_mbps": 25,
        "min_upload_mbps": 5
      },
      "name": "Jane Doe",
      "result": "meets",
      "download_mbps": 85.2,
      "upload_mbps": 12.1,
      "latency_ms": 23,
      "provider": "PLDT",
      "connection": "Home internet",
      "city": "Quezon City",
      "country": "PH",
      "phone_last4": "0614",
      "phone_confirmed": true,
      "certificate_url": "https://speedof.me/v/7KQ4-MR2D"
    }
  ]
}

curl https://speedof.me/for-employers/api/v1/hooks \
  -H "Authorization: Bearer $SPEEDOFME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/speedofme"}'

{
  "id": 12,
  "url": "https://example.com/speedofme",
  "secret": "whsec_...",
  "created_at": "2026-11-12T20:00:00Z"
}

curl -X DELETE https://speedof.me/for-employers/api/v1/hooks/12 \
  -H "Authorization: Bearer $SPEEDOFME_KEY"

{
  "deleted": true
}

The Applicant

GET /applicants lists applicants, and each webhook carries one, in this shape. It holds what your applicant list shows, rounded as it shows it, and never the applicant's email address or full phone number.

idinteger

The result's id.

referencestring or null

Your reference from the invitation the applicant tested through, or null.

submitted_atstring

When the applicant sent you their result.

linkobject

The speed test link they used: its slug, role, min_download_mbps and min_upload_mbps, as in GET /links.

namestring or null

The name the applicant entered.

resultstring

meets or below: whether the download and upload speeds meet the link's minimums, compared as they are shown here. A minimum that is not set is always met. It looks at the speeds only; connection says what kind of line they tested on.

download_mbpsnumber or null

Download speed in Mbps, as the list and the certificate show it: one decimal below 100, whole numbers from 100.

upload_mbpsnumber or null

Upload speed, shown the same way.

latency_msinteger or null

Latency in milliseconds.

providerstring or null

The connection's internet provider.

connectionstring

The kind of line: Home internet, Business network, VPN or data center, Mobile network or Connection type unknown.

citystring or null

The approximate city of the connection.

countrystring or null

Its two-letter country code, such as PH.

phone_last4string or null

The last 4 digits of the phone number the applicant gave.

phone_confirmedboolean

Whether they confirmed that phone with a one-time code.

certificate_urlstring or null

Where the certificate the applicant bought can be checked, or null when there is none.

Webhooks

A webhook sends each new applicant to your own system: everyone who arrives on your list after you add it, shortly after they submit. Applicants from before it was added are not sent: read them with GET /applicants.

The request

A POST of this JSON to the webhook's address:

{
  "id": "evt_8812",
  "type": "applicant.submitted",
  "created": "2026-11-12T20:33:00Z",
  "livemode": true,
  "data": {
    "id": 4567,
    "reference": "cand-123",
    "submitted_at": "2026-11-12T20:30:00Z",
    "link": {
      "slug": "support-agent-7kq4m",
      "role": "Support Agent",
      "min_download_mbps": 25,
      "min_upload_mbps": 5
    },
    "name": "Jane Doe",
    "result": "meets",
    "download_mbps": 85.2,
    "upload_mbps": 12.1,
    "latency_ms": 23,
    "provider": "PLDT",
    "connection": "Home internet",
    "city": "Quezon City",
    "country": "PH",
    "phone_last4": "0614",
    "phone_confirmed": true,
    "certificate_url": "https://speedof.me/v/7KQ4-MR2D"
  }
}

idstring

The event's id, the same on every try.

typestring

applicant.submitted, the only type.

createdstring

When the event was made.

livemodeboolean

Always true.

dataobject

The applicant, as they are when it is sent.

Headers

SOM-Event-Id

The event's id, as in the body.

SOM-Signature

t=1794515580,v1= and 64 hex characters: the Unix time of this try, and the signature.

Checking the signature

v1 is the hex HMAC-SHA256 of t, a full stop and the raw body, keyed with the webhook's secret: the whole whsec_ string, as text. Compute it over the body exactly as it arrived, before parsing the JSON, compare in constant time, and refuse a stale t, as the examples below do: every try is signed afresh.

const crypto = require('crypto');

// body: the raw request body, exactly as it arrived (a Buffer or a string)
// header: the SOM-Signature header; secret: the webhook's whsec_ secret
function isFromSpeedOfMe(body, header, secret) {
  const sig = Object.fromEntries(String(header || '').split(',').map((p) => p.split('=', 2)));
  const want = crypto.createHmac('sha256', secret).update(sig.t + '.').update(body).digest('hex');
  const got = Buffer.from(String(sig.v1 || ''));
  return got.length === want.length
    && crypto.timingSafeEqual(got, Buffer.from(want))
    && Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
}

// Express: app.post('/speedofme', express.raw({ type: 'application/json' }), ...)
// keeps req.body raw; check it, then JSON.parse(req.body).

import hashlib
import hmac
import time

# body: the raw request body, exactly as it arrived (bytes)
# header: the SOM-Signature header; secret: the webhook's whsec_ secret
def is_from_speedofme(body: bytes, header: str, secret: str) -> bool:
    sig = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
    t = sig.get("t", "")
    try:
        age = abs(time.time() - int(t))
    except ValueError:
        return False
    if age > 300:
        return False
    want = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want.encode(), sig.get("v1", "").encode())

# Flask: is_from_speedofme(request.get_data(), request.headers.get("SOM-Signature"), secret)

To check your code: the secret whsec_zTqObEOJ_mN4EpvbaVePjUJsfRGu8IdTUuoEO9FTvfE, t 1700000000 and the body {"id":"evt_1"} give v1 83a2c92d878a7276bdebbe70487e5d7e51fd1bdafb5f6d22e1ae11b6342eaf78.

Answering

• Answer with any 2xx, quickly. Do slow work after answering; what you send back is ignored.
• Any other answer but 410, or none, is tried again later.
• A delivery can arrive more than once. The event id stays the same on every try, so drop one you have already handled.
• Answer 410 to remove the webhook. Nothing more is sent to it.

Errors

An error answers with its HTTP status and this body. The code is for your program; the message is one sentence for a person, so match on the code.

{
  "error": {
    "code": "invalid_request",
    "message": "email must be a valid email address when send_email is true."
  }
}