Saved Shortlists

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:

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:

{
  "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:

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.

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 to retrieve the latest stored metrics and contact details, or campaign scoring to evaluate fit as your brief evolves. Save your review decisions in the list’s notes. The Shortlists reference defines request and response fields. For general recovery, see Error Handling.

Start building

Find and evaluate creators

Research and save

Apps and workflows

Live platform data

Connect your tools

Operate your integration

Create a list

Reopen and list

Update with the current version

Delete deliberately

Reopen creator evidence

​Create a list

​Reopen and list

​Update with the current version

​Delete deliberately

​Reopen creator evidence

Create a list

Reopen and list

Update with the current version

Delete deliberately

Reopen creator evidence