Skip to main content

Recipients

01. List recipients

Back to top

Get a list of recipients.

GET /int/v1/recipient

Headers - Header

NameTypeDescription
AuthorizationStringPrefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
-X GET https://<url>/int/v1/recipient

Javascript Example:

(async (url, token) => {

try{
const response = await(
await fetch(
`${url}/int/v1/recipient`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
}
)
).json();
console.log("API response:", response);
}catch(error){
console.error("API error:", error);
}
})(process.env.URL, process.env.TOKEN);

Success response

Success response - Success 200

NameTypeDescription
successBooleanIndicates whether the operation was successful.
dataObject[]optionalList of recipient objects. Present when success is true.
totalNumberoptionalTotal number of recipients. Present when success is true.
messageStringoptionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
"success":true,
"data":[
{
"_id": "60f4aeb09279e27183c0a9da",
"aDate": "2021-07-18T22:44:00.989Z",
"mDate": "2024-04-29T01:52:26.962Z",
"email": "john@communic8.com",
"active": true,
"registered": true,
"suppressed": false,
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"formalName": "John Smith",
"mobile": "",
"phone": "",
"country": "",
"fax": "",
"phoneCountry": "",
"faxCountry": "",
"mobileCountry": "",
"phoneFull": "",
"faxFull": "",
"mobileFull": "",
"nameIsUnicode": false,
"mobileSendable": false,
"photoFileId": "62a299850049992e5b91c106",
"tags": [
{
"key": "z_customField",
"value": "Foo",
"_id": "630469fd98ed1f21a621a4e6"
}
],
"agreementLog": {
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"history": [
{
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"_id": "5f2ca8e101579077b3594f96"
}
]
},
"agreement": {
"history": []
},
"lastAccessDate": "2024-05-13T05:27:34.702Z",
"allowEmail": true,
"allowSms": false,
"allowCommentReplyMobileNotify": true,
"skills": [],
"availability": [],
"exclusive": false,
"sharedUsers": [],
"sharedGroups": [],
"status": "99",
"ownerId": "60f4aeb09279e27183c0a9da",
"sfReportsToUserIds": [],
"followingIds": [
"635b559a1da40d7f27ea0f14"
],
"reportsTo": [],
"supports": [],
"supportedBy": [
"6205aeba97496a2c8e880d91"
],
"education": [],
"employment": [],
"certification": [],
"notes": [],
"contactMeCount": 4,
"appPermission": true,
"appPermissionIndex": "20230117171101",
"online": true,
"timezone": "Australia/Brisbane",
"admin": true,
"activeConsole": true,
"onlineConsole": true,
"lastAccessDateConsole": "2024-01-22T01:31:31.952Z",
"legacyPbUserId": "5f2ca7e0ff6d3377ce1743d2",
"clientAgreementLog": {
"history": []
},
"appStorage": {
"recentObjects": []
},
"noDefaultRole": false,
"roles": [],
"groups": [
"5a0370e7c224ab5ff3337aee",
"65bc71292c8c5205c64a8441"
],
"notifyMyChanges": false,
"notifyCampaignOwner": false,
"notifyCampaignMember": false,
"_type": "pb_c_c8_console_user",
"__v": 20,
"hasChosenPhoto": false,
"sfUserId": "700001",
"sfUserIdLower": "700001",
"delegators": [],
"sfUserName": "700001"
}
],
"total": 1
}

Success response example - Error:

HTTP/1.1 200 OK
{
"success":false,
"message":"Illegal parameters"
}

02. Get a recipient

Back to top

Get the details of an individual recipient.

GET /int/v1/recipient/:email

Headers - Header

NameTypeDescription
AuthorizationStringPrefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

NameTypeDescription
emailString(URL Query Parameter) Recipient email address OR recipient _id value (case insensitive)

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
-X GET https://<url>/int/v1/recipient/<email>

Javascript Example:

