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.

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

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.

POST https://api.connectycube.com/users
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
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
{
"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
}
}

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

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

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
{
"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
}
]
}

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

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

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
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'order=asc+string+login' \
https://api.connectycube.com/users
{
"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"]
}
}

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

GET https://api.connectycube.com/users/{user_id}
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/51946
{
"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 information about User stored in the bata base by specifying user’s login.

GET https://api.connectycube.com/users/by_login
ParameterRequiredDescription
loginYesUser’s login to login into the system
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'login=Dacia' \
https://api.connectycube.com/users/by_login
{
"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 information about User stored in the data base by specifying user’s full name.

GET https://api.conectycube.com/users/by_full_name
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
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'full_name=Gabrielle%20Corcoran' \
https://api.connectycube.com/users/by_full_name
{
"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)

Section titled “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.

GET https://api.connectycube.com/users/by_facebook_id
ParameterRequiredDescription
facebook_idYesUser’s ID on Facebook
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'facebook_id=95610574' \
https://api.connectycube.com/users/by_facebook_id
{
"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)

Section titled “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.

GET https://api.connectycube.com/users/by_twitter_id
ParameterRequiredDescription
twitter_idYesUser’s ID on Twitter
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'twitter_id=83510562734' \
https://api.connectycube.com/users/by_twitter_id
{
"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 information about User stored in the data base by specifying user’s email.

GET https://api.connectycube.com/users/by_email
ParameterRequiredDescription
emailYesUser’s email address
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'email=dacia_k@domain.com' \
https://api.connectycube.com/users/by_email
{
"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 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.

GET https://api.connectycube.com/users/by_tags
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
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'tags=accountant' \
https://api.connectycube.com/users/by_tags
{
"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)

Section titled “Retrieve User by external user id (Deprecated)”

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

GET https://api.connectycube.com/users/external/{id}
Terminal window
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/users/external/52691165
{
"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’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.

PUT https://api.connectycube.com/users/{user_id}
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)
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
{
"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 user’s identifier. Users can delete their own accounts only.

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

Delete User by specifying an external user id.

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

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

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

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

Reset password email