> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved Shortlists

> Save, reopen, update, and delete your creator selections through the REST API.

Keep a campaign brief, selected Instagram profiles, and notes under your API account or OAuth user.

| Before you start | Details |
| - | - |
| Auth | API key or OAuth; anonymous x402/MPP requests have no saved workspace |
| Cost | No credits for saved-shortlist operations; creator lookups and scoring are billed separately |
| Capacity | Up to 100 lists per owner; 1–8 distinct Instagram profile references per list |
| Text limits | Name: 80 characters; brief: 500; notes: 2,000 |
| Request limits | 60 saved-work requests/minute and 600/hour per owner; honor `Retry-After` on `429` |

API keys belonging to the same API account share its lists. OAuth lists belong to the linked user and persist across reconnections. API-key lists and OAuth-user lists are separate workspaces; switching authentication does not transfer a list.

## Create a list

Use selected profile usernames from your own lookup or expanded creator results. Saved profiles contain `platform` and `username`, rather than creator IDs or scores.

This fictional example illustrates the request:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  'https://api.influship.com/v1/shortlists' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Home fitness launch",
    "brief": "Practical home-workout educators for a resistance-band campaign",
    "profiles": [{"platform": "instagram", "username": "alexrivera.fit"}],
    "notes": "Review recent tutorials and evidence before outreach."
  }' -o shortlist.json
```

The response wraps your list in `data`. Keep the returned `id` and `version`:

```json theme={null}
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Home fitness launch",
    "brief": "Practical home-workout educators for a resistance-band campaign",
    "profiles": [{"platform": "instagram", "username": "alexrivera.fit"}],
    "notes": "Review recent tutorials and evidence before outreach.",
    "version": 1,
    "created_at": "2026-10-05T12:00:00Z",
    "updated_at": "2026-10-05T12:00:00Z"
  }
}
```

Creating a list omits both `id` and `expected_version`. A second create request is a separate list; do not blindly retry a create after an ambiguous network failure. List your saved work and check what was created first.

## Reopen and list

Set `SHORTLIST_ID` to the ID returned by your create request. These commands use `jq`:

```bash theme={null}
SHORTLIST_ID=$(jq -er '.data.id' shortlist.json)
curl --fail-with-body --silent --show-error \
  "https://api.influship.com/v1/shortlists/$SHORTLIST_ID" \
  -H "X-API-Key: $INFLUSHIP_API_KEY" -o shortlist.json

curl --fail-with-body --silent --show-error \
  'https://api.influship.com/v1/shortlists' \
  -H "X-API-Key: $INFLUSHIP_API_KEY"
```

Listing returns `{ "data": [...] }`, newest updated first. Saved-work reads require the same owner. A `404` means the list is unavailable to that owner; check the ID and authentication method.

## Update with the current version

POST the complete editable list to the same `/v1/shortlists` endpoint, adding its `id` and current `expected_version`. This replaces the editable fields; it is not a partial patch.

```bash theme={null}
jq '.data | {id, expected_version: .version, name, brief, profiles,
  notes: "Recent content reviewed; confirm availability before outreach."}' \
  shortlist.json > shortlist-update.json

curl --fail-with-body --silent --show-error \
  'https://api.influship.com/v1/shortlists' \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @shortlist-update.json -o shortlist-updated.json
```

Read the newly returned `version` before another change. If another editor has changed the list, the API returns `422 validation_error`. Reopen it, review the latest contents, merge your intended changes, and submit that version. Do not automatically overwrite it by fetching a new version and replaying stale content.

## Delete deliberately

Deletion permanently removes the list, brief, and notes. It does not delete creator profiles. Ask the user of your application to confirm deletion before sending this request.

After reopening the list, send `POST /v1/shortlists/{id}/delete` with `{ "expected_version": <current version> }`. Success returns `{ "data": { "deleted": true, "id": "..." } }`. A stale version returns `422`; reopen and confirm again before attempting deletion.

## Reopen creator evidence

Your shortlist keeps selected profile references, your campaign brief, and review notes together. Use [profile lookup](/concepts/creators-vs-profiles) to retrieve the latest stored metrics and contact details, or [campaign scoring](/cookbook/score-campaign-fit) to evaluate fit as your brief evolves. Save your review decisions in the list's notes.

The [Shortlists reference](/api-reference/shortlists/save-or-update-your-creator-shortlist) defines request and response fields. For general recovery, see [Error Handling](/guides/error-handling).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.