Core - Communities

This module is dedicated to the user communities and the relevant information such as terms of service, FAQs, etc.

The base url for the APIs in this page is at:

/api/admin

A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.

Get Tree of communities

Gets the tree of communities:

GET /v1/communities/tree

Gets the tree of communities

Status Codes

The request will return a positive Json response and the tree of communities as per the following example:

[
  {
    ID: 1234,                                           // Int
    Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",       // Guid
    Name: "Community Name",                             // String
    Level: 0,                                           // Int
    Parent: "53155c4b-b2a0-412f-ab41-662d9ccdf784",     // Guid (nullable)
    Children:
    [
      {
        ID: 14,
        Guid: "b2686bd5-5fa4-4cca-a904-d616faf86a74",
        Name: "aaa003",
        Level: 1,
        Parent: "53155c4a-b2a0-412f-ab41-552d9ccdf784",
        Children: [...]
      },
      ...
    ]
  },
  ...
]

The Parent field inside a children is always valorized. The Level field is an incrementing value, where the value on a children is the value of the parent incremented by 1.

Get communities subtree

Gets a subtree of communities for the specified parent:

GET /v1/communities/{id}/tree

Gets a subtree of communities for the specified parent

Parameters

  • id (integer) – The id of the parent community

Status Codes

The request will return a positive Json response and the subtree of the specified community:

[
  {
    ID: 1234,                                          // Int
    Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",      // Guid
    Name: "Community Name",                            // String
    Level: 0,                                          // Int
    Parent: "53155c4b-b2a0-412f-ab41-662d9ccdf784",    // Guid (nullable)
    Children:
    [
      {
        ID: 14,
        Guid: "b2686bd5-5fa4-4cca-a904-d616faf86a74",
        Name: "aaa003",
        Level: 1,
        DeletionDate: null,
        Parent: "53155c4a-b2a0-412f-ab41-552d9ccdf784",
        Children: [...]
      },
      ...
    ]
  },
  ...
]

The Parent field inside a children is always valorized. The Level field is an incrementing value, where the value on a children is the value of the parent incremented by 1.

Get a community

Gets a specific community:

GET /v1/communities/{id}

Gets a specific community

Parameters

  • id (integer) – The id of the community

Status Codes
DELETE /v1/communities/{id}

Marks a specific community (and all sub-communities) as deleted

Parameters

  • id (integer) – The id of the community

Status Codes

If the specified id corresponds to an existing community, the request will return a positive Json response and the data of the community requested:

{
  ID: 1234,                                        // Int
  ParentID: 1233,                                  // Int (nullable)
  Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid
  Name: "Community Nmame",                         // String
  RegistrationCode: "RegistrationCode",            // String
  Level: 0,                                        // Int
  CreatedDate: "2001-01-01T01:01:01Z",             // DateTime
  LastUpdated: "2001-01-01T01:01:01Z",             // DateTime
  LevelName: "Master",                             // String
  Logo: "013d7d16d7ad4fefb61bd95b765c8ceb...",     // ByteArray as String (nullable)
  PrimaryColor: 3456,                              // Int (nullable)
  AccentColor: 6789                                // Int (nullable)
}

If the id does not correspond to an existing community, the response will be empty. If there is a problem during the request a plain Json negative message will be returned. Possible error messages are:

err_unauthorized

The user does not have the authorization to access the information for the request community

Get a community by Guid

Gets a specific community by its Guid:

GET /v1/communities/{guid}

Gets a specific community

Parameters

  • guid (string) – The id of the community

Status Codes

If the specified Guid corresponds to an existing community, the request will return a positive Json response and the data of the community requested:

{
  ID: 1234,                                       // Int
  ParentID: 1233,                                 // Int (nullable)
  Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid
  Name: "Community Nmame",                        // String
  RegistrationCode: "RegistrationCode",           // String
  Level: 0,                                       // Int
  CreatedDate: "2001-01-01T01:01:01Z",            // DateTime
  LastUpdated: "2001-01-01T01:01:01Z",            // DateTime
  LevelName: "Master",                            // String
  Logo: "013d7d16d7ad4fefb61bd95b765c8ceb...",    // ByteArray as String (nullable)
  PrimaryColor: 3456,                             // Int (nullable)
  AccentColor: 6789                               // Int (nullable)
}

