# Creators

> Creators you work with, and a partner's roster.

Source: https://www.onlucra.com/docs/api-creators

An account sees the creators it works with: creators in its programs and, for a partner, the creators on its roster.

## List creators

`GET /v1/creators` filters by `q` (a name, email or handle), `status`, `program`, `relationship` and `visibility`:

```ts
const { data: page } = await lucra.creators.list({
  query: { program: "prog_00lhuAJjQgdtNt5WnqTBc95", q: "sam" },
})
```

## Add a creator to your roster

A partner adds a creator by email with `POST /v1/creators`:

```ts
const { data: creator } = await lucra.creators.create({
  body: { email: "sam@example.com", name: "Sam Rivera", visibility: "private" },
})
```

What happens next depends on the creator:

- **New to Lucra**: they get an account to claim later, and you can act for them right away with `Lucra-Account: crtr_…`.
- **Already on Lucra, or left your roster before**: they're emailed an invite and show as `invited`. You can act for them once they accept.
- **Already on your roster**: you get them back with `200`.

A creator can be on one partner's roster at a time.

## Manage the roster

Choose which client brands a roster creator works with by sending the full list. A brand left out stops working with them:

```ts
await lucra.creators.update({
  path: { id: "crtr_026UYfiw1Y6OvUpuKWiOpeL" },
  body: { brands: ["acct_07RodMW6bE7BBO6e1I3UzSi"] },
})
```

Send `{ "status": "removed" }` to take a creator off the roster, or `takeRate` to set your cut of their pay.

## Edit a creator's profile

Acting as the creator (`Lucra-Account: crtr_…`), `PATCH /v1/creators/:id` with their own ID edits their `name`, `bio`, `interests` and location.

- **Location**: search the city catalog with `GET /v1/cities?q=…`, then send the picked city as `locationDetails`, with its `displayName` as `location`.
- **Photo**: send `profilePicture`, a `profile_picture` [file](https://www.onlucra.com/docs/api-files) uploaded as the creator. Or send `pictureFrom: "instagram"` or `"tiktok"` to use a connected account's photo.

## Visibility

`private` hides a creator from brands browsing Explore; `network` lets any brand find them. Either way, they can apply to programs open to the network.

## Getting paid

A creator is paid to their own Stripe balance once `payouts.identity.status` is `verified`. Until then they keep earning. To finish setup, send them to the URL from `POST /v1/connections` with `provider: "stripe"`. The [`creator.payouts_updated` webhook](https://www.onlucra.com/docs/webhooks) tells you when their setup changes.

## Endpoints

- `GET /v1/creators` (read, SDK `lucra.creators.list`): List the account's creators and, for a partner, its roster
- `GET /v1/creators/:id` (read, SDK `lucra.creators.retrieve`): Get one of the account's creators, or, as a creator, yourself
- `POST /v1/creators` (write, SDK `lucra.creators.create`): Add a creator to a partner's roster; one already on it is returned with 200, and one with a Lucra account is invited (status invited) until they accept
- `PATCH /v1/creators/:id` (write, SDK `lucra.creators.update`): Update a creator: a brand's labels and status, a partner's roster creator, or, as a creator, your own profile
- `GET /v1/cities` (read, SDK `lucra.cities.list`): Search cities by name, exact matches first