Example: Changing Current Portal Group

Portal Groups are a feature available for VOW users with a Portal account. They must be managed by an agent, but once created, these groups allow consumers to share a work space, managing resources such as Listing Carts, Saved Searches and News Feeds together.

  1. Authentication
  2. Checking the current portal group
  3. Viewing portal groups
  4. Changing the current portal groups
  5. Viewing data for the current portal group

Step 1: Authentication

This example expects that you have already obtained an OAuth 2 authorization token to access a user's data. Read more on our OpendID Connect Authentication and OAuth 2 Authorization.

Step 2: Checking the current portal group

As a user with a VOW role, we first want to double check which portal group we are currently associated with. Notice that, in this case, we are not currently associated with any portal group, so API requests to services such as Listing Carts will retrieve the current user's data directly.
$ curl "https://sparkapi.com/v1/portal/groups/current" -H "X-SparkApi-User-Agent: SparkAPIExamples" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} 
{
    "D": {
        "Success": true,
        "Results": []
    }
}

Step 3: Viewing portal groups

Next, we want to retrieve a list of the available portal groups, perhaps to present a user interface to the end user allowing them to select which portal group to work with on subsequent requests. Notice that, in this case, we only have a single option; however, a consumer may be associated with many portal groups.
$ curl "https://sparkapi.com/v1/portal/groups" -H "X-SparkApi-User-Agent: SparkAPIExamples" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} 
{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/portal/groups/20130919194721820379000000",
                "Id": "20130919194721820379000000",
                "ContactId": "20130919194721358470000000",
                "Users": [
                    {
                        "Enabled": true,
                        "ResourceUri": "/v1/contacts/20130919194721358470000000",
                        "Name": "Ozzy Owner",
                        "OfficeId": null,
                        "Id": "20130919194721358470000000",
                        "Active": false,
                        "CompanyId": null,
                        "Company": null,
                        "Office": null,
                        "UserType": "Contact",
                        "LastLogin": null
                    },
                    {
                        "Enabled": true,
                        "ResourceUri": "/v1/contacts/20130405184413250277000000",
                        "Name": "Johnny Consumer",
                        "OfficeId": null,
                        "Id": "20130405184413250277000000",
                        "Active": false,
                        "CompanyId": null,
                        "Company": null,
                        "Office": null,
                        "UserType": "Contact",
                        "LastLogin": null
                    },
                    {
                        "Enabled": true,
                        "ResourceUri": "/v1/contacts/20110616210203794915000000",
                        "Name": "Betty Buyer",
                        "OfficeId": null,
                        "Id": "20110616210203794915000000",
                        "Active": true,
                        "CompanyId": null,
                        "Company": null,
                        "Office": null,
                        "UserType": "Contact",
                        "LastLogin": "2014-06-06T09:06:56Z"
                    }
                ]
            }
        ]
    }
}

Step 4: Changing the current portal groups

To change our current circle, we merely need to PUT the "Id" of the portal group we wish to link up to. Note that this doesn't modify any existing relationships between consumers. Instead, it merely indicates that, for subsequent requests, we wish to share a workspace with the specified portal group.
$ curl "https://sparkapi.com/v1/portal/groups/current" -H "X-SparkApi-User-Agent: SparkAPIExamples" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} -H 'Content-Type: application/json' -X PUT --data '{"D": { "Id": "20130919194721820379000000" } }'
{
    "D": {
        "Success": true
    }
}

Step 5: Viewing data for the current portal group

Now, requests to resources such as Listing Carts, Saved Searches and News Feeds will be for the portal owner's data 'Ozzy Owner' above.
$ curl "https://sparkapi.com/v1/listingcarts" -H "X-SparkApi-User-Agent: SparkAPIExamples" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} 
{
    "D": {
        "Results": [
            {
                "ResourceUri": "/v1/listingcarts/20110706204418816410000000",
                "ListingCount": 2,
                "Name": "Favorites",
                "Id": "20110706204418816410000000",
                "PortalCartType": "Favorites"
            },
            {
                "ResourceUri": "/v1/listingcarts/20110616210204744387000000",
                "ListingCount": 3,
                "Name": "Possibilities",
                "Id": "20110616210204744387000000",
                "PortalCartType": "Possibilities"
            },
            {
                "ResourceUri": "/v1/listingcarts/20110616210204845814000000",
                "ListingCount": 0,
                "Name": "Recommended",
                "Id": "20110616210204845814000000",
                "PortalCartType": "Recommended"
            },
            {
                "ResourceUri": "/v1/listingcarts/20110616210204795277000000",
                "ListingCount": 1,
                "Name": "Rejects",
                "Id": "20110616210204795277000000",
                "PortalCartType": "Rejects"
            },
            {
                "ResourceUri": "/v1/listingcarts/20110616210204897215000000",
                "ListingCount": 0,
                "Name": "Removed",
                "Id": "20110616210204897215000000",
                "PortalCartType": "Removed"
            }
        ],
        "Success": true
    }
}