If the Guid does not correspond to an existing community, the response will be empty. If there is a problem during the request a plain Json negative message will be returned. Possible error messages are:

err_unauthorized

The user does not have the authorization to access the information for the request community

Get list of communities

Gets the flat list of all communities (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/list

Gets the flat list of all communities

Status Codes

The request will return a positive Json response with the following data:

{
  [
    {
      ID: 1234,                                       // Int
      Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784",   // Guid
      Name: "Community Nmame",                        // String
      RegistrationCode: "RegistrationCode",           // String
      Level: 0,                                       // Int
      CreatedDate: "2001-01-01T01:01:01Z",            // DateTime
      LastUpdated: "2001-01-01T01:01:01Z",            // DateTime
      LevelName: "Master",                            // String
      Logo: "013d7d16d7ad4fefb61bd95b765c8ceb...",    // ByteArray as String (nullable)
      PrimaryColor: 3456,                             // Int (nullable)
      AccentColor: 6789                               // Int (nullable)
    },
    { ... }
  ]
}

or a plain negative response in case of errors.

Add new or edit existing community

Persists edits about a new or existing community record:

POST /v1/communities

Persists edits about a new or existing community

Status Codes

The following is an example of a request:

{
  ID: 1234,          // Int
  Name: "",          // String Required
  ParentId: null,    // Int (nullable)
  Level: 0           // Int
}

If the ID field is not provided or set to 0, then the request will create a new record.

The Level property must be positive or null, and less than 4.

The ParentId field will be ignored while editing an existing community.

err_UserCannotAddChild

The user does not have the privilige to edit a subcommunity/child or edit an existing subcommunity/child

err_UserCannotAddRoot

The user does not have the privilige to add a community or edit an existing community

err_LevelNotExisting

The user is trying to add community to a non-existing level

err_InvalidElement

The name property is not set, the provided level is less than 0 or greater or equal than 4, or no communit to edit was found for the provided ID

Delete community

Marks a specific community (and all sub-communities) as deleted:

GET /v1/communities/{id}

Gets a specific community

Parameters

  • id (integer) – The id of the community

Status Codes
DELETE /v1/communities/{id}

Marks a specific community (and all sub-communities) as deleted

Parameters

  • id (integer) – The id of the community

Status Codes

A plain positive or negative Json response will be returned depending on whether the operation was successful.

Possible error messages are:

err_ElementDoesNotExist

The id provided in the request does not correspond to any existing community

err_ElementAlreadyDeleted

The community is already marked as deleted

err_UserCannotDelete

The user does not have the privileges to delete the community

err_CannotDeleteHasChildren

The community, or one of its subcommunities/children, currently has users.

Get list of community default groups

Gets the list of default groups for new registrations to a specific community (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/{id}/groups

Gets the list of default groups for new registrations to a specific community

Parameters

  • id (integer) – The id of the community

Status Codes
id: Int

The request will return list of the default groups (only the records contained in the current page) as per the following example:

[
  {
    ID: 1,                                  // Int
    CreatedDate: "2001-01-01T01:01:01Z",    // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",    // DateTime
    Labels: "Name of the group",            // String
  },
  ...
]

Get list of community ancestors default groups

Gets the list of default groups for new registrations inherited by ancestors of a specific community:

GET /v1/communities/{id}/ancestors-groups

Gets the list of default groups for new registrations inherited by ancestors of a specific community

Parameters

  • id (integer) – The id of the community

Status Codes
id: Int

The response will be a positive Json response and the list with the following structure:

[
  {
    ID: 1,                                  // Int
    CreatedDate: "2001-01-01T01:01:01Z",    // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",    // DateTime
    Labels: "Name of the group"             // String
  },
  ...
]

The request will return a Json negative response if there was an error retrieving the list.

Get list of community group IDs

Gets the list of group IDs for new registrations to a specific community:

GET /v1/communities/{id}/groups-id

Gets the list of group IDs for new registrations to a specific community

Parameters

  • id (integer) – The id of the community

Status Codes
id: Int

The request will return a positive Json response and a list of the groups ID filtered by the community provided:

{
  [ID1,ID2,ID3,...]
}

Set enabled groups

Persists the list of groups to enable for new registrations to a specific community:

POST /v1/communities/groups

Persists the list of groups to enable for new registrations to a specific community

Status Codes

The request requires the id of the specific community:

{
  ID: 1234,              // Int
  Groups: [1,2,3,...]    // Int Array
}

If the request is successful, a positive Json response will be returned.

The following errors will be returned:

err_InvalidElement

No community was found for the provided ID

Edit community branding

Persists edits about branding of a community (colors, images):

POST /v1/communities/{id}/branding

Persists edits about branding of a community (colors, images)

Parameters

  • id (integer) – The id of the community

Status Codes
id: Int

The structure of the values is the following:

{
  Base64String: "013d7d16d7ad4fefb61bd95b765c8ceb...",    // String (nullable)
  PrimaryColor: 123,                                      // Int (nullable)
  AccentColor: 456                                        // Int (nullable)
}

The request will return a positive JSon response if the branding edits are saved correctly or if no edit was necessary in case of empty or null values.

A Json negative response will return if the request wasn’t able to find a valid community based on the id provided, or if there was a problem saving the edits.

Get community details

Gets the list of community details (key-value pairs) for a specific community (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/{guid}/details

Gets the list of community details (key-value pairs) for a specific community

Parameters

  • guid (string) – The guid of the community

Status Codes
POST /v1/communities/{guid}/details

Persists edits about a new or existing community detail

Parameters

  • guid (string) – The guid of the community

Status Codes
Guid: Community Guid

The request will return a Json negative response if the provided Guid does not correspond to any existing community.

The request will return the list (only the records contained in the current page) of the community details for the requested community:

[
  {
    LastUpdated: "2001-01-01T01:01:01Z",    // DateTime
    Key: "",                                // String
    Value: ""                               // String
  },
  ...
]

Possible errors are:

err_InvalidElement

No key has been provided in the Json body

Add new or edit community details

Persists edits about a new or existing community detail:

GET /v1/communities/{guid}/details

Gets the list of community details (key-value pairs) for a specific community

Parameters

  • guid (string) – The guid of the community

Status Codes
POST /v1/communities/{guid}/details

Persists edits about a new or existing community detail

Parameters

  • guid (string) – The guid of the community

Status Codes
Guid: Guid

The structure of the values is the following:

{
  Key: "detail key",       // String
  Value: "detail value"    // String (nullable)
}

If on the specified community already exists a detail with the provided Key, its value will be updated with the specified Value.

If no details with the provided Key exists on the specified community, a new detail will be added.

The request will return a Json error message if not successful.

Specific error messages are:

err_InvalidElement

Key is empty or null.

Delete community detail

Deletes a detail (key-value pair) for a specific community:

DELETE /v1/communities/{guid}/details/{key}

Deletes a specific community detail (key-value pair)

Parameters

  • guid (string) – The guid of the community

  • key (string) – The key of the detail

Status Codes

If Guid corresponds to an existing community and the key corresponds to an existing detail, the record will be deleted and a positive Json response will be returned. If not, a negative Json response will be returned with no additional details.

Get list of community hierarchy levels

Gets the list of community hierarchy levels:

GET /v1/communities/levels/list

Gets the list of community hierarchy levels

Status Codes

The request will return a list of the hierarchy levels of a community with the following structure:

{
  LastUpdated: "2001-01-01T01:01:01Z",    // DateTime
  Name: "Community Name",                 // String
  Level: 1                                // Int
}

Add or edit existing community level

Persists edits about a new or existing community level:

POST /v1/communities/levels

Persists edits about a new or existing community level

Status Codes

The format of the request is the following:

{
  ID: 1234,             // Int
  Level: 1,             // Int
  Name: "Level name"    // String
}

If the ID field is not provided or set to 0, then the request will create a new record.

The request will return a positive JSon response if the community level as been successfully added or modified.

Some of the specific error messages are:

err_MaxLevelReached

The maximum number of level allowed has been reached

err_InvalidElement

The provided level is less than 0, greater than 3 or different from the last level described + 1, no name was passed or no community level to edit was found for the provided ID

err_DuplicateElement

The request is trying to add a record with the same Level as an existing one.

Delete community level

Remove a community level from the DB:

DELETE /v1/communities/levels/{id}

Marks a community level as deleted

Parameters

  • id (integer) – The id of the level

Status Codes
id: Int ID Level

A plain positive or negative Json response will be returned depending on whether the operation was successful.

Get a Bulletin Board document

Gets a specific BB document:

GET /v1/communities/{id}/bulletin-board-documents/{did}

Gets a specific BB document

Parameters

  • id (integer) – The id of the parent community

  • did (integer) – The id of the document

Status Codes
DELETE /v1/communities/{id}/bulletin-board-documents/{did}

Marks a specific document as deleted

Parameters

  • did (integer) – The id of the document

  • id (string) –

Status Codes
id: Parent Community (Int)
did: Document ID (Int)

If the request is successful it will return a positive Json response with this data:

{
  ID: 1,                                                   // Int
  CommunityId: 12345,                                      // Int
  CommunityName: "Community",                              // String
  LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
  LastUpdatedBy: "Jane Doe",                               // String
  Title: "Document name",                                  // String
  Body: "Body text of the document",                       // String
  Url: "http://www...",                                    // String
  Ordinal: 0,                                              // Int
  Type: 0,                                                 // Int (enum DocumentType)
  AttachmentId: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid (nullable)
  LCID: 0,                                                 // Int
  Language: "en-GB"                                        // String
}

Value types can be one of the DocumentType enumeration.

Get FAQs

Gets a list of FAQ documents for the specified community (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/{id}/bulletin-board-documents/faqs

Gets a list of FAQ documents for the specified community

Parameters

  • id (integer) – The id of the parent community

Status Codes
id: Parent Community ID (Int)

If the FAQs cannot be found the API will return an empty array.

If the FAQs are found, the response has this data:

[
  {
    ID: 1,                                                   // Int
    CommunityId: 12345,                                      // Int
    CommunityName: "Community",                              // String
    LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
    LastUpdatedBy: "Jane Doe",                               // String
    Title: "Document name",                                  // String
    Body: "Body text of the document",                       // String
    Url: "http://www...",                                    // String
    Ordinal: 0,                                              // Int
    Type: 0,                                                 // Int (enum DocumentType)
    AttachmentId: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid (nullable)
    LCID: 0,                                                 // Int
    Language: "en-GB"                                        // String
  },
  ...
]

Value type for FAQ is always 1 (as in DocumentType enumeration)

Get Terms and Conditions

Gets a list of documents for the specified community (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/{id}/bulletin-board-documents/terms-and-conditions

Gets a list of documents for the specified community

Parameters

  • id (integer) – The id of the parent community

Status Codes
id: Parent Community ID (Int)

If no terms and conditions can be found the API will return an empty array.

If the terms and conditions for the specified community can be found, the response is the following:

[
  {
    ID: 1,                                                   // Int
    CommunityId: 12345,                                      // Int
    CommunityName: "Community",                              // String
    LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
    LastUpdatedBy: "Jane Doe",                               // String
    Title: "Document name",                                  // String
    Body: "Body text of the document",                       // String
    Url: "http://www...",                                    // String
    Ordinal: 0,                                              // Int
    Type: 0,                                                 // Int (enum DocumentType)
    AttachmentId: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid (nullable)
    LCID: 0,                                                 // Int
    Language: "en-GB"                                        // String
  },
  ...
]

For Terms & Conditions Type is always 0 (as in DocumentType enumeration)

Get all documents of a community

Gets a complete list of all documents for the specified community corresponding to the id provided in the request (it’s a Paged List APIs, as explained in the introduction):

GET /v1/communities/{id}/bulletin-board-documents/list

Gets a complete list of all documents for the specified community

Parameters

  • id (integer) – The id of the community

Status Codes
id: Parent Community ID (Int)

If the list of documents for the specified community can be found, the response is the following:

[
  {
    ID: 1,                                                   // Int
    CommunityId: 12345,                                      // Int
    CommunityName: "Community",                              // String
    LastUpdated: "2001-01-01T01:01:01Z",                     // DateTime
    LastUpdatedBy: "Jane Doe",                               // String
    Title: "Document name",                                  // String
    Body: "Body text of the document",                       // String
    Url: "http://www...",                                    // String
    Ordinal: 0,                                              // Int
    Type: 0,                                                 // Int (enum DocumentType)
    AttachmentId: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid (nullable)
    LCID: 0,                                                 // Int
    Language: "en-GB"                                        // String
  },
  ...
]

Value types can be one of the DocumentType enumeration.

Edit an existing document or create a new document

Persists edits about a new or existing document for the specified community:

POST /v1/communities/{id}/bulletin-board-documents

Persists edits about a new or existing document

Parameters

  • id (integer) – The id of the community

Status Codes
id: Parent Community ID (Int)

With a request body like this:

{
  ID: 1234,                                                // Int
  Title: "Name of the attachment",                         // String
  Body: "Body of the attachment",                          // String (nullable)
  Ordinal: 0,                                              // Int
  Url: "http://www...",                                    // String (nullable)
  AttachmentId: "53155c4a-b2a0-412f-ab41-552d9ccdf784",    // Guid (nullable)
  Attachment: "...",                                       // Base64String (nullable)
  AttachmentName: "Name-of-the-attachment",                // String (nullable)
  AttachmentMimeType: "application/pdf",                   // String (nullable)
  Type: 1,                                                 // Int (enum DocumentType)
  LCID: 1040,                                              // Int
  Language: "it-IT"                                        // String
}

Value types can be one of the DocumentType enumeration.

If the ID field is not provided or set to 0, then the request will create a new record. If the request is succesfull, it will return a positive Json response

Some of the possible specific error responses are:

err_UserCannotAccessCommunity

The user doesn’t have the privilege to add a bulletin board document to the community or edit an existing document

err_NoBodyOrAttachment

Both Body and Url are null or empty and AttachmentId is null

err_BothUrlAndFile

The user is trying to add both url and attachment for the document

err_BothBodyAndFile

The user is trying to add both body and attachment for the document

err_BothBodyAndUrl

The user is trying to add both body and url for the document

err_BodyUrlAndFile

The user is trying to add a body, an url and an attachment for the document

err_InvalidElement

No community was found for the id specified in the request url, no title was provided in the request body, an incorrect language code was provided or no document to edit was found for the provided ID

err_DuplicateElement:

The request is trying to add a record similar to an existing one on the same community, with the same ordinal, title, document type and culture language.

Delete document

Marks a specific document of the specified community as deleted:

GET /v1/communities/{id}/bulletin-board-documents/{did}

Gets a specific BB document

Parameters

  • id (integer) – The id of the parent community

  • did (integer) – The id of the document

Status Codes
DELETE /v1/communities/{id}/bulletin-board-documents/{did}

Marks a specific document as deleted

Parameters

  • did (integer) – The id of the document

  • id (string) –

Status Codes
id: Parent Community ID (Int)
did: Document ID (Int)

If the request is successful, the specified document will be marked as deleted, and it will return a positive Json response.

Some of the possible errors are:

err_ElementDoesNotExst

There is no document corresponding to the provided document id number

err_ElementAlreadyDeleted

The specified document has already bene marked as deleted