client.lists

Create Lists, manage their members, and follow import operations.

Create client by following Install and configure. The examples use listId, operationId and memberId values saved from earlier responses. The @reverse-contact/sdk package exports Body, Data, Query and the other types used in the signatures.

JSON responses contain data and optional quotas and metadata. They also include the original response, with its body already read. See First call for response handling.

HTTP errors use the APIError subclasses and retry rules: BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError, NotFoundError, ConflictError, GoneError, UnprocessableEntityError, RateLimitError, DailyLimitError, KeyCreditLimitError, UnavailableForLegalReasonsError and InternalServerError, according to the API response. Other statuses use APIError.

list()

client.lists.list(
  params?: Query<"listLists">,
  options?: RequestOptions
): Promise<Page<Data<"listLists">["items"][number], undefined>>

Parameters

Returns

A Page with results in data and pagination through nextCursor, hasNextPage() and getNextPage(). The page also includes optional quotas and metadata, and the original response.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const page = await client.lists.list({ perPage: 20 });
for (const list of page.data) console.log(list.id, list.name);

create()

The SDK generates an Idempotency-Key if you omit it and reuses the key on automatic retries. Save your own key if you need to repeat the request after a restart.

client.lists.create(
  params: Body<"createList">,
  options?: IdempotentRequestOptions
): Promise<Result<Data<"createList">>>

Parameters

Returns

A response with the new List in data. Save data.id for later operations.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const created = await client.lists.create(
  { name: "Prospects", entity: "persons" },
  { idempotencyKey: "prospects-2026-11-04" }
);
console.log(created.data.id);

retrieve()

client.lists.retrieve(
  listId: string,
  params?: Query<"getList">,
  options?: RequestOptions
): Promise<Result<Data<"getList">>>

Parameters

Returns

A response envelope with List details, data.members and data.nextCursor. This method does not return a Page object.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.retrieve(listId, { kind: "all", perPage: 100 });
console.log(result.data.members, result.data.nextCursor);

delete()

client.lists.delete(
  listId: string,
  options?: RequestOptions
): Promise<Result<Data<"deleteList">>>

Parameters

Returns

A response envelope containing the deletion acknowledgement in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.delete(listId);
console.log(result.data);

importSignals()

Send signals or sourceUrl, not both. The SDK generates operationId when omitted. Keep your own operation UUID to resume after a restart. Inspect clientAction and nextStep before resending. You must set maxCredits when you request data families and the worst-case cost of the operation exceeds 25 credits.

client.lists.importSignals(
  listId: string,
  params: Body<"importListSignals">,
  options?: RequestOptions
): Promise<Result<Data<"importListSignals">>>

Parameters

Returns

An operation acknowledgement in data, including operationId and pollUrl. Call client.lists.operations.wait(listId, operationId) to follow progress. See Lists and Bulk enrichment.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const imported = await client.lists.importSignals(listId, {
  signals: [{ email: "jane@acme.com", externalId: "crm-001" }],
  families: ["contact_email"],
  maxCredits: 100
});
console.log("Save operation id:", imported.data.operationId);
const progress = await client.lists.operations.wait(listId, imported.data.operationId);
console.log(progress.data.clientAction, progress.data.nextStep);

export()

client.lists.export(
  listId: string,
  options?: RequestOptions
): Promise<string>

Parameters

Returns

A CSV string, not a JSON response envelope.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options.

Example

const csv = await client.lists.export(listId);
console.log(csv);

listAll()

client.lists.listAll(
  params?: Query<"listLists">,
  options?: ListIteratorOptions
): AsyncGenerator<Data<"listLists">["items"][number], void, unknown>

Parameters

Returns

An AsyncGenerator of individual results. The iterator requests pages as needed. A repeated cursor raises ReverseContactError.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. ReverseContactError also reports invalid perPage or maxResults values and repeated cursors.

Example

for await (const list of client.lists.listAll()) {
  console.log(list.id, list.name);
}

members.list()

