Campaign group

Method: get

Authorization is required. Campaign groups hold a list of subscribers that need to receive the campaign's email.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{groupId}

Parameters

property value description
groupId integer The campaign group's ID

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": "Nisi proident tempor cillum sint duis eu elit dolor Lorem amet qui officia occaecat.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": {},
  "object": {
    "id": 2,
    "type": "campaignGroup",
    "name": "Campaign group #2 name",
    "description": "Campaign group #2 description",
    "group": {
      "id": "83acbf0f-b920-4ecb-a61e-e85bbfaaa52f",
      "name": "ea",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "allowPublicSubscription": true,
    "subscribersCount": 12,
    "unSubscribedCount": 2,
    "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 integer the id of the record
name string The campaign group name
description string Some words of what is the purpose of this group
group object some common properties of the group in which the record was created: id, name, slug, thumbUrl, url (of the group home page)
allowPublicSubscription boolean whether people can openly subscribe to this group
subscribersCount integer how many subscribers the group has
unSubscribedCount integer how many of the subscribers clicked the unsubscribe link

Method: list

Authorization is required. Campaign groups hold a list of subscribers that need to receive the campaign's email.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/list/{groupId}?offset={offset}&pageSize={pageSize}

Parameters

property value description
groupId guid The campaign's group 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

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": "Esse anim incididunt duis nostrud veniam nisi ut non in duis dolor cupidatat enim.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": {},
  "object": {
    "offset": 0,
    "groups": [
      {
        "id": 1,
        "type": "campaignGroup",
        "name": "Campaign group #1 name",
        "description": "Campaign group #1 description",
        "group": {
          "id": "83acbf0f-b920-4ecb-a61e-e85bbfaaa52f",
          "name": "ea",
          "slug": "Home",
          "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
          "url": "http://demo.hivesocialnow.com/Home/"
        },
        "allowPublicSubscription": false,
        "subscribersCount": 12,
        "unSubscribedCount": 2,
        "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 integer the id of the record
name string The campaign group name
description string Some words of what is the purpose of this group
group object some common properties of the group in which the record was created: id, name, slug, thumbUrl, url (of the group home page)
allowPublicSubscription boolean whether people can openly subscribe to this group
subscribersCount integer how many subscribers the group has
unSubscribedCount integer how many of the subscribers clicked the unsubscribe link

Method: create

Authorization is required.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group

Parameters

Do not supply a request parameters with this method.

Request body

property value description
groupId guid In which group to create the record
name string The campaign group name
description string Some words of what is the purpose of this group
allowPublicSubscription boolean whether people can openly subscribe to this group

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": [
    {
      "key": "name",
      "value": "",
      "message": "name cannot be blank"
    }
  ],
  "object": {
    "id": 2,
    "type": "campaignGroup",
    "name": "Campaign group #2 name 111",
    "description": "Campaign group #2 description",
    "group": {
      "id": "83acbf0f-b920-4ecb-a61e-e85bbfaaa52f",
      "name": "ea",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "allowPublicSubscription": false,
    "subscribersCount": 12,
    "unSubscribedCount": 2,
    "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) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The object that caused the validation errors or that was created. Have in mind that, if the server requires string trimming or data manipulation after the user submission, it is applied in this object. In this way the returned object can differe from the posted one.

Method: update

Authorization is required.

Request

HTTP request

PUT https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}

Parameters

property value description
emailGroupId integer In id of the updated record

Request body

property value description
name string The campaign group name
description string Some words of what is the purpose of this group
allowPublicSubscription boolean whether people can openly subscribe to this group

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": [
    {
      "key": "name",
      "value": "",
      "message": "name cannot be blank"
    }
  ],
  "object": {
    "id": 2,
    "type": "campaignGroup",
    "name": "Campaign group #2 name 111",
    "description": "Campaign group #2 description",
    "group": {
      "id": "83acbf0f-b920-4ecb-a61e-e85bbfaaa52f",
      "name": "ea",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "allowPublicSubscription": false,
    "subscribersCount": 12,
    "unSubscribedCount": 2,
    "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) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The object that caused the validation errors or the object that was updated. Have in mind that, if the server requires string trimming or data manipulation after the user submission, it is applied in this object. In this way the returned object can differe from the posted one.

Method: delete

Authorization is required.

Request

HTTP request

DELETE https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}

Parameters

property value description
emailGroupId 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": [
    {
      "key": "name",
      "value": "",
      "message": "name cannot be blank"
    }
  ],
  "object": {
    "id": 2,
    "type": "campaignGroup",
    "name": "Campaign group #2 name 111",
    "description": "Campaign group #2 description",
    "group": {
      "id": "83acbf0f-b920-4ecb-a61e-e85bbfaaa52f",
      "name": "ea",
      "slug": "Home",
      "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
      "url": "http://demo.hivesocialnow.com/Home/"
    },
    "allowPublicSubscription": false,
    "subscribersCount": 12,
    "unSubscribedCount": 2,
    "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: list subscribers

Authorization is required.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/subscribers?offset={offset}&pageSize={pageSize}&filter={filter}&target={target}

Parameters

property value description
emailGroupId integer In id of the deleted record
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 Looks into the target data (subscriber email or name) and displays any matched records
target string Chooses what subscriber's record field to match with the filter. The alternatives are:
  • email - Subscriber's email address
  • name - Subscriber's first and second names

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": "Esse anim incididunt duis nostrud veniam nisi ut non in duis dolor cupidatat enim.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": {},
  "object": {
    "offset": 11,
    "subscribers": [
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077172",
        "email": "joe@doe.com",
        "type": "subscriber",
        "firstName": "Joe",
        "lastName": "Doe",
        "registered": true,
        "accessWarnings": []
      },
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077173",
        "email": "jane@doe.com",
        "type": "subscriber",
        "firstName": "Jane",
        "lastName": "Doe",
        "registered": false,
        "accessWarnings": []
      },
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077174",
        "email": "joe11@doe.com",
        "type": "subscriber",
        "firstName": "Joe11",
        "lastName": "Doe11",
        "registered": true,
        "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 user's hivesocial account id. Zero guid if the subscriber is not an user of the system.
email string The target email
firstName string The first name of the subscriber
lastName string The last name of the subscriber
registered boolean Whether the subscriber is a registered user.

Method: list unsubscribed

Authorization is required. List all subscribers that clicked on the unsubscribe link and will not receive any of the future emails.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/unsubscribed?offset={offset}&pageSize={pageSize}

Parameters

property value description
emailGroupId integer In id of the deleted record
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

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": "Esse anim incididunt duis nostrud veniam nisi ut non in duis dolor cupidatat enim.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": {},
  "object": {
    "offset": 11,
    "subscribers": [
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077172",
        "email": "joe@doe.com",
        "type": "subscriber",
        "firstName": "Joe",
        "lastName": "Doe",
        "registered": true,
        "accessWarnings": []
      },
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077173",
        "email": "jane@doe.com",
        "type": "subscriber",
        "firstName": "Jane",
        "lastName": "Doe",
        "registered": false,
        "accessWarnings": []
      },
      {
        "id": "1DD6C5D7-5F92-4F3F-B9A5-35E55F077174",
        "email": "joe11@doe.com",
        "type": "subscriber",
        "firstName": "Joe11",
        "lastName": "Doe11",
        "registered": true,
        "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 user's hivesocial account id. Zero guid if the subscriber is not an user of the system.
email string The target email
firstName string The first name of the subscriber
lastName string The last name of the subscriber
registered boolean Whether the subscriber is a registered user.

Method: list available for import

Authorization is required. List existing members that can be imported into the campaign group.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/user-for-import?offset={offset}&pageSize={pageSize}&filter={filter}&role={role}&target={target}

Parameters

property value description
emailGroupId integer In id of the deleted record
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 Looks into the target data (subscriber email or name) and displays any matched records
role integer The id of the member role, which you need the subscriber to be enrolled in. The alternatives are:
  • 0 - All roles
  • 1 - regular
  • 2 - member
  • 3 - moderator
  • 4 - administrator
target string Chooses what subscriber's record field to match with the filter. The alternatives are:
  • email - Subscriber's email address
  • name - Subscriber's first and second names

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": "Qui Lorem velit laborum aute duis sunt.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": {},
  "object": {
    "offset": "bec18635-4897-4e41-8012-8658e007df7e",
    "members": [
      {
        "id": "bec18635-4897-4e41-8012-8658e007df7e",
        "type": "member",
        "alias": "in consequat",
        "email": "lottrobinson@isoplex.com",
        "photoUrl": "/HS4/ContentServer/avatar/786499b2-1499-48ac-ab7e-09b1247361c9.jpg",
        "memberSince": "2014-03-03T23:20:23Z",
        "roleId": 5,
        "roleName": "administrator",
        "blocked": false,
        "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 user's hivesocial account id. Zero guid if the subscriber is not an user of the system.
alias string The hivesocial alias of the member. In most cases the first and the second name.
email string The target email
photoUrl string the url of the member's photo image
memberSince date When the user became a member of the campaign's community group in ISO 8601 format and UTC time zone.
roleId integer The Id of the current member's role of the user.
  • 0 - All roles
  • 1 - regular
  • 2 - member
  • 3 - moderator
  • 4 - administrator
roleName string Human readable role name.
blocked boolean Is the member account disabled

Method: import subscriber

Authorization is required. Add an existing group's member to the subscribers list

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/subscribers/add

Parameters

property value description
emailGroupId integer In id of the deleted record

Request body

property value description
userId guid The member's HiveSocial account Id

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": {},
"errors":[
	{
	"key":"name",
	"value":"",
	"message": "name cannot be blank"
	}],
"object": {}
}

The general response properties are described on the Response format page.

Method: remove subscriber

Authorization is required. Removes an existing group's member from the subscribers list

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/subscribers/remove

Parameters

property value description
emailGroupId integer In id of the deleted record

Request body

property value description
userId guid The member's HiveSocial account Id

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": {},
"errors":[
	{
	"key":"name",
	"value":"",
	"message": "name cannot be blank"
	}],
"object": {}
}

The general response properties are described on the Response format page.

Method: evaluate import csv

Authorization is required. Evaluates a csv file prepared for import and in the format: email, first name, last name. New line for record separator. It matches it to the current campaign group's subscribers and produces a result, which is used later by the next method for the actual import.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/evaluate-import

Parameters

property value description
emailGroupId integer In id of the email group

Request body

property value description
csvPath string Url to the CSV file that needs to be evaluated. The file should be in the format: email, first name, last name. New line for record separator.

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": {
      "csvPath": "http://demo.hivesocialnow.com/ClientFiles/bc7fbf51-7930-4550-98b0-6a3ff6111ebe/users.csv"
    },
    "output": [
      {
        "type": "campaignImportRow",
        "email": "lottrobinson@isoplex.com",
        "firstName": "lott",
        "lastName": "robinson",
        "resultId": 1,
        "resultName": "New subscriber"
      },
      {
        "type": "campaignImportRow",
        "email": "besn@isoplex.com",
        "firstName": "besn",
        "lastName": "besn",
        "resultId": 2,
        "resultName": "Registered email"
      },
      {
        "type": "campaignImportRow",
        "email": "office@isoplex.com",
        "firstName": "office",
        "lastName": "company",
        "resultId": 3,
        "resultName": "Already subscribed"
      },
      {
        "type": "campaignImportRow",
        "email": "mary@isoplex.com11",
        "firstName": "mary",
        "lastName": "mary",
        "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
input object Has a csvPath property, which is the provided for evaluation URL of the CSV file.
output List (object) List of the CSV file records but evaluated and with provided possible result of the import. The most important property of these objects is the resultId. It alternates as follows:
  • 1 - New subscriber - Record will be imported as a new subscriber of this campaign group
  • 2 - Registered email - This email is associated with an already registered user. This user will be added as a subscriber
  • 3 - Already subscribed - Not processed! This email is already subscribed
  • 4 - Invalid email - Not processed! The email is not in a valid format
  • 5 - Unsubscribed - Not processed! The email is already unsubscribed

Method: bulk import

Authorization is required. Bulk imports a list of records as campaign group subscribers.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/campaign/group/{emailGroupId}/bulk-import

Parameters

property value description
emailGroupId integer In id of the email group

Request body

property value description
records List (object) List of record objects scheduled for import. The record object properties are:
  • email - subscriber email
  • firstName - subscriber first name
  • lastName - subscriber last name

Response

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

{
    "success": false,
    "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.