Skip to main content
The connections module reads and manages a user’s mutual connections (bidirectional relationships, similar to “friends”). Use it to list established connections, inspect pending requests, and accept, decline, or remove connections.
Every function acts on behalf of a named user. Pass that user’s Sublay ID as userId — your service key performs the operation as that user.
To send a connection request, check a connection’s status, or remove a connection by the other user’s ID, use the nested routes on the users module (requestConnection, fetchConnectionStatus, removeConnectionByUserId), which take an actingUserId.

​
fetchConnections

Fetches a paginated list of a user’s established (mutual) connections.
​
userId
string
required
The Sublay user ID whose connections to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
​
query
string
Optional search term. Filters the list to connections whose connected user’s username or name contains this text (case-insensitive). When omitted, no filtering is applied.
​
searchFields
string
Restricts which field query matches against — username or name. When omitted, query matches either field.
Returns — Promise<PaginatedResponse<EstablishedConnection>>

​
fetchConnectionsCount

Returns the number of established connections for a user.
​
userId
string
required
The Sublay user ID.
Returns — Promise<{ count: number }>

​
fetchSentPendingConnections

Returns a paginated list of connection requests the user has sent that are still pending.
​
userId
string
required
The Sublay user ID whose sent requests to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<PendingConnection>>

​
fetchReceivedPendingConnections

Returns a paginated list of pending connection requests the user has received.
​
userId
string
required
The Sublay user ID whose received requests to fetch.
​
page
number
Page number (1-indexed). Defaults to 1.
​
limit
number
Results per page. Defaults to 20.
Returns — Promise<PaginatedResponse<PendingConnection>>

​
acceptConnection

Accepts a pending connection request received by the user.
​
connectionId
string
required
The ID of the pending connection request to accept.
​
userId
string
required
The Sublay user ID accepting the request (the recipient).
Returns — Promise<ConnectionActionResponse> — { id, status, createdAt?, respondedAt? }

​
declineConnection

Declines a pending connection request received by the user.
​
connectionId
string
required
The ID of the pending connection request to decline.
​
userId
string
required
The Sublay user ID declining the request (the recipient).
Returns — Promise<ConnectionActionResponse> — { id, status, createdAt?, respondedAt? }

​
removeConnection

Removes an established connection (or withdraws a pending request) by its connection ID.
​
connectionId
string
required
The connection ID to remove.
​
userId
string
required
The Sublay user ID on whose behalf the connection is removed.
Returns — Promise<void>