NOTE: all requests must be authenticated.

In general, there are three ways to retrieve the full details of an entity within Yapster:

By it’s unique ID within Yapster.
By it’s unique external ID.

These are IDs that are provided by the source system for the entity. For a user, this would be their unique ID within the originating HR system, similarly for groups. In some instances—such as conversations—the creator of the entity is able to specify the external ID when creating the entity.
By performing a text-based query.

Typically this is performed against the name of the entity and puts the onus on the querier for selecting the correct result.

Where possible using a known unique ID should always be preferred over performing a text-based query.

Finding Orgs

Every company that uses Yapster is represented by a unique ‘Org’ record. This serves as the root record against which all related records are recorded and partitioned.

It is only possible to retrieve a list of the ‘orgs’ of which you, as an authenticated user, are a member.

Typically users are only assigned to a single org, however, if your user is assigned to multiple organizations then you will need to select the appropriate entity from those returned (and specify it’s UUID when making requests related to it.)

Path	`/api/users/{user-id}/orgs`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
user-id	the UUID of the user whose org memberships to list

(Typically you will only be able to, and only be interested in, listing the orgs for the user you are authenticated as. Not sure what that ID is? Retrieve your authenticated user details.)

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 'https://devapi.yapsterchat.com/api/users/<user UUID>/orgs'

Response

A successful response will be a JSON document consisting of:

[{
 "id": "<org UUID>",
 "name": "Example Org",
 "nick": "example",
 // … other org details
},
 …
]

You will need to extract the "id" of the relevant org in order to make requests related to the users, groups, conversations, etc. within it.

Finding Users

By External ID

Path	`/api/orgs/{org-id}/org-users/by-external-uid/{external-uid}`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org to which the user belongs
external-uid	the external ID of the user to lookup

External UIDs for users will typically be the employee number/staff ID of the user within the organisations HR system as that will have been the source from which they were imported.

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 'https://devapi.yapsterchat.com/api/orgs/<org-id>/org-users/by-external-uid/<external-uid>'

Response

A successful response will be a JSON document consisting of:

{
 "org_id": "<org UUID>",
 "user_id": "<user UUID>",
 "staff_uid": "<user external UUID>",
 "name": "Example Dummy User",
 "managed_name": "Example User",
 "username": "example",
 "function_id": ["<group UUID>", "<group UUID>", …],
 "location_id": ["<group UUID>", "<group UUID>", …],
 // … other user details 
}

Some items to note:

"name" should be preferred over "managed_name" if present (either field may be null.)

The "name" field is the users preferred name whereas "managed_name" is the name provided during import.
A users "username" is their @mention handle.

If a user doesn’t have a "username" their @mention handle is a normalized version of their "name" (non-ascii characters removed, spaces replaced by underscores.)
The "function_id" and "location_id" lists are sorted such that the users primary function/location groups are first.

By Text Search

Path	`/api/orgs/{org-id}/org-users`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org to which the user belongs

Query Parameters

Name	Value
q	the string to search for

The given query string will only be matched against users names (both their "name", "managed_name", and "username") and partial matches are possible (e.g. searching for a user by only their surname.)

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 'https://devapi.yapsterchat.com/api/orgs/<org-id>/org-users?q=example'

Response

A successful response will be a JSON document consisting of:

[
 {
  "org_id": "<org UUID>",
  "user_id": "<user UUID>",
  "staff_uid": "<user external UUID>",
  "name": "Example Dummy User",
  "managed_name": "Example User",
  "username": "example",
  "function_id": ["<group UUID>", "<group UUID>", …],
  "location_id": ["<group UUID>", "<group UUID>", …],
  // … other user details
 },
 …
]

(Note that unlike the external ID lookup this response can include multiple user records.)

Finding Groups

By External ID

Path	`/api/orgs/{org-id}/groups/by-external-uid/{external-uid}`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org to which the user belongs
external-uid	the external ID of the group to lookup

Important: the group "external-uid"s are prefixed by their type within Yapster.

When looking up groups by external ID in Yapster be sure to prefix the ID with either [[F]]—if the group represents a function/role/job/etc.—or [[L]]—when it’s a location/area/region/store/etc.

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 'https://devapi.yapsterchat.com/api/orgs/<org-id>/groups/by-external-uid/<external-uid>'

Important: remember to URL escape the <external-uid> (e.g. [[F]]1234 becomes %5B%5BF%5D%5D1234.)

Response

A successful response will be a JSON document consisting of:

{
 "org_id": "<org UUID>",
 "id": "<group UUID>",
 "external_uid": "<group external UUID>",
 "name": "Example Function Group",
 "flavour": "org_user__function_id",
 // … other group details
}

By Text Search

Path	`/api/orgs/{org-id}/groups`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org to which the group belongs

Query Parameters

Name	Value
q	the string to search for

The given query string will only be matched against the groups name.

Example Request

$ curl \ -X GET \ -H "Authorization: Token <auth token value>" \ -H 'Accept: application/json' \ 'https://devapi.yapsterchat.com/api/orgs/<org-id>/groups?q=example'

Response

A successful response will be a JSON document consisting of:

[ { "org_id": "<org UUID>", "id": "<group UUID>", "external_uid": "<group external UUID>", "name": "Example Function Group", "flavour": "org_user__function_id", // … other group details }, … ]

Finding Conversations

By External ID

When creating a conversation you can (optionally) specify an external_uid to make retrieval of that conversation simpler in the future. These external UIDs can be any string value you choose—they are not restricted to UUIDs!

Path	`/api/orgs/{org-id}/conversations/by-external-uid/{external-uid}`
Method	`GET`
Response Type	`application/json`

URL Path Parameters

Name	Value
org-id	the UUID of the org to which the user belongs
external-uid	the external ID of the group to lookup

Example Request

$ curl \
 -X GET \
 -H "Authorization: Token <auth token value>" \
 -H 'Accept: application/json' \
 'https://devapi.yapsterchat.com/api/orgs/<org-id>/conversations/by-external-uid/my%20conversation'

Response

A successful response will be a JSON document consisting of:

{
 "conversation": {
  "org_id": "<org UUID>",
  "id": "<conversation UUID>",
  "name": "Conversation Title",
  // … other conversation details
 },
 …
}

Note: in addition to returning the "conversation" the response will include a "conversation_participant" record which encapsulates details related to your interaction with the conversation.