Advocates

Manage employees who promote your company on social media through the advocacy board.

Advocates are employees or other individuals who promote your company on their personal social media channels. In Oktopost, advocates are system users who are members of an advocacy board. Use these endpoints to retrieve advocates, add new members to boards, and manage advocate participation in your advocacy program.

Advocates require an Oktopost user account to access the advocacy board. When adding advocates, ensure they have been invited to the platform first.

Get Advocate

The boardId parameter is optional. If provided, the response will include Topics and LatestShares.

Example Request

curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001

Example Result

{
  	"Result": true,
  	"Advocate": {
		"Id": "00A000000000000",
		"Created": "2012-03-25 18:48:32",
		"Modified": "2018-09-26 13:27:55",
		"Status": "active",
		"Name": "Liad Guez",
		"FirstName": "Liad",
		"LastName": "Guez",
		"Email": "liad@oktopost.com",
		"PictureUrl": null,
		"LastBoardLogin": "2018-09-12 17:18:42",
		"Profiles": [
			{
				"Id": "003-001000000000000-10795428XXXXXXXXX",
				"Created": "2015-10-26 21:02:30",
				"Name": "Oktopost's Twitter",
				"Status": "valid",
				"Network": "Twitter",
				"ImageLink": "valid",
				"NetworkUsername": "oktopost"
			}
		],
		"BoardIds": [
			"brd000000000001"
		],
		"Topics": [
			"tpc000000000001"
		],
		"LatestShares": [
			{
				"Id": "004000000000000",
				"Created": "2018-09-12 18:29:42",
				"CreatedBy": "00A000000000000",
				"Network": "Twitter",
				"CredentialId": "003-001000000000000-10795428XXXXXXXXX",
				"CredentialImage": "...",
				"Message": "Good Vs. Bad #SocialMedia Management Platforms: 5 Capabilities You Need to Build a Data-Driven #B2BMarketing Team",
				"ImageUrl": "",
				"LinkUrl": "",
				"LinkTitle": "",
				"Description": "",
				"Picture": null,
				"Type": "status-update",
				"Media": null,
				"StartDateTime": "2018-09-12 18:29:38",
				"EndDateTime": "2019-03-13 03:59:59",
				"Status": "complete",
				"Source": "Board",
				"TargetGeo": ""
			}
		]
	}
}

List Advocates

Example Request

curl -i https://api.oktopost.com/v2/advocate?boardId=brd000000000001

Parameters

The activity filters lastSeen, notSeen, and neverSeen require boardId to take effect. Without it, they are silently ignored.

Param	Default	Description
boardId	-	Scope results to a specific board. Enables activity filters and additional response fields (Shares, LastSeen, Role, RoleId, CustomFields, Leaderboards).
email	-	Filter by exact email address
lastSeen	-	Integer (1–365). Return advocates seen within the last N days. Requires boardId.
notSeen	-	Integer (1–365). Return advocates NOT seen within the last N days. Requires boardId.
neverSeen	-	Boolean. Return advocates who have never logged in to the board. Requires boardId.
_page	0	Pagination page number
_count	25	Results per page. Options: 25, 50, 100

Example Result

{
	"Result": true,
	"Items": [
		{
			"Id": "00A000000000001",
			"Name": "Jimmy Mcgill",
			"Email": "saul@goodman.com",
			"PictureUrl": null,
			"LastBoardLogin": "2018-04-15 10:03:11",
			"LastSeen": "2018-09-10 14:22:00",
			"Shares": 12,
			"RoleId": "contributor",
			"Role": "Contributor",
			"CustomFields": [
				{ "FieldId": "cf001", "FieldName": "Department", "Option": {} }
			],
			"Leaderboards": []
		}
	],
	"Total": 89
}

The fields LastSeen, Shares, RoleId, Role, CustomFields, and Leaderboards are only present when boardId is provided. Without it, each item contains only Id, Name, Email, PictureUrl, and LastBoardLogin.

Invite Advocates

Example Request

curl -i https://api.oktopost.com/v2/advocate -X POST \
	-d firstName="Jimmy" \
	-d lastName="Mcgill" \
	-d email="saul@goodman.com" \
	-d boardId="brd000000000001"

Example Result

{  
	"Result": true
}

Delete Advocate

Example Request

curl -i https://api.oktopost.com/v2/advocate/00A000000000001?boardId=brd000000000001 -X DELETE

Example Result

{  
	"Result": true
}

On this page