undefined

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 name Description
id User's identifier on server
login User's login on server. Usually login OR email is required to log in into the application
password User's password sets for his user's account. Required for log in process
email User's email. Usually login OR email is required to log in into the application
external_user_id ID of User in external system
facebook_id ID of User in Facebook
twitter_id ID of User in Twitter
full_name User's full name
phone User's phone number
website User's Website address
custom_data User's additional info (if any)
user_tags Tag(s) added for User. Several tags comma separated can be added. Same tags can be used for any number of users
avatar An ID of the graphical representation of the user
blob_id Deprecated - 'avatar' field should be used instead. ID of associated blob. Note: blob should be created before
created_at Date and time when User was registered in the application. System creates this parameter automatically
updated_at System creates / updates this parameter automatically when user's data are updated
last_request_at Date and time where the latest request was sent. System creates this parameter automatically

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
Parameters
Parameter Required Description
user[login] Yes User's login. Only login OR email is required
user[password] Yes User's password
user[email] Yes User's email. Only login OR email is required
user[external_user_id] Optional ID of User in external system
user[facebook_id] Optional ID of User in Facebook
user[twitter_id] Optional ID of User in Twitter
user[full_name] Optional Full name
user[phone] Optional Phone number
user[website] Optional Website address
user[custom_data] Optional User's additional info (if any)
user[user_tags] Optional Tags added for User. Several tags comma separated can be added. Same tags can be used for any number of users
user[avatar] Optional The graphical representation of the user
user[blob_id] Optional Deprecated - 'avatar' field should be used instead. ID of associated blob. Note: blob should be created before

Only login OR email is required.

Request example
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token: <TOKEN>" \
-d '{"user": {"login": "Dacia", "password": "petU4or!", "email": "dacia_k@domain.com", "facebook_id": "91234409", "twitter_id": "83510562734", "full_name": "Dacia Kail ", "phone": "+6110797757"}}' \
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,
        "facebook_id":"91234409",
        "twitter_id":"83510562734",
        "blob_id":null,
        "custom_data":null,
        "avatar":null,
        "user_tags":null
    }
}

Retrieve all Users

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

Before processing a request, make sure retrieving list of users is allowed. For this go to ConnectyCube dashboard under 'Users' module and open 'Settings':

Settings for Users module in the ConnectyCube dashboard

Tick 'Allow to retrieve a list of users via API' check box and save changes to continue:

'Allow to retrieve a list of users via API' check box in user module

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

Optional parameters to use for data representative.

Pagination

Parameter Required Description
page No Number of page to show. The first page is shown by default
per_page No Number of results to show per page. Default number of results per page - 10, maximum number of results per page - 100

Example:

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 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}
Operator Description Value example Data to return
gt greater than filter[gt]=number+id+gt+51496 Users with IDs greater than 51496
lt less than filter[lt]=number+id+lt+51946 Users with IDs less than specified ID
ge greater than or equal filter[ge]=number+id+ge+51946 Users with IDs greater than or equal to specified ID
le less than or equal filter[le]=number+id+le+51946 Users with IDs less than or equal to specified ID
eq equal filter[eg]=number+id+eg+51946 User with ID equal to specified ID
ne not equal filter[ne]=number+id+ne+51946 Users with IDs not equal to specified ID
between between filter[between]=number+id+between+51941,51959 List of users with IDs between the specified range. Range limits should be comma separated
in list of data filter[in]=number+id+in+51943,51946 Users with the specified IDs

Example:

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 sort Description Value Example
asc sort the query result set in an ascending order by any of the field order=asc+{data_type}+{field}. Example: order=asc+string+login
desc sort the query result set in an descending order by any of the field order=desc+{data_type}+{field}. Example: order=desc+integer+facebook_id

Example:

curl -X GET \
-H "CB-Token: <TOKEN>" \
-d 'order=desc+string+full_name' \
https://api.connectycube.com/users
Request example
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,
            "facebook_id":"91234409",
            "twitter_id":"83510562734",
            "blob_id":null,
            "custom_data":null,
            "avatar":null,
            "user_tags":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"
            }
        },
        {
        "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"
            }
        },
    ]
}

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

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

Retrieve User by login

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

Endpoint
GET https://api.connectycube.com/users/by_login
Parameters
Parameter Required Description
login Yes User's login to login into the system
Request example
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
    }
}

Retrieve Users by full name

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
Parameter Required Description
full_name Yes Full name of user
page No Number of page to show. The first page is shown by default
per_page No Number of results to show per page. Default number of results per page - 10, maximum number of results per page - 100
Request example
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"
            }
        }
    ]
}

Retrieve User by Facebook identifier

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
Parameter Required Description
facebook_id Yes User's ID on Facebook
Request example
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"
    }
}

Retrieve User by Twitter identifier

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
Parameter Required Description
twitter_id Yes User's ID on Twitter
Request example
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
    }
}

Retrieve User by email

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

Endpoint
GET https://api.connectycube.com/users/by_email
Parameters
Parameter Required Description
email Yes User's email address
Request example
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
    }
}

Retrieve Users by tags

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
Param Required Description
tags Yes API User tag(s). The maximum number of tags per user: 5. Several tags comma separated can be specified
page No Page number of the book of the results that you want to get. Default: 1
per_page No The maximum number of results per page. Min: 1. Max: 100. Default: 10
Request example
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"
            }
        },
        {
            "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"
            }
        }
    ]
}

Retrieve User by external user id

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
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
    }
}

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
Parameter Required Description
user[login] Yes User login
user[password] Yes User password
user[email] Yes User email
user[external_user_id] Optional ID of User in external system
user[facebook_id] Optional ID of User in Facebook
user[twitter_id] Optional ID of User in Twitter
user[full_name] Optional Full name
user[phone] Optional Phone
user[website] Optional Website
user[custom_data] Optional User's additional info (if any)
user[tag_list] Optional Tags
user[avatar] Optional The graphical representation of the user
user[blob_id] Optional Deprecated - ID of associated blob (for example, user's photo)
Request example
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"
    }
}

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
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
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
Parameter Required Description
email Yes User's email available in the user's profile
Request example
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