---
title: "Get linups by match id"
method: GET
path: "/football/lineups/{matchId}"
tags: ["Football.Lineups"]
---

# Get linups by match id

`GET /football/lineups/{matchId}`

## Request

- Base URL: `https://sports.highlightly.net`
- URL: `https://sports.highlightly.net/football/lineups/{matchId}`
- Auth: none declared. Required headers: `x-rapidapi-host`, `x-rapidapi-key`
- TypeScript: <https://skmtc.dev/highlightly/apis/sports-api-highlightly/docs/football/lineups/:matchId/get.ts> (a function with typed inputs; its response is checked against the schema)

> Lineups will become available 30 minutes before the game starts or, at the latest, 15 minutes after kickoff.

> Refresh interval: Once every 10 minutes

Retrieve home and away team lineups for a specific match.

Understanding the returned data structure is crucial for accurate rendering. The `formation` and `initialLineup` fields are closely related. The first row will always include the team's goalkeeper, while subsequent rows will have the number of entries specified by the formation field.

Below is an example of what you can aim to achieve with the lineup endpoint:

![Football lineups example](https://highlightly.net/assets/img/documentation/football/lineups.png)

## Path parameters

- `matchId` number, required

## Headers

- `x-rapidapi-host` string, required
- `x-rapidapi-key` string, required

## Response `200`

- FootballLineupsResponseDto
  - `homeTeam` FootballLineupsTeamDto, required
    - `id` number, required
    - `logo` string, required
    - `formation` string, required
    - `name` string, required
    - `substitutes` FootballLineupsPlayerDto[], required
      - `id` number
      - `name` string, required
      - `number` number, required
      - `position` 'Goalkeeper' | 'Defender' | 'Midfielder' | 'Forward', required
    - `initialLineup` FootballLineupsPlayerDto[], required: 2D grid of players representing their position on the board. The first entry will always be the goal keeper. Other entries will follow the team formation, e.g. formation 4-2-3-1 means that there will be 4 more arrays each containing the associated number of players in the correct order.
      - `id` number
      - `name` string, required
      - `number` number, required
      - `position` 'Goalkeeper' | 'Defender' | 'Midfielder' | 'Forward', required
  - `awayTeam` FootballLineupsTeamDto, required
    - `id` number, required
    - `logo` string, required
    - `formation` string, required
    - `name` string, required
    - `substitutes` FootballLineupsPlayerDto[], required
      - `id` number
      - `name` string, required
      - `number` number, required
      - `position` 'Goalkeeper' | 'Defender' | 'Midfielder' | 'Forward', required
    - `initialLineup` FootballLineupsPlayerDto[], required: 2D grid of players representing their position on the board. The first entry will always be the goal keeper. Other entries will follow the team formation, e.g. formation 4-2-3-1 means that there will be 4 more arrays each containing the associated number of players in the correct order.
      - `id` number
      - `name` string, required
      - `number` number, required
      - `position` 'Goalkeeper' | 'Defender' | 'Midfielder' | 'Forward', required

## Other responses

- `400`: Bad request descriptive error.
- `500`: Internal server error.

---

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