3.1.0

User

Get Users - fetch the first page

Use the API GET /v2/api/management/copilot_connect/users to get your Users. The response will be paginated.

Url

GET https://<BASE_URL>/v2/api/management/copilot_connect/users

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

For how to create an Authorization token see Session Management

Query Parameters

  • order_by - (optional) if included, should be set to updatedAt.
  • order_direction - (optional) if included, should be set to asc or desc. The default is desc.

In case the order_by and order_direction parameters are not provided, the Users will be ordered by their creation time, descending.

Response

Success

Response Model - GetUsersResponse
  • users - An array with Users.
  • next_page - The link for the next page. Concatenate the base URL to this link. In the last page it will return null.
Response Model - User
  • id - (String) The ID of the User in the system.
  • email - (String) The email that was provided during End User registration / End User elevation. If the User is anonymous, it will return null.
  • first_name - (String) The first name of the End User. If the User is anonymous, it will return null.
  • last_name - (String) The last name of the User. If the User is anonymous, it will return null.
  • created_at - (String) Date that the End User was created.
  • updated_at - (String) Date when the User was last updated.

Failures

When the Authorization header is invalid or not provided:

HTTP: HTTP/1.1 401 Unauthorize

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When the request is invalid, e.g order_by=color:

HTTP: HTTP/1.1 400 Bad Request

{
  "reason": "COMMON.REQUEST_VALIDATION",
  "error_message": "Order by column 'color' is not supported"
}

Example

Request

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users?order_by=updatedAt' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

{
  "users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "email": "johndoe@bycopilot.com",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2019-03-13T10:04:10.668Z",
      "updated_at": "2019-03-13T10:04:10.668Z"
    },
    {
      "id": "5c88d40900f138000e9233ba",
      "email": null,
      "first_name": null,
      "last_name": null,
      "created_at": "2019-03-13T09:57:29.779Z",
      "updated_at": "2019-03-13T09:57:29.779Z"
    }
  ],
  "next_page": "/v2/api/management/copilot_connect/users?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw=="
}

Get Users - fetch next pages

Url

GET https://<BASE_URL><next_page>

To fetch the next page, concatenate the next_page link from the previous page response, with your base URL. For example, if your base URL is https://api.iconnect.bycopilot.com and the next_page is /v2/api/management/copilot_connect/users?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw==

the URL will be: https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw==

💡 Remember - verify that next_page is not null before trying to fetch the next page. Next Page will be null on the last page.

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Use headers in the same way as when fetching the first page.

Query Parameters

Do not add any queryParameter manually to the call after building the URL according to the guideline above.

In any case, page parameter is included as part of the next_page link.

Response

Success

See Response models in fetch Users above.

Failures

When the Authorization header is invalid or not provided:

HTTP: HTTP/1.1 401 Unauthorize

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When the request is invalid, for example page=NotValidPage or both page and orderBy parameters were specified

HTTP: HTTP/1.1 400 Bad Request

{
    "reason":"COMMON.REQUEST_VALIDATION",
    "error_message":"Page parameter is not valid. Try to remove the 'page' parameter and start from the first page."
}

HTTP: HTTP/1.1 400 Bad Request

{
    "reason":"COMMON.REQUEST_VALIDATION",
    "error_message":"In case that the parameter page is provided, orderBy and orderDirection must not be specified"
}

Example

In case the first page is

{
  "users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "email": "johndoe@bycopilot.com",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2019-03-13T10:04:10.668Z",
      "updated_at": "2019-03-13T10:04:10.668Z"
    },
    {
      "id": "5c88d40900f138000e9233ba",
      "email": null,
      "first_name": null,
      "last_name": null,
      "created_at": "2019-03-13T09:57:29.779Z",
      "updated_at": "2019-03-13T09:57:29.779Z"
    }
  ],
  "next_page": "/v2/api/management/copilot_connect/users?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw=="
}

Request

The request will be:

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw==' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

The response will be similar to the response of the first page.

Get Single User

Url

GET https://<BASE_URL>/v2/api/management/copilot_connect/users/{user_id}

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating the Authorization token see Session Management

Query Parameters

None

Response

Success

Http code 200 with SingleUser in the body.

