---
title: "Resolve one or more provider IDs to entities (primary endpoint)"
method: POST
path: "/batch/resolve"
---

# Resolve one or more provider IDs to entities (primary endpoint)

`POST /batch/resolve`

The primary bulk translation endpoint. Given a list of `(provider, id, type?)` items,
returns the matching entities. Use this both for single lookups (one-element array)
and bulk translation (up to 100 per request).

**Translation workflow** — to translate N Opta IDs into Wyscout IDs in one call:
```
POST /batch/resolve
{ "items": [{"provider": "opta", "id": "..."}, ...],
  "targets": ["wyscout"] }
```
Each result's `external_ids` will contain only the requested target providers,
dramatically reducing payload size. The `from` field on every result echoes
the input so callers can correlate regardless of array order or `not_found` gaps.

**Error handling** — malformed items return inline errors (`missing_fields`,
`unknown_provider`, `not_found`) rather than failing the whole batch. The
response `count` always equals `items.length`; position is preserved.

Maximum 100 items per request.

## Request body

- object
  - `items` object[], required
    - `provider` 'wikidata' | 'transfermarkt' | 'transfermarkt_manager' | 'fbref' | 'fbref_verified' | 'soccerway' | 'sofascore' | 'flashscore' | 'opta' | 'opta_numeric' | 'optacore' | 'premier_league' | '11v11' | 'espn' | 'national_football_teams' | 'worldfootball' | 'soccerbase' | 'kicker' | 'uefa' | 'lequipe' | 'fff_fr' | 'serie_a' | 'besoccer' | 'footballdatabase_eu' | 'eu_football_info' | 'hugman' | 'german_fa' | 'statmuse_pl' | 'sofifa' | 'soccerdonna' | 'dongqiudi' | 'playmakerstats' | 'understat' | 'whoscored' | 'clubelo' | 'sportmonks' | 'api_football' | 'fotmob' | 'thesportsdb' | 'impect' | 'wyscout' | 'skillcorner' | 'heimspiel' | 'capology', required — Name of a supported data provider. Sourced from `VALID_PROVIDERS` in the worker. Update this list whenever a new provider is added.
    - `id` string, required
    - `type` 'player' | 'team' | 'coach' | 'competition' | 'season' | 'match' — Optional entity type disambiguator for reused provider IDs
  - `targets` ProviderName[] — Optional filter on response `external_ids`. When provided, each matched entity's `external_ids` will contain only the named providers, and the `qid` convenience field is populated only if `wikidata` is in the list. Unknown provider names are silently ignored. Useful for trimming response size when you only need one or two target IDs per translation.

## Response `200`

Batch resolve results. Position is preserved, `count` equals `items.length`.

- BatchResolveResponse
  - `results` union[] — Position-preserved, one result per input item. `count` always equals the input `items.length`. Every result — success or error — includes a `from` field echoing the input for correlation.
    - union
      - object
        - `from` FromEcho, required — Echo of the input `(provider, id)` pair so callers can correlate results.
          - `provider` string, required
          - `id` string, required
          - `type` string, nullable
        - `reep_id` string — Universal Reep ID (reep_<type_prefix><8hex>). This is the canonical identifier.
        - `qid` string, nullable — Wikidata QID (convenience field, null for entities not in Wikidata)
        - `type` 'player' | 'team' | 'coach' | 'competition' | 'season' | 'match'
        - `name_en` string
        - `aliases_en` string, nullable
        - `full_name` string, nullable
        - `date_of_birth` string, nullable
        - `nationality` string, nullable
        - `position` string, nullable — Coarse position (forward, midfielder, defender, goalkeeper). Players only.
        - `position_detail` string, nullable — Granular position from Transfermarkt (e.g. Centre-Back, Attacking Midfield, Right Winger). Players only.
        - `current_team_reep_id` string, nullable — Reep ID of current team (players only)
        - `height_cm` number, nullable
        - `country` string, nullable — For teams only
        - `founded` string, nullable — For teams only
        - `stadium` string, nullable — For teams only
        - `competition_reep_id` string, nullable — For seasons only — Reep ID of the parent competition
        - `match_date` string, nullable — For matches only — ISO date of the fixture
        - `kickoff_utc` string, nullable — For matches only — ISO kickoff timestamp when known
        - `home_team_reep_id` string, nullable — For matches only — Reep ID of the home team
        - `away_team_reep_id` string, nullable — For matches only — Reep ID of the away team
        - `home_score` integer, nullable — For matches only — final home score when known
        - `away_score` integer, nullable — For matches only — final away score when known
        - `round_label` string, nullable — For matches only — provider round label
        - `referee` string, nullable — For matches only
        - `attendance` integer, nullable — For matches only
        - `season_label` string, nullable — For matches only — provider-native season label when no canonical season mapping exists
        - `source` string — Provenance (wikidata, opta, etc.)
        - `external_ids` object — Map of provider name to external ID (includes wikidata QID)
        - `_deprecated` boolean — Present and `true` when the client asked for a `reep_id` that has been retired. The body carries the canonical entity's fields; the `_canonical_id` meta tells the client the underlying `reep_id` has moved. Provider-id paths (e.g. `?id=Q42`) redirect silently and do NOT set this field.
        - `_canonical_id` string, nullable — When `_deprecated=true`, the canonical successor `reep_id`. Null on a retirement (entity removed with no successor — a 410 Gone body).
        - `_deprecated_at` string — ISO timestamp when the retired `reep_id` was soft-deleted.
        - `_deprecated_reason` 'retired' | 'chain_depth_exceeded' | 'canonical_missing' — Present on error-shape deprecation responses (410 Gone body). `retired` = no successor. The other two are defensive fallbacks that should not surface in normal operation.
      - object — Error variant
        - `from` FromEcho, required — Echo of the input `(provider, id)` pair so callers can correlate results.
          - `provider` string, required
          - `id` string, required
          - `type` string, nullable
        - `error` 'not_found' | 'missing_fields' | 'unknown_provider' | 'unknown_type' | 'ambiguous', required
        - `types` string[] — Present on `ambiguous` results to show the matching entity classes
  - `count` integer

## Other responses

- `400` — Invalid body, empty items array, or exceeds 100 item limit

---

[API](https://skmtc.net/withqwerty/apis/the-reep-register.md) · [All operations](https://skmtc.net/withqwerty/apis/the-reep-register/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/withqwerty/the-reep-register/versions/82844e1c9405/schema)