Skip to content

Users API

Users API allows to work with users within the application and manage user’s information - add, update and/or remove. To work with user’s data, session with user authorisation should be created initially.

Users model

A Users model captures certain characteristics about an individual user or group of users registered in the application.

Field nameDescription
idUser’s identifier on server
loginUser’s login on server. Usually login OR email is required to log in into the application
passwordUser’s password sets for his user’s account. Required for log in process
emailUser’s email. Usually login OR email is required to log in into the application
external_user_idID of User in external system (Deprecated)
external_idID of User in external system
facebook_idID of User in Facebook
twitter_idID of User in Twitter
full_nameUser’s full name
phoneUser’s phone number
websiteUser’s Website address
custom_dataUser’s additional info (if any)
user_tagsTag(s) added for User. Several tags comma separated can be added. Same tags can be used for any number of users
avatarAn ID of the graphical representation of the user
blob_idDeprecated - ‘avatar’ field should be used instead. ID of associated blob. Note: blob should be created before
created_atDate and time when User was registered in the application. System creates this parameter automatically
updated_atSystem creates / updates this parameter automatically when user’s data are updated
last_request_atDate and time where the latest request was sent. System creates this parameter automatically
timezoneMinutes UTC offset

User Sign Up

To have an ability to work with user’s data, user should be registered in the application. To register a new user in the application, at least login / email and password should be specified. Other parameters are optional and can be added later.

Endpoint
POST https://api.connectycube.com/users
Headers
Parameters
ParameterRequiredDescription
user[login]YesUser’s login. Only login OR email is required
user[password]YesUser’s password
user[email]YesUser’s email. Only login OR email is required
user[external_user_id]Optional (Deprecated)ID of User in external system
user[external_id]OptionalID of User in external system
user[facebook_id]OptionalID of User in Facebook
user[twitter_id]OptionalID of User in Twitter
user[full_name]OptionalFull name
user[phone]OptionalPhone number
user[website]OptionalWebsite address
user[custom_data]OptionalUser’s additional info (if any)
user[timezone]OptionalMinutes UTC offset
user[tag_list]OptionalTags added for User. Several tags comma separated can be added. Same tags can be used for any number of users
user[avatar]OptionalThe graphical representation of the user
user[blob_id]OptionalDeprecated - ‘avatar’ field should be used instead. ID of associated blob. Note: blob should be created before
Request example
Terminal window
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-AuthKey: 29WfrNWdvkhmX6V" \
-d '{"user": {"login": "Dacia", "password": "petU4or!", "email": "dacia_k@domain.com", "facebook_id": "91234409", "twitter_id": "83510562734", "full_name": "Dacia Kail ", "phone": "+6110797757", "timezone": 180}}' \
https://api.connectycube.com/users
Response
{
"user":{
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":null,
"external_id":null,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": 180
}
}

Retrieve Users V2

Retrieving users within the application. Query result set can be sorted or / and filtered with defining the number of results to shown per page.

Endpoint
GET https://api.connectycube.com/users/v2
Parameters

Optional parameters to use for data representative.

Pagination

ParameterRequiredDescriptionValue example
offsetNoNumber of users to skip before show. Default = 0offset=50
limitNoNumber of results to show per request. Max = 100, default = 100limit=20

Sort the query result set

TypeDescriptionExample
ascAscendingsort_asc=id
descDescendingsort_desc=created_at

Available fields to filter

FieldTypeApply Type
idintegerstand-alone
loginstringstand-alone
emailstringstand-alone
full_namestringstand-alone
phonestringstand-alone
external_idstringstand-alone
facebook_idstringstand-alone
twitter_idstringstand-alone
user_tagsarray of stringsstand-alone/additional
last_request_atdate (string or timestamp)additional
created_atdate (string or timestamp)additional
updated_atdate (string or timestamp)additional

Operators