client.lists.members.list(
  listId: string,
  params?: Query<"listListMembers">,
  options?: RequestOptions
): Promise<Page<Data<"listListMembers">["items"][number], undefined>>

Parameters

Returns

A Page with results in data and pagination through nextCursor, hasNextPage() and getNextPage(). The page also includes optional quotas and metadata, and the original response. Member pages also expose memberCount, pendingIntakeCount and extras.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const page = await client.lists.members.list(listId, { kind: "members", perPage: 100 });
console.log(page.data, page.memberCount, page.pendingIntakeCount);

members.add()

Add up to 1,000 Signals. If any Signal is invalid, the API rejects the whole request before charging. error.details.signalIndex identifies the invalid entry.

client.lists.members.add(
  listId: string,
  params: Body<"addListMembers">,
  options?: RequestOptions
): Promise<Result<Data<"addListMembers">>>

Parameters

Returns

A response with the outcome for each Signal in data. See the endpoint response structure for member and Pending Intake results.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.members.add(listId, {
  signals: [{ email: "jane@acme.com", externalId: "crm-001" }]
});
console.log(result.data);

members.remove()

Send the member or Pending Intake ids to remove. The SDK sends the JSON body with DELETE.

client.lists.members.remove(
  listId: string,
  params: Body<"removeListMembers">,
  options?: RequestOptions
): Promise<Result<Data<"removeListMembers">>>

Parameters

Returns

A response envelope with the removal result in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.members.remove(listId, { memberIds: [memberId] });
console.log(result.data);

members.listAll()

client.lists.members.listAll(
  listId: string,
  params?: Query<"listListMembers">,
  options?: ListIteratorOptions
): AsyncGenerator<Data<"listListMembers">["items"][number], void, unknown>

Parameters

Returns

An AsyncGenerator of individual results. The iterator requests pages as needed. A repeated cursor raises ReverseContactError.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. ReverseContactError also reports invalid perPage or maxResults values and repeated cursors.

Example

for await (const member of client.lists.members.listAll(listId, { kind: "members" })) {
  console.log(member);
}

operations.retrieve()

Use rows: "true" to include a page of line results. perPage and cursor require rows: "true".

client.lists.operations.retrieve(
  listId: string,
  operationId: string,
  params?: Query<"getListOperation">,
  options?: RequestOptions
): Promise<Result<Data<"getListOperation">>>

Parameters

Returns

Result<ListOperation> with progress, clientAction, stopReason and nextStep in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.operations.retrieve(listId, operationId, { rows: "true", wait: 20 });
console.log(result.data.clientAction, result.data.nextStep);

operations.cancel()

Request cancellation of this List import. Lines that have not started are not charged.

client.lists.operations.cancel(
  listId: string,
  operationId: string,
  options?: RequestOptions
): Promise<Result<Data<"cancelListOperation">>>

Parameters

Returns

A response envelope with the operation cancellation result in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.lists.operations.cancel(listId, operationId);
console.log(result.data);

operations.wait()

Follow clientAction, not just status. The SDK polls on poll and returns on done, resume or reconcile. Inspect stopReason and nextStep. The SDK never replays an operation that needs reconciliation.

client.lists.operations.wait(
  listId: string,
  operationId: string,
  options?: WaitOptions<ListOperation>
): Promise<Result<ListOperation>>

Parameters

Returns

Result<ListOperation> when clientAction becomes done, resume or reconcile. A pause or unsuccessful operation does not by itself raise JobFailedError.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. JobTimeoutError means the overall wait deadline has expired. An unsuccessful terminal state does not raise JobFailedError. An unknown clientAction raises ReverseContactError.

Example

const result = await client.lists.operations.wait(listId, operationId, {
  timeout: 30 * 60 * 1000,
  onPoll: snapshot => { console.log(snapshot.data.status); }
});
console.log(result.data.clientAction, result.data.nextStep);

Related guides

Lists and Bulk enrichment, Timeouts and cancellation. Return to the TypeScript SDK overview.