API Communication Value Changes

Posted By: Tracy Mazelin on November 2, 2012

As many of you know, earlier this year we began to streamline the types of communication values available in Fellowship One.  More information about the project can be found on our community blog here, and also on the developer blog here.

As a result of this project, we enhanced functionality around communication values via our API, and last week we pushed the enhancements to production.  You, our developer community, responded very well to the changes.  You rock!

Here is a review of the changes and enhancements:

Reduction in Communication Types.

GET https:// demo.fellowshiponeapi.com/v1/communications/communicationtypes

Response:

{
"communicationTypes":{
"communicationType":[
{
"@array":"true",
"@id":"1",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/1",
"@generalType":"Telephone",
"name":"Home Phone"
},
{
"@array":"true",
"@id":"2",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/2",
"@generalType":"Telephone",
"name":"Work Phone"
},
{
"@array":"true",
"@id":"3",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/3",
"@generalType":"Telephone",
"name":"Mobile Phone"
},
{
"@array":"true",
"@id":"138",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/138",
"@generalType":"Telephone",
"name":"Emergency Phone"
},
{
"@array":"true",
"@id":"5",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/5",
"@generalType":"Email",
"name":"Home Email"
},
{
"@array":"true",
"@id":"4",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/4",
"@generalType":"Email",
"name":"Email"
},
{
"@array":"true",
"@id":"6",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/6",
"@generalType":"Email",
"name":"InFellowship Login"
},
{
"@array":"true",
"@id":"102",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/102",
"@generalType":"Web",
"name":"Web Address"
},
{
"@array":"true",
"@id":"201",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/201",
"@generalType":"SocialMedia",
"name":"Facebook"
},
{
"@array":"true",
"@id":"203",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/203",
"@generalType":"SocialMedia",
"name":"Twitter"
},
{
"@array":"true",
"@id":"202",
"@uri":"https://demo.fellowshiponeapi.com/v1/Communications/CommunicationTypes/202",
"@generalType":"SocialMedia",
"name":"Linkedin"
}
]
}
}

The list of available communication types has been reduced.  It is important to note that the labels for the communication values in portal will change depending on how many communication values exist in a record.  Example:

image

Because this individual has an inFellowship ID, the individual email address is listed as ‘Alternate’.  If no inFellowship ID existed, that same value would be labeled ‘Personal’.  Via the API, the individual email address is always Type 4 - Email, no matter what the label says in portal.  A household email address is always Type 5 - Home Email.  An inFellowship Communication Value is always Type 6.

The Listed Node has been Removed and Replaced with Preferred

GET
https://demo.fellowshiponeapi.com/v1/People/17173182/communications/new 

Response

{"communication":{
"@id":"",
"@uri":"",
"household":{
"@id":"11695333",
"@uri":"https://demo.fellowshiponeapi.com/v1/Households/11695333"},
"person":{
"@id":"17173182",
"@uri":"https://demo.fellowshiponeapi.com/v1/People/17173182"},
"communicationType":{"@id":"",
"@uri":"",
"name":null},
"communicationGeneralType":null,
"communicationValue":null,
"searchCommunicationValue":null,
"preferred":null,
"communicationComment":null,
"createdDate":null,
"lastUpdatedDate":null}}

Remember, it is ALWAYS a good idea to call ‘New’ before ‘Create’.  That way, you will always receive the correct model for the resource from the server:

‘Unsubscribed’ Node in v2 of a person Resource

Instead of versioning the entire people realm for a minor change like this, the unsubscribed value can be obtained by passing a custom content-type header.  This allows enhanced functionality without breaking current compatibility.

Given

GET https://demo.fellowshiponeapi.com/v1/People/17173182
Content-Type: application/vnd.fellowshiponeapi.com.people.people.v2+json

Returns:

...
"firstRecord":"2007-11-05T23:12:24",
"lastMatchDate":"2012-10-25T11:48:01",
"unsubscribed":"false",
"createdDate":"2007-11-05T23:12:24",
"lastUpdatedDate":"2012-10-25T11:48:01"

This node will not exist if the custom content-type is not passed.

That’s all!  Again, we thank you for being such an awesome developer community and look forward to hearing about the new and exciting ways you are consuming our API to maximize ministry and minimize administration.  Nom. Nom. Nom!

Posted In: API, News, Tips,

Comments:
No one has commented yet. Be the first!
Now You Comment

Remember my personal information.   |   Notify me of follow-up comments.