---
title: The ids object
description: How the ids block identifies media across FlickList and external sources, on both reads and writes.
section: Core concepts
order: 1
---

# The ids object

Every Trakt-shaped object on the v3 API carries an `ids` block that ties the item to FlickList's own catalog and to the external databases your client already tracks.

```json
{
  "title": "Breaking Bad",
  "year": 2008,
  "ids": {
    "fldb": "flt_9f2c8a1b",
    "slug": "breaking-bad",
    "tmdb": 1396,
    "imdb": "tt0903747",
    "tvdb": 81189,
    "anilist": null
  }
}
```

`fldb` is FlickList's own permanent public ID. It never gets reassigned, even when two catalog rows are merged into one, so it's the one identifier you can store and trust long term. Every other key is best-effort: `tmdb` is the primary external ID FlickList resolves against, `imdb` is a reliable backup when no TMDB match exists, and `tvdb` and `anilist` are nullable extras that fill in for titles those sources cover.

> [!TIP]
> The `ids` block gains new keys over time as FlickList adds sources. Ignore any key you don't recognize instead of failing on it.

## Using ids as input

Write endpoints across Sync and Scrobble accept an `ids` block to identify the item you're acting on. You don't need every key, only enough to resolve to one catalog row:

```json
{ "ids": { "tmdb": 1396 }, "media_type": "show" }
```

When an item carries more than one key, FlickList resolves in a fixed order: `fldb` first, then `tmdb`, then `imdb`, then `tvdb`. The first key present wins and the rest are ignored for that item. `fldb` resolves on its own since its prefix self-describes the item; every other key needs `media_type` on the same request, because a movie and an unrelated show adaptation can otherwise share the same external ID.

`media_type` accepts `"tv"` as a synonym of `"show"` on writes, so you don't need to translate your own internal vocabulary before sending a request.

Bulk write endpoints accept up to 1000 items per request. An item that doesn't resolve to any catalog row (an empty `ids` block, an unrecognized `media_type`, or no matching external id) isn't a request failure. It comes back in a `not_found` array so you can tell which items to look at, while every resolvable item in the same batch still succeeds:

```json
{
  "added": 3,
  "not_found": [
    { "ids": { "tmdb": 999999999 }, "media_type": "show" }
  ]
}
```

## Keys

| Key | Type | Presence | Notes |
| --- | --- | --- | --- |
| `fldb` | string | Always present | FlickList's permanent public ID (`flm_`/`flt_` prefix). Survives catalog merges, never reassigned. |
| `slug` | string or null | Read responses only | FlickList's URL slug for the title, when one exists. |
| `tmdb` | integer or null | Best-effort | Primary external ID FlickList resolves against. |
| `imdb` | string or null | Best-effort | Backup identifier when no TMDB match exists. |
| `tvdb` | integer or null | Best-effort, nullable | Present when FlickList has cross-linked the title to TVDB. |
| `anilist` | integer or null | Best-effort, nullable | Present when FlickList has cross-linked the title to AniList. |

New keys can appear in this block at any time as FlickList adds sources. Treat any key not in this table the same way you treat a null value: ignore it and move on.