(async (url, token, email) => {

try{
const response = await(
await fetch(
`${url}/int/v1/recipients/${email}`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${token}`
}
}
)
).json();
console.log("API response:", response);
}catch(error){
console.error("API error:", error);
}
})(process.env.URL, process.env.TOKEN, process.env.EMAIL);

Success response

Success response - Success 200

NameTypeDescription
successBooleanIndicates whether the operation was successful.
dataObjectoptionalRecipient objects. Present when success is true.
messageStringoptionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
"success":true,
"data":{
"_id": "60f4aeb09279e27183c0a9da",
"aDate": "2021-07-18T22:44:00.989Z",
"mDate": "2024-04-29T01:52:26.962Z",
"email": "john@communic8.com",
"active": true,
"registered": true,
"suppressed": false,
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"formalName": "John Smith",
"mobile": "",
"phone": "",
"country": "",
"fax": "",
"phoneCountry": "",
"faxCountry": "",
"mobileCountry": "",
"phoneFull": "",
"faxFull": "",
"mobileFull": "",
"nameIsUnicode": false,
"mobileSendable": false,
"photoFileId": "62a299850049992e5b91c106",
"tags": [
{
"key": "z_customField",
"value": "Foo",
"_id": "630469fd98ed1f21a621a4e6"
}
],
"agreementLog": {
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"history": [
{
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"_id": "5f2ca8e101579077b3594f96"
}
]
},
"agreement": {
"history": []
},
"lastAccessDate": "2024-05-13T05:27:34.702Z",
"allowEmail": true,
"allowSms": false,
"allowCommentReplyMobileNotify": true,
"skills": [],
"availability": [],
"exclusive": false,
"sharedUsers": [],
"sharedGroups": [],
"status": "99",
"ownerId": "60f4aeb09279e27183c0a9da",
"sfReportsToUserIds": [],
"followingIds": [
"635b559a1da40d7f27ea0f14"
],
"reportsTo": [],
"supports": [],
"supportedBy": [
"6205aeba97496a2c8e880d91"
],
"education": [],
"employment": [],
"certification": [],
"notes": [],
"contactMeCount": 4,
"appPermission": true,
"appPermissionIndex": "20230117171101",
"online": true,
"timezone": "Australia/Brisbane",
"admin": true,
"activeConsole": true,
"onlineConsole": true,
"lastAccessDateConsole": "2024-01-22T01:31:31.952Z",
"legacyPbUserId": "5f2ca7e0ff6d3377ce1743d2",
"clientAgreementLog": {
"history": []
},
"appStorage": {
"recentObjects": []
},
"noDefaultRole": false,
"roles": [],
"groups": [
"5a0370e7c224ab5ff3337aee",
"65bc71292c8c5205c64a8441"
],
"notifyMyChanges": false,
"notifyCampaignOwner": false,
"notifyCampaignMember": false,
"_type": "pb_c_c8_console_user",
"__v": 20,
"hasChosenPhoto": false,
"sfUserId": "700001",
"sfUserIdLower": "700001",
"delegators": [],
"sfUserName": "700001"
}
}

Success response example - Error:

HTTP/1.1 200 OK
{
"success":false,
"message":"Recipient Not Found"
}

03. Update a recipient

Back to top

Update the details of an individual recipient.

PUT /int/v1/recipient/:email

Headers - Header

NameTypeDescription
AuthorizationStringPrefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

NameTypeDescription
emailString(URL Query Parameter) Recipient email address OR recipient _id value (case insensitive)

Request Body

NameTypeDescription
firstNameStringoptional First name / given name
lastNameStringoptional Last name / surname
preferredNameStringoptional Preferred name
activeBooleanoptional Active recipient flag. If false, recipient cannot login or receive notifications.
allowEmailBooleanoptional Allow recipient to receive email notifications
allowSmsBooleanoptional Allow recipient to receive SMS notifications
exclusiveBooleanoptional Exclusive (aka private) recipient flag. If true, recipient is not shared with other users.
mobileStringoptional Mobile phone number (without country code)
mobileCountryStringoptional 1-4 digit international region code for mobile number
phoneStringoptional Phone number (without country code)
phoneCountryStringoptional 1-4 digit international region code for mobile number
faxStringoptional Fax number (without country code)
faxCountryStringoptional 1-4 digit international region code for fax number
titleStringoptional Role/job title
departmentStringoptional Organizational department
locationStringoptional Geographic or physical location
orgIdStringoptional Organization ID
countryStringoptional Two letter ISO country code
educationObject[]optional Array of education objects
education.schoolStringoptional Name of school / institution
education.degreeStringoptional Degree or qualification
education.majorStringoptional Field of study
education.countryStringoptional Geographic / political country
education.startStringoptional Start date. Format YYYYMMDD
education.endStringoptional End date. Format YYYYMMDD
employmentObject[]optional Array of employment objects
employment.companyStringoptional Name of company / organization
employment.employerStringoptional Employer if not a company
employment.titleStringoptional Job title
employment.countryStringoptional Geographic / political country
employment.startStringoptional Start date. Format YYYYMMDD
employment.endStringoptional End date. Format YYYYMMDD
certificationObject[]optional Array of certification objects
certification.nameStringoptional Name of certification
certification.institutionStringoptional Issuing institution
certification.startStringoptional Start date. Format YYYYMMDD
certification.endStringoptional End date. Format YYYYMMDD
tagsObject[]optional Array of tag (custom field) objects
tags.keyStringoptional Custom field identifier. Prefixed with "z_".
tags.value`StringString[]`
skillsString[]optional List of _id values of skills
sfHireDateStringoptional SucessFactors Hire Date. Format YYYYMMDD.
reportsToString[]optional List of _id values of recipients who this recipient reports to
sfReportsToUserIdsString[]optional List of SuccessFactors User IDs of recipients who this recipient reports to,
supportsString[]optional List of _id values of recipients who this recipient supports
supportedByString[]optional List of _id values of recipients who support this recipient
linkedinUrlStringoptional LinkedIn profile URL

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-X PUT https://<url>/int/v1/recipient/<email> \
-d '{"preferredName": "Johnny"}'

Javascript Example:

(async (url, token, email) => {

try{
const response = await(
await fetch(
`${url}/int/v1/recipients/${email}`,
{
method: "PUT",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(
{
preferredName: "Johnny"
}
)
}
)
).json();
console.log("API response:", response);
}catch(error){
console.error("API error:", error);
}
})(process.env.URL, process.env.TOKEN, process.env.EMAIL);

Success response

Success response - Success 200

NameTypeDescription
successBooleanIndicates whether the operation was successful.
dataObjectoptionalRecipient objects. Present when success is true.
messageStringoptionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
"success":true,
"data":{
"_id": "60f4aeb09279e27183c0a9da",
"aDate": "2021-07-18T22:44:00.989Z",
"mDate": "2024-04-29T01:52:26.962Z",
"email": "john@communic8.com",
"active": true,
"registered": true,
"suppressed": false,
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"formalName": "John Smith",
"mobile": "",
"phone": "",
"country": "",
"fax": "",
"phoneCountry": "",
"faxCountry": "",
"mobileCountry": "",
"phoneFull": "",
"faxFull": "",
"mobileFull": "",
"nameIsUnicode": false,
"mobileSendable": false,
"photoFileId": "62a299850049992e5b91c106",
"tags": [
{
"key": "z_customField",
"value": "Foo",
"_id": "630469fd98ed1f21a621a4e6"
}
],
"agreementLog": {
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"history": [
{
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"_id": "5f2ca8e101579077b3594f96"
}
]
},
"agreement": {
"history": []
},
"lastAccessDate": "2024-05-13T05:27:34.702Z",
"allowEmail": true,
"allowSms": false,
"allowCommentReplyMobileNotify": true,
"skills": [],
"availability": [],
"exclusive": false,
"sharedUsers": [],
"sharedGroups": [],
"status": "99",
"ownerId": "60f4aeb09279e27183c0a9da",
"sfReportsToUserIds": [],
"followingIds": [
"635b559a1da40d7f27ea0f14"
],
"reportsTo": [],
"supports": [],
"supportedBy": [
"6205aeba97496a2c8e880d91"
],
"education": [],
"employment": [],
"certification": [],
"notes": [],
"contactMeCount": 4,
"appPermission": true,
"appPermissionIndex": "20230117171101",
"online": true,
"timezone": "Australia/Brisbane",
"admin": true,
"activeConsole": true,
"onlineConsole": true,
"lastAccessDateConsole": "2024-01-22T01:31:31.952Z",
"legacyPbUserId": "5f2ca7e0ff6d3377ce1743d2",
"clientAgreementLog": {
"history": []
},
"appStorage": {
"recentObjects": []
},
"noDefaultRole": false,
"roles": [],
"groups": [
"5a0370e7c224ab5ff3337aee",
"65bc71292c8c5205c64a8441"
],
"notifyMyChanges": false,
"notifyCampaignOwner": false,
"notifyCampaignMember": false,
"_type": "pb_c_c8_console_user",
"__v": 20,
"hasChosenPhoto": false,
"sfUserId": "700001",
"sfUserIdLower": "700001",
"delegators": [],
"sfUserName": "700001"
}
}

Success response example - Error:

HTTP/1.1 200 OK
{
"success":false,
"message":"Recipient Not Found"
}

04. Create new recipient

Back to top

Create a new recipient record.

POST /int/v1/recipient

Headers - Header

NameTypeDescription
AuthorizationStringPrefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Request Body

NameTypeDescription
emailStringEmail address. Must be unique.
firstNameStringFirst name / given name
lastNameStringLast name / surname
preferredNameStringoptional Preferred name
activeBooleanoptional Active recipient flag. If false, recipient cannot login or receive notifications.
allowEmailBooleanoptional Allow recipient to receive email notifications
allowSmsBooleanoptional Allow recipient to receive SMS notifications
exclusiveBooleanoptional Exclusive (aka private) recipient flag. If true, recipient is not shared with other users.
mobileStringoptional Mobile phone number (without country code)
mobileCountryStringoptional 1-4 digit international region code for mobile number
phoneStringoptional Phone number (without country code)
phoneCountryStringoptional 1-4 digit international region code for mobile number
faxStringoptional Fax number (without country code)
faxCountryStringoptional 1-4 digit international region code for fax number
titleStringoptional Role/job title
departmentStringoptional Organizational department
locationStringoptional Geographic or physical location
orgIdStringoptional Organization ID
countryStringoptional Two letter ISO country code
educationObject[]optional Array of education objects
education.schoolStringoptional Name of school / institution
education.degreeStringoptional Degree or qualification
education.majorStringoptional Field of study
education.countryStringoptional Geographic / political country
education.startStringoptional Start date. Format YYYYMMDD
education.endStringoptional End date. Format YYYYMMDD
employmentObject[]optional Array of employment objects
employment.companyStringoptional Name of company / organization
employment.employerStringoptional Employer if not a company
employment.titleStringoptional Job title
employment.countryStringoptional Geographic / political country
employment.startStringoptional Start date. Format YYYYMMDD
employment.endStringoptional End date. Format YYYYMMDD
certificationObject[]optional Array of certification objects
certification.nameStringoptional Name of certification
certification.institutionStringoptional Issuing institution
certification.startStringoptional Start date. Format YYYYMMDD
certification.endStringoptional End date. Format YYYYMMDD
tagsObject[]optional Array of tag (custom field) objects
tags.keyStringoptional Custom field identifier. Prefixed with "z_".
tags.value`StringString[]`
skillsString[]optional List of _id values of skills
sfHireDateStringoptional SucessFactors Hire Date. Format YYYYMMDD.
reportsToString[]optional List of _id values of recipients who this recipient reports to
sfReportsToUserIdsString[]optional List of SuccessFactors User IDs of recipients who this recipient reports to,
supportsString[]optional List of _id values of recipients who this recipient supports
supportedByString[]optional List of _id values of recipients who support this recipient
linkedinUrlStringoptional LinkedIn profile URL

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-X POST https://<url>/int/v1/recipient \
-d '{"firstName": "John", "lastName": "Smith", "email": "john@communic8.com"}'

Javascript Example:

(async (url, token) => {

try{
const response = await(
await fetch(
`${url}/int/v1/recipients`,
{
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(
{
firstName: "John",
lastName: "Smith",
email: "john@communic8.com"
}
)
}
)
).json();
console.log("API response:", response);
}catch(error){
console.error("API error:", error);
}
})(process.env.URL, process.env.TOKEN);

Success response

Success response - Success 200

NameTypeDescription
successBooleanIndicates whether the operation was successful.
dataObjectoptionalRecipient objects. Present when success is true.
messageStringoptionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
"success":true,
"data":{
"_id": "60f4aeb09279e27183c0a9da",
"aDate": "2021-07-18T22:44:00.989Z",
"mDate": "2024-04-29T01:52:26.962Z",
"email": "john@communic8.com",
"active": true,
"registered": true,
"suppressed": false,
"firstName": "John",
"lastName": "Smith",
"displayName": "John Smith",
"formalName": "John Smith",
"mobile": "",
"phone": "",
"country": "",
"fax": "",
"phoneCountry": "",
"faxCountry": "",
"mobileCountry": "",
"phoneFull": "",
"faxFull": "",
"mobileFull": "",
"nameIsUnicode": false,
"mobileSendable": false,
"photoFileId": "62a299850049992e5b91c106",
"tags": [
{
"key": "z_customField",
"value": "Foo",
"_id": "630469fd98ed1f21a621a4e6"
}
],
"agreementLog": {
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"history": [
{
"agreeTime": "2020-08-07T01:05:37.883Z",
"version": 2,
"_id": "5f2ca8e101579077b3594f96"
}
]
},
"agreement": {
"history": []
},
"lastAccessDate": "2024-05-13T05:27:34.702Z",
"allowEmail": true,
"allowSms": false,
"allowCommentReplyMobileNotify": true,
"skills": [],
"availability": [],
"exclusive": false,
"sharedUsers": [],
"sharedGroups": [],
"status": "99",
"ownerId": "60f4aeb09279e27183c0a9da",
"sfReportsToUserIds": [],
"followingIds": [
"635b559a1da40d7f27ea0f14"
],
"reportsTo": [],
"supports": [],
"supportedBy": [
"6205aeba97496a2c8e880d91"
],
"education": [],
"employment": [],
"certification": [],
"notes": [],
"contactMeCount": 4,
"appPermission": true,
"appPermissionIndex": "20230117171101",
"online": true,
"timezone": "Australia/Brisbane",
"admin": true,
"activeConsole": true,
"onlineConsole": true,
"lastAccessDateConsole": "2024-01-22T01:31:31.952Z",
"legacyPbUserId": "5f2ca7e0ff6d3377ce1743d2",
"clientAgreementLog": {
"history": []
},
"appStorage": {
"recentObjects": []
},
"noDefaultRole": false,
"roles": [],
"groups": [
"5a0370e7c224ab5ff3337aee",
"65bc71292c8c5205c64a8441"
],
"notifyMyChanges": false,
"notifyCampaignOwner": false,
"notifyCampaignMember": false,
"_type": "pb_c_c8_console_user",
"__v": 20,
"hasChosenPhoto": false,
"sfUserId": "700001",
"sfUserIdLower": "700001",
"delegators": [],
"sfUserName": "700001"
}
}

Success response example - Error:

HTTP/1.1 200 OK
{
"success":false,
"message":"The email address john.smith@communic8.com is already in use by another account"
}

05. Delete recipient record

Back to top

Delete recipient record by id

DELETE /int/v1/recipient/:email

Headers - Header

NameTypeDescription
AuthorizationStringPrefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

NameTypeDescription
emailString(URL Parameter) id Recipient email address or id (case insensitive)

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-X DELETE https://<url>/int/v1/recipient/<email>

Javascript Example:

(async (url, token, email) => {

try{
const response = await(
await fetch(
`${url}/int/v1/recipients/${email}`,
{
method: "DELETE",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
}
}
)
).json();
console.log("API response:", response);
}catch(error){
console.error("API error:", error);
}
})(process.env.URL, process.env.TOKEN, process.env.EMAIL);

Success response

Success response - Success 200

NameTypeDescription
successBooleanIndicates whether the operation was successful.
messageStringoptionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
"success":true
}

Success response example - Error:

HTTP/1.1 200 OK
{
"success":false,
"message":"Recipient Not Found"
}