---
title: Families - Controller
description: List and retrieve `Family` models.
---

To implement the `Families` controller, you need to implement 2 API endpoints, we will use these endpoints to fetch families from your system.

## Prerequisites
::grid{cols="2"}
    ::card-baseline{title="Family Model" to="/integrations/models/family"}
      A group of products or services.
      ::flex{class="mt-4"}
        :badge{label="Required" color="green"}
      ::
    ::
::

## SDK

::code-group
```typescript [Typescript]
import { Integrator } from '@churnkey/sdk'
import { Context } from '../Context'
import { Family } from '../models/Family'

export const Families = Integrator.Families.config({
    ctx: Context,
    async retrieve(ctx, options) {
        const yourFamily = await ctx.db.findFamily(options.id)
        return new Family(yourFamily)
    },
    async list(ctx, options) {
        const yourFamilies = await ctx.db.listFamilies({
            limit: options.limit,
            offset: options.cursor // the value you pass as `next` below
        })
        return {
            data: yourFamilies.map(family => new Family(family)),
            // pass the next cursor if there are more items
            next: yourFamilies.length === options.limit ? offset + limit : undefined
        }
    }
})
```
::

## Endpoints

###  Retrieve :badge{label="Required" color="green"}

`GET /churnkey/families/:id`

This endpoint fetches `Family` by its `id`. Usually, implementation will include finding a family in your database and mapping it to the [Family model](/integrations/models/family).

::collapsible{name="response"}
    ::tabs
        ::div{label="200"}
        Must return `Family` model. See [Family model documentation](/integrations/models/family).
        ::
        ::div{label="Error"}
        See [Error Responses](/integrations/general#error-responses).
        ::
    ::
::

::collapsible{name="code example"}
    ::code-group
    ```typescript [Typescript Express]
    import { Family } from '../models/Family'

    app.get('/churnkey/families/:id', async (req, res) => {
        const family = await db.findFamilyById(req.params.id)
        if (!family) {
            return res.status(404).send({ code: 404, message: 'Family not found' })
        }
        res.send(new Family(family))
    })
    ```
    ::
::

### List :badge{label="Required" color="green"}
`GET /churnkey/families`

This endpoint fetches a list of families from your database. You should find families in your database (with pagination), map them to the `Family` model and return a paginated list.

[Learn more about pagination](/integrations/general#pagination).

::collapsible{name="query parameters"}
  :field-schema{schema="/types/pagination-query.type"}
::
::collapsible{name="response"}
  :field-schema{schema="/types/pagination-response.type"}
::

::collapsible{name="code example"}
    ::code-group
    ```typescript [Typescript Express]
    import { Family } from '../models/Family'

    app.get('/churnkey/families', async (req, res) => {
        const limit = Number.parseInt(req.query.limit)
        const offset = Number.parseInt(req.query.cursor) 
        const families = await db.findFamilies({ limit, offset })
        res.send({
            data: families.map(c => new Family(c)),
            next: families.length === limit ? offset + limit : undefined
        })
    })
    ```
    ::
::


## Webhooks
Coming soon.