Connections API

Connections API lets users build relationships like "following" or "friendship", boosting engagement and retention.

Connections API (part of the Audience API) is a high-throughput public RESTful API that enables social UX mechanics, such as one-way "following" or mutual "friendship." It allows users to form meaningful relationships within Interactive Experiences, share progress, collaborate and compete with each other, thus increasing app usage, engagement and retention.

All methods of Connections API require authentication.

GET requests are paginated to allow for potential celebrity mass-following.

Following

Following is a not-necessarily-mutual form of social engagement, where one user may follow another without requiring their explicit approval. API methods below allow a client app to retrieve the lists of "followees" and "followers" for a user, as well as manage their following.

List users the specified user is following

get

/api/connections/following

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

offsetinteger · default: 0

The number of items to skip before starting to collect the result set.

limitinteger · min: 1 · default: 100

The maximum number of items to return.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections/following' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "avatar": "text"
    }
  ],
  "meta": {
    "total": 20,
    "offset": 0,
    "limit": 100
  }
}

Paginated list of users

Follow a user

post

/api/connections/following

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

Body

target_user_idstring · uuidrequired

UUID of the target user.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://your.space.domain/api/connections/following' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "target_user_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

201

401

201

No body

User followed successfully.

Unfollow a user

delete

/api/connections/following/{target_user_id}

Authorizations

Path parameters

target_user_idstring · uuidrequired

UUID of the target user.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://your.space.domain/api/connections/following/{target_user_id}' \
  --header 'Authorization: Bearer JWT'

204

401

204

No body

User unfollowed successfully.

List users following the specified user

get

/api/connections/followers

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

offsetinteger · default: 0

The number of items to skip before starting to collect the result set.

limitinteger · min: 1 · default: 100

The maximum number of items to return.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections/followers' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "avatar": "text"
    }
  ],
  "meta": {
    "total": 20,
    "offset": 0,
    "limit": 100
  }
}

Paginated list of users

Friendship

Following is a mutual form of social engagement, where one user makes a friendship request, that must be approved by the other user before the relationship is established. The API methods below allow a client app to retrieve a user's active friends, sent and received friend requests, and manage these lists.

List friends of the specified user

get

/api/connections/friends

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

offsetinteger · default: 0

The number of items to skip before starting to collect the result set.

limitinteger · min: 1 · default: 100

The maximum number of items to return.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections/friends' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "avatar": "text"
    }
  ],
  "meta": {
    "total": 20,
    "offset": 0,
    "limit": 100
  }
}

Paginated list of users

List sent friend requests

get

/api/connections/friends/requests/sent

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

offsetinteger · default: 0

The number of items to skip before starting to collect the result set.

limitinteger · min: 1 · default: 100

The maximum number of items to return.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections/friends/requests/sent' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "avatar": "text"
    }
  ],
  "meta": {
    "total": 20,
    "offset": 0,
    "limit": 100
  }
}

Paginated list of users

Send a friend request

post

/api/connections/friends/requests/sent

Authorizations

Body

target_user_idstring · uuidrequired

UUID of the target user.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://your.space.domain/api/connections/friends/requests/sent' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "target_user_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

201

401

201

No body

Friend request sent successfully.

Delete previously sent friend request

delete

/api/connections/friends/requests/sent/{target_user_id}

Authorizations

Path parameters

target_user_idstring · uuidrequired

UUID of the target user.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://your.space.domain/api/connections/friends/requests/sent/{target_user_id}' \
  --header 'Authorization: Bearer JWT'

204

401

204

No body

Friend request deleted successfully.

List received friend requests

get

/api/connections/friends/requests/received

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

offsetinteger · default: 0

The number of items to skip before starting to collect the result set.

limitinteger · min: 1 · default: 100

The maximum number of items to return.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections/friends/requests/received' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": [
    {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "avatar": "text"
    }
  ],
  "meta": {
    "total": 20,
    "offset": 0,
    "limit": 100
  }
}

Paginated list of users

Approve a received friend request

patch

/api/connections/friends/requests/received/{target_user_id}

Authorizations

Path parameters

target_user_idstring · uuidrequired

UUID of the target user.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://your.space.domain/api/connections/friends/requests/received/{target_user_id}' \
  --header 'Authorization: Bearer JWT'

200

401

200

No body

Friend request approved successfully.

Stats

Get an overview of the user's connections

get

/api/connections

Authorizations

Query parameters

user_idstring · UUID

UUID of the user. Defaults to the current user.

user_idsstring

Comma-separated list of UUIDs of the users. Enables batch query mode.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://your.space.domain/api/connections' \
  --header 'Authorization: Bearer JWT'

200

401

200

{
  "message": "OK",
  "data": {
    "following_count": 18,
    "followers_count": 34,
    "friends_count": 14,
    "requests_received_count": 7,
    "requests_sent_count": 3
  }
}

Specified user's connection counts