--- title: "Get a List" method: GET path: "/v2/lists/{listId}" tags: ["Lists"] --- # Get a List `GET /v2/lists/{listId}` ## Request - Base URL: `https://api.reversecontact.com` - URL: `https://api.reversecontact.com/v2/lists/{listId}` - Auth: HTTP bearer Returns the List and one page of its rows: List Members (kind member) and Not found lines kept as Pending Intake (kind pending), ordered by added date. Pass nextCursor back as cursor, with the same kind, for the next page; a malformed cursor, or one sent with other filters, is refused with 400. Credits: 0. ## Path parameters - `listId` string, uuid, required: List id ## Query parameters - `perPage` integer: Rows per page (1-1000, default 100) - `cursor` string: Opaque cursor: the nextCursor of the previous page, sent with the same filters. A malformed cursor, or one sent with other filters, is refused with 400. - `kind` 'all' | 'members' | 'pending': Row query. all mixes List Members and Pending Intake by added_at; members or pending restricts the server read. ## Response `200` List and one page of rows - object - `success` true, required - `data` object, required - `list` object, required - `id` string, uuid, required: List id - `name` string, required: List name - `entity` 'persons' | 'companies', required - `memberCount` integer, required: List Members - `pendingIntakeCount` integer, required: Not found lines kept as Pending Intake - `revision` integer: Revision, raised by every member change - `archivedAt` string, date-time, nullable: Archive date - `createdAt` string, date-time: Creation date - `updatedAt` string, date-time: Last update date - `originQuery` object, nullable - `originLastFind` object, nullable - `members` union[], required - union - object - `kind` 'member', required - `id` string, uuid, required: Member id - `entityId` string, required: Person or company id - `linkedinUrl` string, nullable: Social URL - `status` string: identified, profiled or enriched - `fields` object: Stored fields, as the List shows them: a value typed over a cell in the dashboard replaces the enriched one - `addedAt` string, date-time: Date the member was added - `families` object: Per data family state: profile, company, contactEmail, contactPhone. A contact typed in the dashboard reads found with source manual - `externalId` string, nullable, required: Your identifier for this member, null when none was sent - object - `kind` 'pending' - `id` string, uuid: Pending Intake id - `signal` object: The Signal as sent - `source` 'file' | 'paste' - `addedAt` string, date-time: Date the line was kept - `fields` object: Values typed over the row in the dashboard, by column (name, headline, company, url, contactEmail...) - `nextCursor` string, nullable, required: Cursor of the next page - `error` unknown, required - `quotas` V2Quotas, required - `creditsConsumed` number, required: Credits used for this request after pricing resolution - `workspace` object, required - `id` string, required: Workspace identifier - `credits` V2Credits, required - `total` number, required: Total credits in your plan - `used` number, required: Credits consumed so far - `left` number, required: Remaining credits - `hasUnlimitedCredits` boolean, required: Whether workspace credits are unlimited - `allowDailyOvercost` boolean, required: Whether the workspace may exceed its daily cap (Enterprise only) - `dailyLimit` V2LimitInfo - `limit` integer, required: Maximum allowed in the window - `used` integer, required: Amount used in the window - `left` integer, required: Remaining in the window - `nextReset` string, required: When the window resets (ISO 8601) - `minuteRateLimit` V2LimitInfo, required - `limit` integer, required: Maximum allowed in the window - `used` integer, required: Amount used in the window - `left` integer, required: Remaining in the window - `nextReset` string, required: When the window resets (ISO 8601) - `key` object, nullable, required - `id` string, required: API key identifier - `dailyLimit` V2LimitInfo - `limit` integer, required: Maximum allowed in the window - `used` integer, required: Amount used in the window - `left` integer, required: Remaining in the window - `nextReset` string, required: When the window resets (ISO 8601) - `minuteRateLimit` V2LimitInfo, required - `limit` integer, required: Maximum allowed in the window - `used` integer, required: Amount used in the window - `left` integer, required: Remaining in the window - `nextReset` string, required: When the window resets (ISO 8601) - `creditLimits` object, required: Credit limits set on this API key. Each is null when the key has no such limit. - `daily` V2KeyCreditLimit, required - `limit` number, required: Credits this key may spend in the period - `used` number, required: Credits this key spent in the period, this request included - `left` number, required: Credits this key may still spend in the period - `nextReset` string, nullable, required: When the period resets (ISO 8601): 00:00 UTC for the daily limit, the 1st of next month at 00:00 UTC for the monthly limit, null for the total limit - `monthly` V2KeyCreditLimit, required - `limit` number, required: Credits this key may spend in the period - `used` number, required: Credits this key spent in the period, this request included - `left` number, required: Credits this key may still spend in the period - `nextReset` string, nullable, required: When the period resets (ISO 8601): 00:00 UTC for the daily limit, the 1st of next month at 00:00 UTC for the monthly limit, null for the total limit - `total` V2KeyCreditLimit, required - `limit` number, required: Credits this key may spend in the period - `used` number, required: Credits this key spent in the period, this request included - `left` number, required: Credits this key may still spend in the period - `nextReset` string, nullable, required: When the period resets (ISO 8601): 00:00 UTC for the daily limit, the 1st of next month at 00:00 UTC for the monthly limit, null for the total limit - `metadata` V2Metadata, required - `requestId` string, required: Unique identifier for this request - `executionTimeMs` integer, required: Total execution time in milliseconds - `updatedAt` string: Last upstream update timestamp (ISO 8601). Present only when available. ## Other responses - `400`: Invalid JSON body or endpoint-specific business validation - `401`: Missing or invalid API key or OAuth access token - `402`: No credits left. Purchase more to continue. - `403`: Forbidden: the API key lacks permission for this endpoint, or reached its total credit limit (KEY_CREDIT_LIMIT_REACHED, no reset: raise or reset the limit) - `404`: Data not found - `422`: Schema or validation error, unresolved internal id, or disposable email domain - `429`: Rate limit exceeded, or the API key reached its daily or monthly credit limit (KEY_CREDIT_LIMIT_REACHED). Wait error.details.retryAfter seconds, then retry. The response carries no quotas object. - `451`: Data subject blocked. The profile has been removed per GDPR/CCPA data subject request. --- [API](https://skmtc.dev/scrapin/apis/reverse-contact-api.md) - [All operations](https://skmtc.dev/scrapin/apis/reverse-contact-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scrapin/apis/reverse-contact-api/revisions/7d02242af2a9?raw)