Invitation

The HiveSocial system has a build in tool for mass inviting new users to the system. This is done by the invitation methods. The invitation content item is defined as an email sent inviting the user and this target email is not yet registered as user. We refer to this item often as "Pending invitation" as well.

Method: list

Authorization is required.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/invitation/list/{groupId}?offset={offset}&pageSize={pageSize}&filter={filter}&role={role}&target={target}

Parameters

property value description
groupId guid The group for which you want to review the pending invitation's ID
offset integer Needed for the infinite scroll functionality. It is the ID of the last presented item to the user. After the request list is generated the system will skip all records from the beginning up to the record with the provided ID (including it). The next batch of records will be returned in the response.
pageSize integer How many records to be returned by the system. Usually 15
filter string Query string to be looked for when filtering the records
role integer As what role the user was invited in the group. The alternatives for this parameter are:
  • 0 - all roles
  • 2 - regular
  • 3 - member
  • 4 - moderator
  • 5 - administrator
target string Where to look for the filter string. Alternatives are:
  • name
  • email

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Sint do dolor nostrud enim laboris velit veniam nulla nulla.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [],
  "object": {
    "offset": "873dd4d2-7329-4de8-a897-829093635227",
    "invitations": [
      {
        "id": "0e87724a-1cf7-4afd-8f71-5f8b9ae2f10d",
        "type": "invitation",
        "group": {
          "id": "50b88e09-141a-4a2e-811c-d7e086910951",
          "name": "ad",
          "slug": "Home",
          "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
          "url": "http://demo.hivesocialnow.com/Home/"
        },
        "createdOn": "2014-03-03T23:20:23Z",
        "author": {
          "id": "b77fa1be-e5d9-47d7-bfae-cd57aa1ec4f3",
          "alias": "amet do",
          "extendedAlias": "sunt dolore id commodo dolor",
          "slug": "Home",
          "avatarUrl": "http://demo.hivesocialnow.com/bigavatar/bc7fbf51-7930-4550-98b0-6a3ff6111ebe.jpg",
          "url": "http://demo.hivesocialnow.com/blog/GeorgiRaykov/site/profile/"
        },
        "email": "andersonlandry@krag.com",
        "firstName": "in",
        "lastName": "cillum",
        "roleId": 2,
        "roleName": "regular",
        "accessWarnings": []
      }
    ]
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

property value description
id guid The invitation Id
group object The group to which the user is invited
createdOn date When the invitation was created in ISO 8601 string format and UTC time zone
author object Who created the invitation
email string The invited email
firstName string The first name of the invited person
lastName string The last name of the invited person
roleId integer The id of the role the person was invited with
roleName string Human readable role name

Method: delete

Authorization is required.

Request

HTTP request

DELETE https://<YOUR_DOMAIN>/api/v1/en_US/invitation/{invitationId}

Parameters

property value description
invitationId integer In id of the deleted record

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "timestamp": "2014-03-03T23:20:23Z",
  "success": true,
  "message": "Aliqua anim consequat amet cupidatat proident amet amet.",
  "errors": [],
  "object": {
    "id": "0e87724a-1cf7-4afd-8f71-5f8b9ae2f10d",
    "type": "invitation",
    "group": {
      "id": "50b88e09-141a-4a2e-811c-d7e086910951",
      "name": "ad",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "createdOn": "2014-03-03T23:20:23Z",
    "author": {
      "id": "b77fa1be-e5d9-47d7-bfae-cd57aa1ec4f3",
      "alias": "amet do",
      "extendedAlias": "sunt dolore id commodo dolor",
      "slug": "Home",
      "avatarUrl": "http://demo.hivesocialnow.com/bigavatar/bc7fbf51-7930-4550-98b0-6a3ff6111ebe.jpg",
      "url": "http://demo.hivesocialnow.com/blog/GeorgiRaykov/site/profile/"
    },
    "email": "andersonlandry@krag.com",
    "firstName": "in",
    "lastName": "cillum",
    "roleId": 2,
    "roleName": "regular",
    "accessWarnings": []
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

property value description
success Boolean Whether the requested operation is successful or not
message String Human readable error information
errors List (object) This list very rarely contains records during delete method processing
object object The object that was deleted

Method: resend

Authorization is required.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/invitation/{invitationId}/resend

Parameters

property value description
invitationId guid The id of the invitation that needs to be resend

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "timestamp": "2014-03-03T23:20:23Z",
  "success": true,
  "message": "Aliqua anim consequat amet cupidatat proident amet amet.",
  "errors": [],
  "object": {
    "id": "0e87724a-1cf7-4afd-8f71-5f8b9ae2f10d",
    "type": "invitation",
    "group": {
      "id": "50b88e09-141a-4a2e-811c-d7e086910951",
      "name": "ad",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "createdOn": "2014-03-03T23:20:23Z",
    "author": {
      "id": "b77fa1be-e5d9-47d7-bfae-cd57aa1ec4f3",
      "alias": "amet do",
      "extendedAlias": "sunt dolore id commodo dolor",
      "slug": "Home",
      "avatarUrl": "http://demo.hivesocialnow.com/bigavatar/bc7fbf51-7930-4550-98b0-6a3ff6111ebe.jpg",
      "url": "http://demo.hivesocialnow.com/blog/GeorgiRaykov/site/profile/"
    },
    "email": "andersonlandry@krag.com",
    "firstName": "in",
    "lastName": "cillum",
    "roleId": 2,
    "roleName": "regular",
    "accessWarnings": []
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

Method: evaluate invitations import

Authorization is required.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/invitation/import-evaluate-csv/{groupId}

Parameters

property value description
groupId guid The group for which you want to review the pending invitation's ID

Request body

property value description
roleId integer With which role you are inviting the users. The alternatives are:
  • 2 - regular
  • 3 - member
  • 4 - moderator
  • 5 - administrator
csvPath string Path to the CSV file you need to import. File format: email, first name, last name. Separation between user records is newline.
subject string The subject of the invitation email
header string message content header. If null the string set in the group settings will be used.
content string message content
footer string message content footer. If null the string set in the group settings will be used.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Qui Lorem velit laborum aute duis sunt.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [
    {
      "key": "csvPath",
      "value": "http://demo.hivesocialnow.com/ClientFiles/bc7fbf51-7930-4550-98b0-6a3ff6111ebe/users.csv",
      "message": "The csv file is with wrong format"
    }
  ],
  "object": {
    "input": {
      "roleId": 1,
      "csvPath": "http://demo.hivesocialnow.com/ClientFiles/bc7fbf51-7930-4550-98b0-6a3ff6111ebe/users.csv",
      "subject": "Some subject here",
      "header": "Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. At vero eos et accusam et justo duo dolores et ea rebum.",
      "content": "Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. At vero eos et accusam et justo duo dolores et ea rebum.",
      "footer": "Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. At vero eos et accusam et justo duo dolores et ea rebum."
    },
    "output": [
      {
        "type": "inviteRow",
        "email": "lottrobinson@isoplex.com",
        "firstName": "John",
        "lastName": "Smith",
        "resultId": 1,
        "resultName": "New user"
      },
      {
        "type": "importRow",
        "email": "besn@isoplex.com",
        "firstName": "John",
        "lastName": "Smith",
        "resultId": 2,
        "resultName": "Group member"
      },
      {
        "type": "importRow",
        "email": "office@isoplex.com",
        "firstName": "John",
        "lastName": "Smith",
        "resultId": 3,
        "resultName": "Existing account"
      },
      {
        "type": "importRow",
        "email": "mary@isoplex.com",
        "firstName": "John",
        "lastName": "Smith",
        "resultId": 4,
        "resultName": "Invalid email"
      }
    ]
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

property value description
resultId integer This is the most important result of this method. Here you can review for each row from the CSV file, what actions will be made, if you proceed with the import.
  • 1 - New user - invitation emails will be send.
  • 2 - Group member - invitation emails will not be send
  • 3 - Existing account - invitation emails will be send
  • 4 - Invalid email - invitation emails will not be send

Method: bulk import

Authorization is required.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/invitation/bulk-import/{groupId}

Parameters

property value description
groupId guid The group for which you want to review the pending invitation's ID

Request body

property value description
roleId integer With which role you are inviting the users. The alternatives are:
  • 2 - regular
  • 3 - member
  • 4 - moderator
  • 5 - administrator
subject string The subject of the invitation email
header string message content header. If null the string set in the group settings will be used.
content string message content
footer string message content footer. If null the string set in the group settings will be used.
records list (object) List of object to be imported. The record object properties are:
  • email - the invited email
  • firstName - the first name of the invited person
  • lastName - the last name of the invited person

Response

If successful, this method returns a response JSON with the following structure:

{
    "success": true,
    "message": "Qui Lorem velit laborum aute duis sunt.",
    "timestamp": "2014-03-03T23:20:23Z",
    "errors": [
		{
		"key":"",
		"value":"",
		"message": "System error occured"
		}],
    "object": {

    }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.