OperatorDescriptionValue exampleType
eqequalid=51946primary
inlist of data equalid[in][]=51946&id[in][]=51943primary
start_withmatch string starting with substringfull_name[start_with]=diverprimary
ninlist of data not equaluser_tags[nin][]=vipexclude
gtgreater thanupdated_at[gt]=2019-11-06T09:21:41Zcompare
ltless thancreated_at[lt]=2019-11-06T09:21:41Zcompare
gtegreater than or equallast_request_at[gte]=2017-12-06T09:21:41Zcompare
lteless than or equallast_request_at[lte]=2018-11-06T09:21:41Zcompare

Query need to contain at least one stand-alone field with primary operator
stand-alone field can’t be used with compare operators
start_with operator search for a match at the beginning of the string, this operator automatic set limit = 5, minimum argument length for searching = 4

Examples of valid/invalid query:

  • id=51946 - valid (stand-alone with primary operator)
  • id[in][]=51946&id[in][]=51943&last_request_at[gt]=2018-12-06T09:21:41Z - valid (stand-alone with primary operator and additional with compare operator)
  • user_tags=guest - valid (stand-alone with primary operator)
  • user_tags=guest&created_at[lt]=1690886495 - valid (stand-alone/additional with primary operator and additional with compare operator)
  • login=smith1&phone=6754987345566&user_tags[nin][]=vip&updated_at[lte]=2018-12-06T09:21:41Z - valid (has stand-alone with primary operator)
  • phone=6754987345566&last_request_at=2020-11-09T08:21:41Z - valid (stand-alone with primary operator)
  • full_name[start_with]=hunter&id[nin][]=68647 - valid (stand-alone with primary operator, start_with argument length = 6)
  • login[nin][]=admin19 - invalid (stand-alone only with exclude operator)
  • user_tags[nin][]=guest - invalid (stand-alone/additional only with exclude operator)
  • last_request_at=2017-07-06T11:21:41Z - invalid (additional with primary operator)
  • created_at[gte]=2019-11-06T09:21:41Z - invalid (additional with compare operator)
  • login[start_with]=vip - invalid (stand-alone with primary operator, but start_with argument length = 3)

Example:

Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'id[in][]=52671&id[in][]=51943&phone=5464579797975&last_request_at[gt]=2018-12-06T09:21:41Z&sort_desc=id&limit=10' \
https://api.connectycube.com/users/v2
Response
{
"limit":10,
"skip":0,
"total_entries":1,
"items":[
{
"id":52671,
"full_name":"David Smith",
"email":null,
"login":"smithguest18",
"phone":"5464579797975",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":"2019-12-07T10:21:41Z",
"external_user_id":null,
"external_id":null,
"facebook_id":null,
"twitter_id":null,
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
]
}

Retrieve Users V1 (Deprecated)

Retrieving users within the application. Query result set can be sorted or / and filtered with defining the number of results to shown per page.

To enable this deprecated API go to https://admin.connectycube.com Overview -> Permissions, and uncheck option DISABLE LIST USERS API V1.

App Permissions Permission option

Endpoint
GET https://api.connectycube.com/users
Parameters

Optional parameters to use for data representative.

Pagination

ParameterRequiredDescription
pageNoNumber of page to show. The first page is shown by default
per_pageNoNumber of results to show per page. Default number of results per page - 10, maximum number of results per page - 100

Example:

Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d "per_page=7" \
https://api.connectycube.com/users

Filtering the query result set

  • Parameter to use to filter data - filter[]
  • Filter by - all fields (exclude ‘custom_data’) are allowed to be used as a filter for results
  • Data types:
    • number
    • string
    • date - date format must be yyyy-mm-dd or yyyy.mm.dd)
  • Request format: filter[]={data_type}+{field_to_filter}+[operator]+{value_to_filter}
