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 |
User’s email. Usually login OR email is required to log in into the application | |
external_user_id | ID of User in external system (Deprecated) |
external_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 |
timezone | Minutes 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
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 (Deprecated) | ID of User in external system |
user[external_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[timezone] | Optional | Minutes UTC offset |
user[tag_list] | 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
Response
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
Parameters
Optional parameters to use for data representative.
Pagination
Parameter | Required | Description | Value example |
---|---|---|---|
offset | No | Number of users to skip before show. Default = 0 | offset=50 |
limit | No | Number of results to show per request. Max = 100, default = 100 | limit=20 |
Sort the query result set
Type | Description | Example |
---|---|---|
asc | Ascending | sort_asc=id |
desc | Descending | sort_desc=created_at |
Available fields to filter
Field | Type | Apply Type |
---|---|---|
id | integer | stand-alone |
login | string | stand-alone |
string | stand-alone | |
full_name | string | stand-alone |
phone | string | stand-alone |
external_id | string | stand-alone |
facebook_id | string | stand-alone |
twitter_id | string | stand-alone |
user_tags | array of strings | stand-alone/additional |
last_request_at | date (string or timestamp) | additional |
created_at | date (string or timestamp) | additional |
updated_at | date (string or timestamp) | additional |
Operators
Operator | Description | Value example | Type |
---|---|---|---|
eq | equal | id=51946 | primary |
in | list of data equal | id[in][]=51946&id[in][]=51943 | primary |
start_with | match string starting with substring | full_name[start_with]=diver | primary |
nin | list of data not equal | user_tags[nin][]=vip | exclude |
gt | greater than | updated_at[gt]=2019-11-06T09:21:41Z | compare |
lt | less than | created_at[lt]=2019-11-06T09:21:41Z | compare |
gte | greater than or equal | last_request_at[gte]=2017-12-06T09:21:41Z | compare |
lte | less than or equal | last_request_at[lte]=2018-11-06T09:21:41Z | compare |
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
withprimary
operator)id[in][]=51946&id[in][]=51943&last_request_at[gt]=2018-12-06T09:21:41Z
- valid (stand-alone
withprimary
operator andadditional
withcompare
operator)user_tags=guest
- valid (stand-alone
withprimary
operator)user_tags=guest&created_at[lt]=1690886495
- valid (stand-alone/additional
withprimary
operator andadditional
withcompare
operator)login=smith1&phone=6754987345566&user_tags[nin][]=vip&updated_at[lte]=2018-12-06T09:21:41Z
- valid (hasstand-alone
withprimary
operator)phone=6754987345566&last_request_at=2020-11-09T08:21:41Z
- valid (stand-alone
withprimary
operator)full_name[start_with]=hunter&id[nin][]=68647
- valid (stand-alone
withprimary
operator,start_with
argument length = 6)login[nin][]=admin19
- invalid (stand-alone
only withexclude
operator)user_tags[nin][]=guest
- invalid (stand-alone/additional
only withexclude
operator)last_request_at=2017-07-06T11:21:41Z
- invalid (additional
withprimary
operator)created_at[gte]=2019-11-06T09:21:41Z
- invalid (additional
withcompare
operator)login[start_with]=vip
- invalid (stand-alone
withprimary
operator, butstart_with
argument length = 3)
Example:
Response
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
.
Endpoint
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:
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}
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[eq]=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:
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:
Request example
Response
Note: if ‘Allow to retrieve a list of users via API’ is un-ticked, retrieving users is forbidden, error is shown in the response:
Show User by identifier (Deprecated)
Retrieve information about User stored in the data base by specifying user’s identifier.
Endpoint
Request example
Response
Retrieve User by login (Deprecated)
Retrieve information about User stored in the bata base by specifying user’s login.
Endpoint
Parameters
Parameter | Required | Description |
---|---|---|
login | Yes | User’s login to login into the system |
Request example
Response
Retrieve Users by full name (Deprecated)
Retrieve information about User stored in the data base by specifying user’s full name.
Endpoint
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
Response
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
Parameters
Parameter | Required | Description |
---|---|---|
facebook_id | Yes | User’s ID on Facebook |
Request example
Response
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
Parameters
Parameter | Required | Description |
---|---|---|
twitter_id | Yes | User’s ID on Twitter |
Request example
Response
Retrieve User by email (Deprecated)
Retrieve information about User stored in the data base by specifying user’s email.
Endpoint
Parameters
Parameter | Required | Description |
---|---|---|
Yes | User’s email address |
Request example
Response
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
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
Response
Retrieve User by external user id (Deprecated)
Retrieve information about User stored in the data base by specifying user’s external User ID.
Endpoint
Request example
Response
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
Parameters
Parameter | Required | Description |
---|---|---|
user[login] | Optional | User login |
user[password] | Optional | User password |
user[old_password] | Optional | Old user password. Required if new password provided |
user[email] | Optional | 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[timezone] | Optional | Minutes UTC offset |
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
Response
Delete User by identifier
Delete User by user’s identifier. Users can delete their own accounts only.
Endpoint
Request example
Response
Delete User by external user ID
Delete User by specifying an external user id.
Request
Request example
Response
Reset User password by email
Reseting User’s password by specifying an email. Reset link will be sent on the specified email.
Endpoint
Parameters
Parameter | Required | Description |
---|---|---|
Yes | User’s email available in the user’s profile |
Request example
Response
User whose email was specified in the requests receives an email immidiately with a reset link: