# Predictive Lineups

## Overview

The Predictive Lineups API returns AI-generated starting lineup predictions for upcoming fixtures. Predictions are generated and refreshed at multiple timeframes before kickoff:

* 96 hours before kickoff
* 72 hours before kickoff
* 48 hours before kickoff
* 24 hours before kickoff
* 12 hours before kickoff
* 3 hours before kickoff
* 1 hour before kickoff
* At kickoff

Each call returns the most recent prediction available for the fixture.

***

## Endpoint

### Get Predicted Lineup

Returns the latest predicted lineup for a fixture.

```
POST https://engage-api.lsports.eu/api/lineups
```

**Request body**

| Field       | Type    | Required | Description                            |
| ----------- | ------- | -------- | -------------------------------------- |
| `username`  | string  | Yes      | Package credentials username           |
| `password`  | string  | Yes      | Package credentials password           |
| `packageId` | integer | Yes      | Your package ID                        |
| `fixtureId` | long    | Yes      | The fixture to retrieve the lineup for |

```json
{
  "username": "user@example.com",
  "password": "password123",
  "packageId": 123,
  "fixtureId": 18793806
}
```

**Success (200)**

Returns the latest predicted lineup. If no prediction has been generated yet for the fixture, `lastUpdate` is `null` and both lineup arrays are empty.

```json
{
  "fixtureId": 18793806,
  "lastUpdate": "2025-05-17T10:30:00Z",
  "homeLineup": [
    {
      "playerId": 178106,
      "name": "Lisandro Martinez",
      "shirtNumber": 6,
      "isCaptain": false,
      "position": "CB",
      "status": 1,
      "team": {
        "id": 22,
        "name": "Manchester United",
        "sportId": 6046,
        "locationId": 243
      },
      "nationality": {
        "id": 203,
        "name": "Argentina"
      },
      "birthDate": "1998-01-18T00:00:00Z"
    }
  ],
  "awayLineup": [...]
}
```

**Validation Error (400)**

```json
{ "error": "Invalid package credentials" }
```

Possible validation errors:

* `"PackageId must be a positive integer"`
* `"Username is required"`
* `"Password is required"`
* `"Invalid package credentials"`

**Server Error (500)**

```json
{ "error": "An unexpected error occurred" }
```

**cURL**

```bash
curl -X POST https://engage-api.lsports.eu/api/lineups \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "password123",
    "packageId": 123,
    "fixtureId": 18793806
  }'
```

***

## Response Fields

### FixtureLineup

| Field        | Type                                   | Description                                                          |
| ------------ | -------------------------------------- | -------------------------------------------------------------------- |
| `fixtureId`  | long                                   | The fixture ID                                                       |
| `lastUpdate` | string (ISO 8601) or null              | When the prediction was generated. Null if no prediction exists yet. |
| `homeLineup` | array of [PlayerLineup](#playerlineup) | Predicted home team players                                          |
| `awayLineup` | array of [PlayerLineup](#playerlineup) | Predicted away team players                                          |

### PlayerLineup

| Field         | Type                                            | Description                                         |
| ------------- | ----------------------------------------------- | --------------------------------------------------- |
| `playerId`    | long                                            | LSports player ID (0 if not resolved)               |
| `name`        | string                                          | Player name                                         |
| `shirtNumber` | integer or null                                 | Shirt number                                        |
| `isCaptain`   | boolean                                         | Whether the player is predicted to captain the side |
| `position`    | string                                          | Predicted position (see [Positions](#positions))    |
| `status`      | integer                                         | Player status (see [Status Values](#status-values)) |
| `team`        | [PlayerTeam](#playerteam) or null               | Club team from LSports mapping                      |
| `nationality` | [PlayerNationality](#playernationality) or null | Nationality from LSports mapping                    |
| `birthDate`   | string (ISO 8601) or null                       | Date of birth from LSports mapping                  |

### PlayerTeam

| Field        | Type           | Description           |
| ------------ | -------------- | --------------------- |
| `id`         | integer        | LSports team ID       |
| `name`       | string or null | Team name             |
| `sportId`    | integer        | Sport ID              |
| `locationId` | integer        | Location (country) ID |

### PlayerNationality

| Field  | Type           | Description            |
| ------ | -------------- | ---------------------- |
| `id`   | integer        | LSports nationality ID |
| `name` | string or null | Nationality name       |

***

## Status Values

| Value | Meaning    |
| ----- | ---------- |
| `1`   | Starter    |
| `2`   | Substitute |
| `3`   | Injured    |
| `4`   | Suspended  |

***

## Positions

Positions reflect the player's specific role in the predicted lineup for this match.

| Code  | Position                      |
| ----- | ----------------------------- |
| `GK`  | Goalkeeper                    |
| `CB`  | Centre-back                   |
| `RB`  | Right-back                    |
| `LB`  | Left-back                     |
| `RWB` | Right wing-back               |
| `LWB` | Left wing-back                |
| `CDM` | Defensive midfielder          |
| `CM`  | Central midfielder            |
| `RM`  | Right midfielder              |
| `LM`  | Left midfielder               |
| `AMC` | Attacking midfielder (centre) |
| `AMR` | Attacking midfielder (right)  |
| `AML` | Attacking midfielder (left)   |
| `RW`  | Right winger                  |
| `LW`  | Left winger                   |
| `SS`  | Second striker                |
| `ST`  | Striker                       |
| `CF`  | Centre-forward                |

***

## Notes

* Players with `playerId: 0` could not be resolved to an LSports player ID. Their `team`, `nationality`, and `birthDate` fields will be `null`.

***

## See also

* [Customers API Guide](https://github.com/lsportsltd/lsports-products-docs/blob/main/engage/predictive-lineups/customers-api-guide.md) — package activation, snapshot, and status endpoints
* [Metadata API Guide](https://github.com/lsportsltd/lsports-products-docs/blob/main/engage/predictive-lineups/metadata-api-guide.md) — look up sport, location, league, period, and incident reference data


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lsports.eu/u/engage/lineups-api-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.