OperatorDescriptionValue exampleData to return
gtgreater thanfilter[gt]=number+id+gt+51496Users with IDs greater than 51496
ltless thanfilter[lt]=number+id+lt+51946Users with IDs less than specified ID
gegreater than or equalfilter[ge]=number+id+ge+51946Users with IDs greater than or equal to specified ID
leless than or equalfilter[le]=number+id+le+51946Users with IDs less than or equal to specified ID
eqequalfilter[eq]=number+id+eg+51946User with ID equal to specified ID
nenot equalfilter[ne]=number+id+ne+51946Users with IDs not equal to specified ID
betweenbetweenfilter[between]=number+id+between+51941,51959List of users with IDs between the specified range. Range limits should be comma separated
inlist of datafilter[in]=number+id+in+51943,51946Users with the specified IDs

Example:

Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'filter[]=number+id+gt+51946' \
https://api.connectycube.com/users

Sort the query result set

Type of sortDescriptionValue Example
ascsort the query result set in an ascending order by any of the fieldorder=asc+{data_type}+{field}. Example: order=asc+string+login
descsort the query result set in an descending order by any of the fieldorder=desc+{data_type}+{field}. Example: order=desc+integer+facebook_id

Example:

Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'order=desc+string+full_name' \
https://api.connectycube.com/users
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'order=asc+string+login' \
https://api.connectycube.com/users
Response
{
"current_page":1,
"per_page":10,
"total_entries":3,
"items":[
{
"user": {
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":52691165,
"external_id":null,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
},
{
"user": {
"id":51946,
"full_name":"Gabrielle Corcoran",
"email":"gabrielle.corcoran@domain.com",
"login":"gabby",
"phone":"+6192622155",
"website":"http://gabby.com",
"created_at":"2018-12-06T09:29:57Z",
"updated_at":"2018-12-06T09:29:57Z",
"last_request_at":null,
"external_user_id":null,
"external_id":null,
"facebook_id":"95610574",
"twitter_id":null,
"blob_id":null,
"custom_data":"Responsible for signing documents",
"avatar":null,
"user_tags":"vip,accountant",
"timezone": null
}
},
{
"user": {
"id":51943,
"full_name":"Pallavi Purushottam",
"email":"pavallip@domain.com",
"login":"ppavalli",
"phone":"+6138907507",
"website":null,
"created_at":"2018-12-06T09:21:41Z",
"updated_at":"2018-12-06T09:21:41Z",
"last_request_at":null,
"external_user_id":null,
"external_id":null,
"facebook_id":null,
"twitter_id":null,
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":"accountant",
"timezone": null
}
},
]
}

Note: if ‘Allow to retrieve a list of users via API’ is un-ticked, retrieving users is forbidden, error is shown in the response:

{
"errors":{
"base":["Users retrieving forbidden in admin panel, application settings. Setup it here https://admin.connectycube.com/apps/230/service/users/settings"]
}
}

Show User by identifier (Deprecated)

Retrieve information about User stored in the data base by specifying user’s identifier.

Endpoint
GET https://api.connectycube.com/users/{user_id}
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/51946
Response
{
"user":{
"id":51946,
"full_name":"Gabrielle Corcoran",
"email":"gabrielle.corcoran@domain.com",
"login":"gabby",
"phone":"+6192622155",
"website":"http://gabby.com",
"created_at":"2018-12-06T09:29:57Z",
"updated_at":"2018-12-06T09:29:57Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":"95610574",
"twitter_id":null,
"blob_id":null,
"custom_data":"Responsible for signing documents",
"avatar":null,
"user_tags":"vip,accountant",
"timezone": null
}
}

Retrieve User by login (Deprecated)

Retrieve information about User stored in the bata base by specifying user’s login.

Endpoint
GET https://api.connectycube.com/users/by_login
Parameters
ParameterRequiredDescription
loginYesUser’s login to login into the system
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'login=Dacia' \
https://api.connectycube.com/users/by_login
Response
{
"user":{
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":52691165,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
}

Retrieve Users by full name (Deprecated)

Retrieve information about User stored in the data base by specifying user’s full name.

Endpoint
GET https://api.conectycube.com/users/by_full_name
Parameters
ParameterRequiredDescription
full_nameYesFull name of user
pageNoNumber of page to show. The first page is shown by default
per_pageNoNumber of results to show per page. Default number of results per page - 10, maximum number of results per page - 100
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'full_name=Gabrielle%20Corcoran' \
https://api.connectycube.com/users/by_full_name
Response
{
"current_page":1,
"per_page":10,
"total_entries":1,
"items":[
{
"user": {
"id":51946,
"full_name":"Gabrielle Corcoran",
"email":"gabrielle.corcoran@domain.com",
"login":"gabby",
"phone":"+6192622155",
"website":"http://gabby.com",
"created_at":"2018-12-06T09:29:57Z",
"updated_at":"2018-12-06T09:29:57Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":"95610574",
"twitter_id":null,
"blob_id":null,
"custom_data":"Responsible for signing documents",
"avatar":null,
"user_tags":"vip,accountant",
"timezone": null
}
}
]
}

Retrieve User by Facebook identifier (Deprecated)

Retrieve information about User stored in the data base by specifying user’s Facebook identifier. If no Facebook ID is available for User, system will return 404 error.

Endpoint
GET https://api.connectycube.com/users/by_facebook_id
Parameters
ParameterRequiredDescription
facebook_idYesUser’s ID on Facebook
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'facebook_id=95610574' \
https://api.connectycube.com/users/by_facebook_id
Response
{
"user": {
"id":51946,
"full_name":"Gabrielle Corcoran",
"email":"gabrielle.corcoran@domain.com",
"login":"gabby",
"phone":"+6192622155",
"website":"http://gabby.com",
"created_at":"2018-12-06T09:29:57Z",
"updated_at":"2018-12-06T09:29:57Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":"95610574",
"twitter_id":null,
"blob_id":null,
"custom_data":"Responsible for signing documents",
"avatar":null,
"user_tags":"vip,accountant",
"timezone": null
}
}

Retrieve User by Twitter identifier (Deprecated)

Retrieve information about User stored in the data base by specifying user’s Twitter identifier. If no Twitter ID is available for User, system will return 404 error.

Endpoint
GET https://api.connectycube.com/users/by_twitter_id
Parameters
ParameterRequiredDescription
twitter_idYesUser’s ID on Twitter
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'twitter_id=83510562734' \
https://api.connectycube.com/users/by_twitter_id
Response
{
"user": {
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":52691165,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
}

Retrieve User by email (Deprecated)

Retrieve information about User stored in the data base by specifying user’s email.

Endpoint
GET https://api.connectycube.com/users/by_email
Parameters
ParameterRequiredDescription
emailYesUser’s email address
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'email=dacia_k@domain.com' \
https://api.connectycube.com/users/by_email
Response
{
"user": {
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":52691165,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
}

Retrieve Users by tags (Deprecated)

Retrieve information about User(s) stored in the data base by specifying one or more tags added for their profiles. At least one specified tag must match with User’s tags to retrieve User’s information.

Endpoint
GET https://api.connectycube.com/users/by_tags
Parameters
ParamRequiredDescription
tagsYesAPI User tag(s). The maximum number of tags per user: 5. Several tags comma separated can be specified
pageNoPage number of the book of the results that you want to get. Default: 1
per_pageNoThe maximum number of results per page. Min: 1. Max: 100. Default: 10
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'tags=accountant' \
https://api.connectycube.com/users/by_tags
Response
{
"current_page":1,
"per_page":10,
"total_entries":2,
"items":[
{
"user": {
"id":51943,
"full_name":"Pallavi Purushottam",
"email":"pavallip@domain.com",
"login":"ppavalli",
"phone":"+6138907507",
"website":null,
"created_at":"2018-12-06T09:21:41Z",
"updated_at":"2018-12-06T09:21:41Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":null,
"twitter_id":null,
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":"accountant",
"timezone": null
}
},
{
"user": {
"id":51946,
"full_name":"Gabrielle Corcoran",
"email":"gabrielle.corcoran@domain.com",
"login":"gabby",
"phone":"+6192622155",
"website":"http://gabby.com",
"created_at":"2018-12-06T09:29:57Z",
"updated_at":"2018-12-06T09:29:57Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":"95610574",
"twitter_id":null,
"blob_id":null,
"custom_data":"Responsible for signing documents",
"avatar":null,
"user_tags":"vip,accountant",
"timezone": null
}
}
]
}

Retrieve User by external user id (Deprecated)

Retrieve information about User stored in the data base by specifying user’s external User ID.

Endpoint
GET https://api.connectycube.com/users/external/{id}
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/external/52691165
Response
{
"user": {
"id":51941,
"full_name":"Dacia Kail",
"email":"dacia_k@domain.com",
"login":"Dacia",
"phone":"+6110797757",
"website":null,
"created_at":"2018-12-06T09:16:26Z",
"updated_at":"2018-12-06T09:16:26Z",
"last_request_at":null,
"external_user_id":52691165,
"facebook_id":"91234409",
"twitter_id":"83510562734",
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":null,
"timezone": null
}
}

Update User by identifier

Update User’s information stored in the data base by specifying user’s identifier. One or more parameters can be updated at once. System will return the updated data in the response.

Endpoint
PUT https://api.connectycube.com/users/{user_id}
Parameters
ParameterRequiredDescription
user[login]OptionalUser login
user[password]OptionalUser password
user[old_password]OptionalOld user password. Required if new password provided
user[email]OptionalUser email
user[external_user_id]OptionalID of User in external system
user[facebook_id]OptionalID of User in Facebook
user[twitter_id]OptionalID of User in Twitter
user[full_name]OptionalFull name
user[phone]OptionalPhone
user[website]OptionalWebsite
user[custom_data]OptionalUser’s additional info (if any)
user[tag_list]OptionalTags
user[timezone]OptionalMinutes UTC offset
user[avatar]OptionalThe graphical representation of the user
user[blob_id]OptionalDeprecated - ID of associated blob (for example, user’s photo)
Request example
Terminal window
curl -X PUT \
-H "Content-Type: application/json" \
-H "CB-Token: <TOKEN>" \
-d '{"user": {"email": "pallavi.purushottam@yahoo.com", "website": "pavalli.com.au"}}' \
https://api.connectycube.com/users/51943
Response
{
"user": {
"id":51943,
"full_name":"Pallavi Purushottam",
"email":"pallavi.purushottam@yahoo.com",
"login":"ppavalli",
"phone":"+6138907507",
"website":"http://pavalli.com.au",
"created_at":"2018-12-06T09:21:41Z",
"updated_at":"2018-12-06T11:50:16Z",
"last_request_at":null,
"external_user_id":null,
"facebook_id":null,
"twitter_id":null,
"blob_id":null,
"custom_data":null,
"avatar":null,
"user_tags":"accountant",
"timezone": null
}
}

Delete User by identifier

Delete User by user’s identifier. Users can delete their own accounts only.

Endpoint
DELETE https://api.connectycube.com/users/{user_id}
Request example
Terminal window
curl -X DELETE \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/51959
Response
Status: 200

Delete User by external user ID

Delete User by specifying an external user id.

Request
DELETE https://api.connectycube.com/users/external/{external_user_id}
Request example
Terminal window
curl -X DELETE \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/external/52691165
Response
Status: 200

Reset User password by email

Reseting User’s password by specifying an email. Reset link will be sent on the specified email.

Endpoint
GET https://api.connectycube.com/users/password/reset
Parameters
ParameterRequiredDescription
emailYesUser’s email available in the user’s profile
Request example
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'email=dacia_k@domain.com' \
https://api.connectycube.com/users/password/reset
Response
Status: 200

User whose email was specified in the requests receives an email immidiately with a reset link:

Reset password email