Response Model - SingleUser

  • id - (String) End User’s ID.
  • email - (String) The email addresss provided during the End User registration / elevation. In case the User is anonymous, this field will be null
  • first_name - (String) The User’s first name. If the User is anonymous, this field will be null
  • last_name - (String) The User’s last name. If the User is anonymous, this field will be null
  • is_anonymous - (Boolean) Indicates whether the User has registered with an email or annonymously.
  • terms_of_use_version_approved - (String) The version of your product's Terms of Use that has been approved by the End User. If the User has not approved any version of the product's Terms of Use, this field will be null.
  • email_verification_status - (EmailVerificationStatus) The values can be: Unset, Pending or Verified.
  • consents - List of Consent object that represent the consent key that the specific User has accepted or rejected.
  • custom_settings - CustomSettings object stored specifically for this User. See below.
  • associated_things - List of associated_thing object associated with the specific User.
  • created_at - (String) The date that the User was created.
  • updated_at - (String) The date the User was updated.

Response Model - EmailVerificationStatus

One of the following statuses:

  • Verified - The User has verified the email address provided during registration.
  • Pending - The User has not verified the email provided at registration but a request was sent.
  • Unset - The User is anonymous, or, no email verification was required in your system at the time this User registered.

Response Model - Consent

  • key - The consent key, as saved on the application side.
  • value - The consent item values can be Accept or Reject.
  • updated_at - The date this consent key was updated.

Response Model - CustomSettings

Custom Setting is a Map where the keys are Strings and the values might be any object. They are used on the client side as simple key-value pairs, and support the following data types:

  • Primitive data types: Boolean, String, Integer, Float, Double.
  • Array of primitive or custom objects.
  • Dictionary of primitive or custom objects.

See the example User below - illustrating complex custom settings

Response Model - associatedThing

Represent Things that associated to the User. The response provides part of the information available on the returned Things.

  • physical_id - (String) The ID of the Thing in the system; the Thing physical ID as set when associated to the User by the client application.
  • name - (String) Name given to a Thing.
  • model - (String) Thing model.
  • firmware_version - (String) Last known Thing firmware version.
  • last_seen_at - (String) Date the Thing was last seen by the system, set by either mobile application or management API.
  • association_data - An object with the property associated_at representing the association date.

Failures

HTTP: HTTP/1.1 401 Unauthorize

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When requesting a User that does not exist in the system:

HTTP: HTTP/1.1 404 Not Found

{
    "reason": "COMMON.ENTITY_NOT_FOUND",
    "error_message": "User 5c750c9ab85520000f70243e was not found"
}

Example 1

Request

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users/5c88d59a00f138000e9233bc' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

{
  "id": "5c88d59a00f138000e9233bc",
  "first_name": John,
  "last_name": Doe,
  "is_anonymous": true,
  "email": "johndoe@bycopilot.com",
  "terms_of_use_version_approved": "1.0",
  "email_verification_status": "Verified",
  "consents": [
    {
      "key": "consent_key_1",
      "value": "Reject",
      "updated_at": "2019-03-14T19:02:56.498Z"
    },
    {
      "key": "analytics",
      "value": "Accept",
      "updated_at": "2019-03-14T19:02:56.498Z"
    }
  ],
  "custom_settings": {
    "color": "green",
    "viewPreferences": {
      "alignment": 3,
      "showHeader": false
    },
    "favoritePlace": null,
    "age": 32,
    "height": 175.4,
    "favoriteVegetables": [
      "Broccoli",
      "Onions"
    ]
  },
  "associated_things": [
    {
      "physical_id": "abcedfg-323-g",
      "firmware_version": "xv8312",
      "model": "bmx86",
      "name": "My smart thing",
      "last_seen_at": null,
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    },
    {
      "physical_id": "d6d3dc24-a8c2-4834-9b11-d3459ce03bc2",
      "firmware_version": "2.0.0",
      "model": "xv8311",
      "name": "Different name",
      "last_seen_at": "2019-02-26T16:31:57.001Z",
      "association_data": {
        "associated_at": "2019-02-08T13:53:04.728Z"
      }
    }
  ],
  "created_at": "2018-08-14T19:02:56.513Z",
  "updated_at": "2018-09-14T19:02:56.513Z"
}

Example 2

Response

{
    "id": "5c88d59a00f138000e9233bc",
    "first_name": null,
    "last_name": null,
    "is_anonymous": true,
    "email": null,
    "terms_of_use_version_approved": null,
    "email_verification_status": "Unset",
    "consents": [],
    "custom_settings": null,
    "associated_things": [],
    "created_at": "2018-08-14T19:02:56.513Z",
    "updated_at": "2018-08-14T20:00:50.000Z",
}
← Session ManagementThing →