Skip to main content
Kinetic Community

Users / Invitations / Participants

This resource describes the concept of Users, Invitations and Participants and the actions that can be performed on them. In Kinetic Response anyone who creates an account is considered a User. In order to access any Issues the person must first be registered as a User. So a User simply means that the person has registered with Kinetic Response. A User can have their information fetched and edited including their password. An Invitation is created when person has been invited to participate in an Issue but has not yet accepted the invitation. Invitations are sent to Users and non-users alike. If an invitation is sent to a User, that user is able to participate immediately. If an invitation is sent to a non-user, then that person must first create a User account before they can participate in the Issue. An Invitation is created by entering a person's email address and sending them an invitation. Invitations can be sent, re-sent and deleted. A Participant is a User that has joined an Issue. A person might become a Participant by either creating an issue, having an issue created for them or joining an Issue via an invitation that they received. If a person is classified as an Invitation and then they accept the Invitation they are then classified as a Participant and not longer considered an Invitation. All users that have access to the Issue are considered Participants. A Participant can be revoked which removes their access from the Issue. It does not however delete the user from the Kinetic Response system. When an Issue is fetched it has an owner (a User that owns the issue), an array of Participants (Users that have joined the issue, this includes the owner) and an array or Invitations (Users and non-users that have been invited to participate). The guids of these Users, Participants and Invitations can be used to access, modify and revoke them.

Editing a User

HTTP Request

To edit user information the client can PUT a JSON User object with the edits to be made. In the case that some fields are not editable, the edits will be ignored.

Method: PUT

URL: api/v1/users/<user_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

Body Content:

{
    "id": 71,
    "email": "dillon.hodapp@kineticdata.com",
    "name": "Dillon Hodapp Admin",
    "type": "Admin",
    "created_at": "2014-07-02T15:39:55.039-05:00",
    "updated_at": "2015-04-02T11:24:06.045-05:00",
    "status": "Active",
    "deleted_at": null,
    "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
    "time_zone": "Central Time (US & Canada)",
    "company": "Companydd",
    "phone": "555-555-5555",
    "title": "Title"
}

 

Parameters

Edit section
Route Parameter Name Description Required / Optional
name Name of User Optional
email Email of User Optional
company Company name of User Optional
title Title of User Optional
phone Phone number of User Optional

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to the newly created User.

 

Example Response:

{
    "id": 71,
    "email": "dillon.hodapp@kineticdata.com",
    "name": "Dillon Hodapp Admin",
    "type": "Admin",
    "created_at": "2014-07-02T15:39:55.039-05:00",
    "updated_at": "2015-04-02T11:24:06.045-05:00",
    "status": "Active",
    "deleted_at": null,
    "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
    "time_zone": "Central Time (US & Canada)",
    "company": "Companydd",
    "phone": "555-555-5555",
    "title": "Title"
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 422 

Response Body:

{
"message": "Unprocessable attributes",
"reasons": 
    [
        "Detail can't be blank"
    ]
}

 

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
422 A required field was left out.
500 If there was an unexpected server error.

 

Changing a Password

Changing a password is identical to editing a user. 

HTTP Request

Edit section

Method: PUT

URL: api/v1/users/<user_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

Body Content:

{
  "user":{
    "password":"asdf"
  }
}

 

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to the User.

 

Example Response:

{
    "id": 71,
    "email": "dillon.hodapp@kineticdata.com",
    "name": "Dillon Hodapp Admin",
    "type": "Admin",
    "created_at": "2014-07-02T15:39:55.039-05:00",
    "updated_at": "2015-04-02T11:24:06.045-05:00",
    "status": "Active",
    "deleted_at": null,
    "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
    "time_zone": "Central Time (US & Canada)",
    "company": "Companydd",
    "phone": "555-555-5555",
    "title": "Title"
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.
 

Fetching a User

HTTP Request

Method: GET

URL: api/v1/users/<user_guid>

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to the User.

 

Example Response:

{
    "id": 71,
    "email": "dillon.hodapp@kineticdata.com",
    "name": "Dillon Hodapp Admin",
    "type": "Admin",
    "created_at": "2014-07-02T15:39:55.039-05:00",
    "updated_at": "2015-04-02T11:24:06.045-05:00",
    "status": "Active",
    "deleted_at": null,
    "guid": "971c294f-49b7-4a05-a25f-733ce678449a",
    "time_zone": "Central Time (US & Canada)",
    "company": "Companydd",
    "phone": "555-555-5555",
    "title": "Title"
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

 

 

Creating an Invitation

An Invitation is used to inform someone that there presence is being requested in an Issue. The person may already be a User or they may not be. An Invitation needs an email address so that it can be routed to the correct person. A person can be re-invited using this same route.

HTTP Request

Edit section

Method: POST

URL: /api/v1/issues/<issue_guid>/invites

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

 

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code. 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
400 Bad Request. Json might have a field named incorrectly.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
422 JSON field named incorrectly.
500 If there was an unexpected server error.
 

Deleting an Invitation

Deletes an Invitation. Note that when invitations are accepted the system automatically deletes them. This is useful only for deleting Invitations that haven't been accepted yet.

HTTP Request

Method: DELETE

URL: /api/v1/issues/<issue_guid>/invites/<invitation_guid>

Headers: Authorization Bearer <token>

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code.

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

Response Codes

Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.

Fetching Invitations

Edit section

HTTP Request

Edit section

Method: GET

URL: api/v1/issues/<issue_guid>/invites

Headers: Content-Type application/json AND Accept application/json AND Authorization Bearer <token>

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body corresponding to an array or Invitations. In the event that there are not any invitations, the array will be empty.

 

Example Response:

[
    {
        "id": 794,
        "user_id": null,
        "issue_id": 92,
        "created_at": "2014-12-12T14:58:16.636-06:00",
        "updated_at": "2014-12-12T14:58:16.636-06:00",
        "suspended": false,
        "status": "Invitee",
        "guid": "3987d488-6f9a-4542-bed5-fb3364eb578d",
        "last_emailed_at": null,
        "last_visited_at": null
    }
]

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.
 

 

 

Revoking a Participant

Edit section

To revoke the access of a person who has joined the issue, it is possible to revoke the Participant. Note, if you attempt to revoke a participant that is also the issue owner you will receive a 500 error.

HTTP Request

Edit section

Method: DELETE

URL: /api/v1/issues/<issue_guid>/participants/<participant_guid>

Headers: Authorization Bearer <token>

 

HTTP Response

Edit section

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code.

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

Note, if you attempt to revoke a participant that is also the issue owner you will receive a 500 error.

Example of a failed request:

Response Code: 401 

Response Body:

{
    "success": false,
    "message": "Error with your login or password"
}

 

Response Codes

Edit section
Response Code Reason
200 Successful request.
401 The auth. token is invalid and needs to be refreshed.
404 If the provided URL was not found on this server.
500 If there was an unexpected server error.