---
title: "GET /events/lookup"
method: GET
path: "/events/lookup"
tags: ["Identity"]
---

# GET /events/lookup

`GET /events/lookup`

## Request

- Base URL: `https://api.sockodds.com/v1`
- URL: `https://api.sockodds.com/v1/events/lookup`
- Auth: HTTP bearer

Find our event from an official event id: ESPN's event id, the AFL's match id (`CD_M` and digits) for AFLW, or the NRL's match id (digits) for the Rugby League World Cup. Send `ref` for one event, or `refs` for up to 100 at once. With `ref`, the response is the event, or 404 when no event carries that id. With `refs`, the response lists the ids that matched, in the order sent, each with its event; ids that match nothing are left out. A merged event returns the event it was merged into. Only official sources can be looked up, never a bookmaker's listing id. Each event returned counts as one object towards your allowance, like an event read.

## Query parameters

- `source` 'espn' | 'afl' | 'nrl', required
- `ref` string
- `refs` string

## Response `200`

Event lookup

- union
  - EventEnvelope
    - `data` Event, required
      - `id` string, required
      - `name` string, required
      - `league` NamedKey, required
        - `key` string, required
        - `name` string, required
      - `scheduled_start` string, date-time, required
      - `status` 'scheduled' | 'live' | 'final' | 'postponed' | 'cancelled', required
      - `participants` Participant[], required
        - `role` 'home' | 'away' | 'competitor_1' | 'competitor_2', required: home and away in team sports. In tennis and UFC
        - `identity` union, required
          - NamedKey
            - `key` string, required
            - `name` string, required
          - object
            - `id` string, required
            - `name` string, required
    - `meta` Meta, required
      - `count` integer, required
      - `cursor` string, nullable, required
    - `links` Links, required
      - `next` string, uri-reference, nullable, required
  - EventLookupsEnvelope
    - `data` EventLookup[], required
      - `source` 'espn' | 'afl' | 'nrl', required
      - `ref` string, required
      - `event` Event, required
        - `id` string, required
        - `name` string, required
        - `league` NamedKey, required
          - `key` string, required
          - `name` string, required
        - `scheduled_start` string, date-time, required
        - `status` 'scheduled' | 'live' | 'final' | 'postponed' | 'cancelled', required
        - `participants` Participant[], required
          - `role` 'home' | 'away' | 'competitor_1' | 'competitor_2', required: home and away in team sports. In tennis and UFC
          - `identity` union, required
            - NamedKey
              - …
            - object
              - …
    - `meta` Meta, required
      - `count` integer, required
      - `cursor` string, nullable, required
    - `links` Links, required
      - `next` string, uri-reference, nullable, required

## Other responses

- `default`: Request failed

---

[API](https://skmtc.dev/sockodds/apis/sockodds-api.md) · [All operations](https://skmtc.dev/sockodds/apis/sockodds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sockodds/apis/sockodds-api/revisions/f4c680d355be?raw)