Recipients
01. List recipients
Get a list of recipients.
GET /int/v1/recipient
Headers - Header
| Name | Type | Description |
|---|---|---|
| Authorization | String | Prefix 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
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates whether the operation was successful. |
| data | Object[] | optionalList of recipient objects. Present when success is true. |
| total | Number | optionalTotal number of recipients. Present when success is true. |
| message | String | optionalError 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
Get the details of an individual recipient.
GET /int/v1/recipient/:email
Headers - Header
| Name | Type | Description |
|---|---|---|
| Authorization | String | Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result). |
Parameters - Parameter
| Name | Type | Description |
|---|---|---|
String | (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
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates whether the operation was successful. |
| data | Object | optionalRecipient objects. Present when success is true. |
| message | String | optionalError 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
Update the details of an individual recipient.
PUT /int/v1/recipient/:email
Headers - Header
| Name | Type | Description |
|---|---|---|
| Authorization | String | Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result). |
Parameters - Parameter
| Name | Type | Description |
|---|---|---|
String | (URL Query Parameter) Recipient email address OR recipient _id value (case insensitive) |
Request Body
| Name | Type | Description |
|---|---|---|
| firstName | String | optional First name / given name |
| lastName | String | optional Last name / surname |
| preferredName | String | optional Preferred name |
| active | Boolean | optional Active recipient flag. If false, recipient cannot login or receive notifications. |
| allowEmail | Boolean | optional Allow recipient to receive email notifications |
| allowSms | Boolean | optional Allow recipient to receive SMS notifications |
| exclusive | Boolean | optional Exclusive (aka private) recipient flag. If true, recipient is not shared with other users. |
| mobile | String | optional Mobile phone number (without country code) |
| mobileCountry | String | optional 1-4 digit international region code for mobile number |
| phone | String | optional Phone number (without country code) |
| phoneCountry | String | optional 1-4 digit international region code for mobile number |
| fax | String | optional Fax number (without country code) |
| faxCountry | String | optional 1-4 digit international region code for fax number |
| title | String | optional Role/job title |
| department | String | optional Organizational department |
| location | String | optional Geographic or physical location |
| orgId | String | optional Organization ID |
| country | String | optional Two letter ISO country code |
| education | Object[] | optional Array of education objects |
| education.school | String | optional Name of school / institution |
| education.degree | String | optional Degree or qualification |
| education.major | String | optional Field of study |
| education.country | String | optional Geographic / political country |
| education.start | String | optional Start date. Format YYYYMMDD |
| education.end | String | optional End date. Format YYYYMMDD |
| employment | Object[] | optional Array of employment objects |
| employment.company | String | optional Name of company / organization |
| employment.employer | String | optional Employer if not a company |
| employment.title | String | optional Job title |
| employment.country | String | optional Geographic / political country |
| employment.start | String | optional Start date. Format YYYYMMDD |
| employment.end | String | optional End date. Format YYYYMMDD |
| certification | Object[] | optional Array of certification objects |
| certification.name | String | optional Name of certification |
| certification.institution | String | optional Issuing institution |
| certification.start | String | optional Start date. Format YYYYMMDD |
| certification.end | String | optional End date. Format YYYYMMDD |
| tags | Object[] | optional Array of tag (custom field) objects |
| tags.key | String | optional Custom field identifier. Prefixed with "z_". |
| tags.value | `String | String[]` |
| skills | String[] | optional List of _id values of skills |
| sfHireDate | String | optional SucessFactors Hire Date. Format YYYYMMDD. |
| reportsTo | String[] | optional List of _id values of recipients who this recipient reports to |
| sfReportsToUserIds | String[] | optional List of SuccessFactors User IDs of recipients who this recipient reports to, |
| supports | String[] | optional List of _id values of recipients who this recipient supports |
| supportedBy | String[] | optional List of _id values of recipients who support this recipient |
| linkedinUrl | String | optional 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
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates whether the operation was successful. |
| data | Object | optionalRecipient objects. Present when success is true. |
| message | String | optionalError 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
Create a new recipient record.
POST /int/v1/recipient
Headers - Header
| Name | Type | Description |
|---|---|---|
| Authorization | String | Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result). |
Request Body
| Name | Type | Description |
|---|---|---|
String | Email address. Must be unique. | |
| firstName | String | First name / given name |
| lastName | String | Last name / surname |
| preferredName | String | optional Preferred name |
| active | Boolean | optional Active recipient flag. If false, recipient cannot login or receive notifications. |
| allowEmail | Boolean | optional Allow recipient to receive email notifications |
| allowSms | Boolean | optional Allow recipient to receive SMS notifications |
| exclusive | Boolean | optional Exclusive (aka private) recipient flag. If true, recipient is not shared with other users. |
| mobile | String | optional Mobile phone number (without country code) |
| mobileCountry | String | optional 1-4 digit international region code for mobile number |
| phone | String | optional Phone number (without country code) |
| phoneCountry | String | optional 1-4 digit international region code for mobile number |
| fax | String | optional Fax number (without country code) |
| faxCountry | String | optional 1-4 digit international region code for fax number |
| title | String | optional Role/job title |
| department | String | optional Organizational department |
| location | String | optional Geographic or physical location |
| orgId | String | optional Organization ID |
| country | String | optional Two letter ISO country code |
| education | Object[] | optional Array of education objects |
| education.school | String | optional Name of school / institution |
| education.degree | String | optional Degree or qualification |
| education.major | String | optional Field of study |
| education.country | String | optional Geographic / political country |
| education.start | String | optional Start date. Format YYYYMMDD |
| education.end | String | optional End date. Format YYYYMMDD |
| employment | Object[] | optional Array of employment objects |
| employment.company | String | optional Name of company / organization |
| employment.employer | String | optional Employer if not a company |
| employment.title | String | optional Job title |
| employment.country | String | optional Geographic / political country |
| employment.start | String | optional Start date. Format YYYYMMDD |
| employment.end | String | optional End date. Format YYYYMMDD |
| certification | Object[] | optional Array of certification objects |
| certification.name | String | optional Name of certification |
| certification.institution | String | optional Issuing institution |
| certification.start | String | optional Start date. Format YYYYMMDD |
| certification.end | String | optional End date. Format YYYYMMDD |
| tags | Object[] | optional Array of tag (custom field) objects |
| tags.key | String | optional Custom field identifier. Prefixed with "z_". |
| tags.value | `String | String[]` |
| skills | String[] | optional List of _id values of skills |
| sfHireDate | String | optional SucessFactors Hire Date. Format YYYYMMDD. |
| reportsTo | String[] | optional List of _id values of recipients who this recipient reports to |
| sfReportsToUserIds | String[] | optional List of SuccessFactors User IDs of recipients who this recipient reports to, |
| supports | String[] | optional List of _id values of recipients who this recipient supports |
| supportedBy | String[] | optional List of _id values of recipients who support this recipient |
| linkedinUrl | String | optional 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
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates whether the operation was successful. |
| data | Object | optionalRecipient objects. Present when success is true. |
| message | String | optionalError 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
Delete recipient record by id
DELETE /int/v1/recipient/:email
Headers - Header
| Name | Type | Description |
|---|---|---|
| Authorization | String | Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result). |
Parameters - Parameter
| Name | Type | Description |
|---|---|---|
String | (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
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates whether the operation was successful. |
| message | String | optionalError 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"
}