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

Invite a new advocate by email, or re-invite an existing board advocate by userId. Provide either email or userId, not both.

Invalid input returns HTTP 400. Exceeding the board advocate seat limit returns an Advocacy RateLimit error.

Parameters

Param	Default	Description
boardId	-	Required. Board to invite the advocate to.
email	-	Required for a new invite. Mutually exclusive with userId.
userId	-	Required for a re-invite. Must already be an advocate on the board. Mutually exclusive with email.
firstName	-	Required for a new invite (with email). Max 32 characters.
lastName	-	Required for a new invite (with email). Max 32 characters.
role	Based on the board's default role.	Board role for the new invite. Ignored for re-invite.
message	-	Optional note attached to the invite. Max 1024 characters.

Example Request — New Invite

curl -i https://api.oktopost.com/v2/advocate -X POST \
	-d boardId="brd000000000001" \
	-d firstName="Jimmy" \
	-d lastName="Mcgill" \
	-d email="saul@goodman.com" \
	-d role="contributor" \
	-d message="Welcome to the advocacy board"

Example Request — Re-invite

curl -i https://api.oktopost.com/v2/advocate -X POST \
	-d boardId="brd000000000001" \
	-d userId="00A000000000001" \
	-d message="Reminder to join the board"

Example Result

{
	"Result": true,
	"Users": [
		{
			"Id": "00A000000000001",
			"Name": "Jimmy Mcgill",
			"Email": "saul@goodman.com"
        }
	]
}

Bulk Invite Advocates

Invite or re-invite up to 100 advocates in one request. Valid entries are processed; invalid entries are returned in Errors without failing the whole request.

This endpoint accepts POST only. Other methods return HTTP 405. Requests with more than 100 entries return HTTP 400. Exceeding the board seat limit returns an Advocacy RateLimit error for the whole request.

Parameters

Param	Default	Description
boardId	-	Required. Board to invite advocates to.
users	-	Required. Array of 1–100 invite entries (see below).
message	-	Optional note applied to all invites and re-invites in the batch. Max 1024 characters.

users[] entry

Each entry must include either email or userId, not both.

Param	Default	Description
email	-	New invite. Requires firstName and lastName.
userId	-	Re-invite an existing board advocate.
firstName	-	Required with email.
lastName	-	Required with email.
role	Based on the board's default role.	Board role for a new invite.

Example Request

curl -i https://api.oktopost.com/v2/advocate/bulk -X POST \
	-d boardId="brd000000000001" \
	-d message="Welcome to the advocacy board" \
	-d "users[0][userId]=00A000000000001" \
	-d "users[1][email]=user@oktopost.com" \
	-d "users[1][firstName]=user" \
	-d "users[1][lastName]=smith" \
	-d "users[2][email]=bad-email" \
	-d "users[2][firstName]=Bad" \
	-d "users[2][lastName]=Email"

Example Result

{
	"Result": true,
	"Users": [
		{
			"Id": "00A000000000001",
			"Name": "Jimmy Mcgill",
			"Email": "saul@goodman.com"
		},
		{
			"Id": "00A000000000002",
			"Name": "User Smith",
			"Email": "user@oktopost.com"
		}
	],
	"Errors": [
		{
			"Id": 3,
			"Data": {
				"email": "bad-email",
				"firstName": "Bad",
				"lastName": "Email"
			},
			"ErrorField": "email",
			"ErrorMessage": "Invalid email address"
		}
	]
}

Each error Id is the 1-based index of the entry in users. Successful invites and re-invites appear in Users (Id, Name, Email).

Delete Advocate

Example Request

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

Example Result

{  
	"Result": true
}

On this page