Saved lists

This workspace's saved lists

Scopes (any one): dsp.entities.read, dsp.search.read

Use it when you want to keep records you found, such as a target account list or a set of patents to review, and come back to them later from the dashboard, an integration or an agent. Outcome: named lists that store record ids and return each record's current data whenever you read them.

• Free. No list route charges credits, including reading the records back.
• Shared with the workspace. A list belongs to your workspace, not to one person or key: everyone in the workspace sees the same lists.
• Either credential. Every route accepts an API key or a dashboard session holding dsp.search.read or dsp.entities.read.

Your lists#

Lists come back most recently updated first.

• saved_items is the number of distinct records saved across all of the workspace's lists. A record in two lists counts once.
• saved_items_cap is the most a workspace can save, or null when no cap applies. Only workspaces that have not bought credits can have a cap; see The saved-items cap.
• field_tier says how much of each record reading the items returns: free or unlocked.

Create a list#

curl -X POST "https://api.sproutsdata.ai/v1/lists" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Q4 target accounts"
     }'

name is 1 to 120 characters; spaces at either end are trimmed. Returns 201 Created with the new list. Its id (a UUID) is the list_id every other route takes. created_by is the user who created it, or null when an API key did.

Rename a list#

curl -X PATCH "https://api.sproutsdata.ai/v1/lists/{list_id}" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q4 target accounts (EMEA)" }'

Same rules for name as on create. Returns the updated list.

Delete a list#

curl -X DELETE "https://api.sproutsdata.ai/v1/lists/{list_id}" \
  -H "X-API-Key: $SPROUTS_API_KEY"

Returns 204 No Content. A deleted list is gone for the whole workspace.

Add items#

curl -X POST "https://api.sproutsdata.ai/v1/lists/{list_id}/items" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "items": [
         {
           "entity_category": "company",
           "entity_id": "stripe.com"
         },
         {
           "entity_category": "person",
           "entity_id": "https://www.linkedin.com/in/example-person"
         }
       ]
     }'

Each item is an entity_category and that record's natural id, the one it can be looked up by later:

Ids are normalised on the way in: a domain is lower-cased and loses its scheme and www., and a LinkedIn URL is reduced to linkedin.com/in/<slug>. So https://www.Stripe.com/ and stripe.com are the same item.

Up to 500 items per request; more is a 422. Duplicates in one request are counted once.

• added: items newly saved to this list.
• already_present: items the list already held. Adding them again changes nothing.
• suppressed: items refused because the record is on the platform's Do-Not-Contact list. A suppressed record is never added to a list and never returned from one, and suppressing a record removes it from every list it is in.

The saved-items cap

A workspace that has not bought credits can be capped on how many distinct records it saves across all its lists. GET /v1/lists reports the cap as saved_items_cap; null means none applies. Workspaces that have bought credits are never capped.

An add that would take the workspace past the cap is refused as a whole with 409 lists.item_cap_reached, and nothing is added. extra carries the numbers:

{
  "type": "https://dashboard.sproutsdata.ai/errors/lists-item-cap-reached",
  "title": "Saved-items limit reached",
  "status": 409,
  "code": "lists.item_cap_reached",
  "detail": "This workspace can save 250 items; 245 are saved and 10 would be added.",
  "extra": { "cap": 250, "saved": 245, "adding": 10 },
  "request_id": "..."
}

A record already saved in another of the workspace's lists does not count again, so adding it never hits the cap.

Remove items#

curl -X DELETE "https://api.sproutsdata.ai/v1/lists/{list_id}/items" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "items": [
         {
           "entity_category": "company",
           "entity_id": "stripe.com"
         }
       ]
     }'

Same item shape and the same 500-per-request limit as adding. removed is how many items were taken out; an item the list did not hold is ignored.

Read the items#

curl "https://api.sproutsdata.ai/v1/lists/{list_id}/items?limit=25" \
  -H "X-API-Key: $SPROUTS_API_KEY"

The list's items, most recently added first, each with the record's current data read when you ask. Reading is never charged.

• Paging: limit is 1 to 100 (default 25). Pass next_cursor back as cursor for the next page; it is null on the last page. A cursor this route did not issue is 422 pagination.cursor_invalid.
• field_tier decides how much of each record you get. free returns the fields shown on a result card in the dashboard (for a company: name, domain, industry, size, location, funding and similar). unlocked, for a workspace that has bought credits, returns the full record.
• available: false means the record could not be read this time. The item stays in the list. unavailable_reason says why: not_found (the index no longer resolves that id) or retrieval_unavailable (the lookup failed; try again later).

CSV export (not switched on yet)#

Two routes will export records as CSV: POST /v1/lists/{list_id}/export for a whole list, and POST /v1/search/export for selected search results. They are not switched on yet: today both answer 404 export.not_enabled.

Errors#

• 404 lists.not_found: no list with that id in this workspace. A list id from another workspace answers the same way.
• 503 lists.unavailable: saved lists could not be reached. Nothing was changed; retry shortly.