API Overview

Getting started with the Wintro Customer API

The Wintro Customer API lets you programmatically access your company’s referral data. Use it to build custom leaderboards, dashboards, reports, or integrations with your internal tools.

For your own agent or script there is the Agent API: your vacancies, their best candidates and who can introduce them, read-only. It has its own address, limits and errors; this page is about /api/v1.

Base URL

https://www.wintro.app/api/v1

Authentication

All requests must include a Bearer token in the Authorization header:

curl -H "Authorization: Bearer wintro_abc123..." \
  https://www.wintro.app/api/v1/leaderboard

Tokens are prefixed with wintro_ and can be created by a recruiter admin under Settings > API. Each token is scoped to a specific company and set of permissions.

Scopes

When creating a token, select which endpoints it can access:

Scope	Endpoint	Description
leaderboard:read	/api/v1/leaderboard	Employee leaderboard data

Need access to more data? Reach out to your Wintro contact and we’ll work with you to enable additional endpoints tailored to your needs.

Rate Limiting

Two limits, checked in this order:

1. 30 requests a minute from one IP address, before the token is read. Over it, the API answers 429 with { "error": "Too Many Requests", "retryAfter": 12 }.
2. 100 requests a minute per endpoint for your company, all tokens together. Over it, 429 with the error format below, code RATE_LIMITED.

Both answer with a Retry-After header, in seconds: wait that long before trying again. Every response carries the per-address limit:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Response Format

All successful responses follow this structure:

{
  "data": [ ... ],
  "meta": {
    "generatedAt": "2026-03-16T12:00:00.000Z",
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 42,
      "totalPages": 5
    }
  }
}

Error Format

All errors follow a consistent structure:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Status	Code	Description
400	BAD_REQUEST	Invalid query parameters
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	MISSING_SCOPE	Token lacks the required scope for this endpoint
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Unexpected server error

Pagination

Endpoints that return lists support cursor-free page-based pagination:

Parameter	Default	Max	Description
page	1	-	Page number (starts at 1)
pageSize	varies	varies	Items per page (see endpoint docs)

Creating an API Token

1. Go to Settings > API in the Wintro dashboard
2. Click Create Token
3. Enter a name and select the scopes you need
4. Copy the token immediately, it is only shown once

To revoke a token, click Revoke next to it in the token list.