Households

A household is a resource that contains people, addresses, and communications. This resource does not contain the delete methods.

Notes ::

• By passing in the content-type of application/help in the accept header or using the {format} parameter help from https://demo.fellowshiponeapi.com/v1/Households, the API will return an html representation of the help documents for this resource (authentication not required)

Authentication

This method requires Authentication

Resource Structure

This resource conforms to the following XSD

Methods

Households ::

• search [GET] https://demo.fellowshiponeapi.com/v1/Households{parameters}
• show [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}
• new [GET] https://demo.fellowshiponeapi.com/v1/Households/New
• edit [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}/Edit
• create [POST] https://demo.fellowshiponeapi.com/v1/Households
• update [PUT] [POST(Low REST)] https://demo.fellowshiponeapi.com/v1/Households/{id}

Method: search [GET]

The search method will return a collection of households for the parameters provided.

Notes ::

• Searching by name, lastActivityDate, lastUpdatedDate, and createdDate are mutually exclusive and cannot be used with any other search parameters
  • Search By name: https://demo.fellowshiponeapi.com/v1/Households/Search?searchfor=Nick%20Floyd
    • This parameter will be used as: parameter.searchfor like household.householdName (searchfor=Nick will return "Nick Floyd", "Nick Johnson", "John Nickleson")
    • All values passed in via searchfor must be url encoded (ex. Nick Floyd needs to be Nick%20Floyd)
  • Search By lastActivityDate: https://demo.fellowshiponeapi.com/v1/People/Search?lastActivityDate=2009-03-01
    • This parameter will be used as: parameter.lastActivityDate >= household.lastActivityDate (greater than or equal to)
  • Search By lastUpdatedDate: https://demo.fellowshiponeapi.com/v1/People/Search?lastUpdatedDate=2009-03-01
    • This parameter will be used as: parameter.lastUpdatedDate >= household.lastUpdatedDate (greater than or equal to)
  • Search By createdDate: https://demo.fellowshiponeapi.com/v1/People/Search?createdDate=2009-03-01
    • This parameter will be used as: parameter.createdDate >= household.createdDate (greater than or equal to)
• By passing in the content-type of application/help in the accept header or using the {format} parameter help from https://demo.fellowshiponeapi.com/v1/Households, the API will return an html representation of the help documents for this resource (authentication not required)
• If the recordsPerPage parameter's value is less than 10, the API will default the parameter to 10
• If the page parameter is not used or its value is less than 1, the API will default the parameter to 1

Content-types ::

• application/json
• application/xml
• application/help

Format ::

• json
• xml
• help

Parameters ::

• {format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/Search.{format}?{search parameters}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/Search?format={format}&{search parameters}
  • [Header] Accept : {Content-type}
• {search parameters}
  • searchFor = Name of the household you are searching for*
    • ex. searchfor=Nick%20Floyd
  • lastActivityDate = The date of the last time the anyone in the household attended an activity (format: yyyy-mm-dd)*
    • ex. lastActivityDate=2009-03-01
  • lastUpdatedDate = The date of the last time the person's information was updated (format: yyyy-mm-dd)*
    • ex. lastUpdatedDate=2009-03-01
  • createdDate = The date when the person's information was created / inserted into the system (format: yyyy-mm-dd)*
    • ex. createdDate=2009-03-01
  • recordsPerPage = number of records to return for each query (default is 20)
    • ex. recordsPerPage=15
  • page = page number for the given result set
    • ex. page=3

*Search parameters that are mutually exclusive. They may not be used in combination with each other or parameter other than paging parameters

Sample Response ::

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/Search?searchFor=Turner&page=1

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 28 Apr 2009 01:17:43 GMT
Content-Length: 1664

<?xml version="1.0" encoding="utf-8"?>
<results count="3" pageNumber="1" totalRecords="3" additionalPages="0">
  <household id="3070691" uri="https://demo.fellowshiponeapi.com/v1/Households/3070691" oldID="" hCode="mlB4tpIVkgyIxMA0TvX0nQ==">
    <householdName>Turner Excavation</householdName>
    <householdSortName>Turner Excavation</householdSortName>
    <householdFirstName></householdFirstName>
    <lastSecurityAuthorization></lastSecurityAuthorization>
    <lastActivityDate></lastActivityDate>
    <createdDate></createdDate>
    <lastUpdatedDate></lastUpdatedDate>
  </household>
  <household id="1551398" uri="https://demo.fellowshiponeapi.com/v1/Households/1551398" oldID="971655" hCode="urt+Ni9Wu8/Ba/c9xvmnTQ==">
    <householdName>Turner Harris</householdName>
    <householdSortName>Harris</householdSortName>
    <householdFirstName>Turner</householdFirstName>
    <lastSecurityAuthorization></lastSecurityAuthorization>
    <lastActivityDate>2006-01-27T12:25:00</lastActivityDate>
    <createdDate></createdDate>
    <lastUpdatedDate>2006-01-31T00:08:53</lastUpdatedDate>
  </household>
  <household id="2695854" uri="https://demo.fellowshiponeapi.com/v1/Households/2695854" oldID="" hCode="uvO24oj2im1NxJIZysniLQ==">
    <householdName>Turner Pierce</householdName>
    <householdSortName>Pierce</householdSortName>
    <householdFirstName>Turner</householdFirstName>
    <lastSecurityAuthorization>2005-03-17T17:15:53</lastSecurityAuthorization>
    <lastActivityDate>2006-01-27T12:25:00</lastActivityDate>
    <createdDate></createdDate>
    <lastUpdatedDate>2008-11-04T17:28:57</lastUpdatedDate>
  </household>
</results>

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/Search.json?searchFor=Turner&page=1

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Fri, 01 May 2009 17:50:48 GMT
Content-Length: 1157

{
    "results": {
        "@count": "3",
        "@pageNumber": "1",
        "@totalRecords": "3",
        "@additionalPages": "0",
        "household": [
            {
                "@id": "3070691",
                "@uri": "https://demo.fellowshiponeapi.com/v1/Households/3070691",
                "@oldID": "",
                "@hCode": "mlB4tpIVkgyIxMA0TvX0nQ==",
                "householdName": "Turner Excavation",
                "householdSortName": "Turner Excavation",
                "householdFirstName": null,
                "lastSecurityAuthorization": null,
                "lastActivityDate": null,
                "createdDate": null,
                "lastUpdatedDate": null
            },
            {
                "@id": "1551398",
                "@uri": "https://demo.fellowshiponeapi.com/v1/Households/1551398",
                "@oldID": "971655",
                "@hCode": "urt+Ni9Wu8/Ba/c9xvmnTQ==",
                "householdName": "Turner Harris",
                "householdSortName": "Harris",
                "householdFirstName": "Turner",
                "lastSecurityAuthorization": null,
                "lastActivityDate": "2006-01-27T12:25:00",
                "createdDate": null,
                "lastUpdatedDate": "2006-01-31T00:08:53"
            },
            {
                "@id": "2695854",
                "@uri": "https://demo.fellowshiponeapi.com/v1/Households/2695854",
                "@oldID": "",
                "@hCode": "uvO24oj2im1NxJIZysniLQ==",
                "householdName": "Turner Pierce",
                "householdSortName": "Pierce",
                "householdFirstName": "Turner",
                "lastSecurityAuthorization": "2005-03-17T17:15:53",
                "lastActivityDate": "2006-01-27T12:25:00",
                "createdDate": null,
                "lastUpdatedDate": "2008-11-04T17:28:57"
            }
        ]
    }
}

Method: show [GET]

The show method will return a single household for a given id.

Notes ::

• By passing in the content-type of application/xsd in the accept header or using the {format} parameter xsd the API will return an xsd for a single version of this resource (authentication not required)

Content-types ::

• application/json
• application/xml
• application/xsd
• application/help

Format ::

• json
• xml
• xsd
• help

Parameters ::

• {format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}.{format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}?format={format}
  • [Header] Accept : {Content-type}
• {id}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}

Sample Response ::

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/1552366

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Content-Location: https://demo.fellowshiponeapi.com/v1/Households/1552366
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 07 Apr 2009 20:44:35 GMT
Content-Length: 562

<?xml version="1.0" encoding="utf-8"?>
<household id="1552366" uri="https://demo.fellowshiponeapi.com/v1/Households/1552366" oldID="1340151" hCode="CYQVRnq3sKZi8rBKr7IGyg==">
  <householdName>Greg and Kristin Cannon</householdName>
  <householdSortName>Cannon</householdSortName>
  <householdFirstName>Greg and Kristin</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate></createdDate>
  <lastUpdatedDate>2008-11-04T13:15:14</lastUpdatedDate>
</household>

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/1552366.json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Content-Location: https://demo.fellowshiponeapi.com/v1/Households/1552366.json
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Fri, 01 May 2009 17:53:59 GMT
Content-Length: 392

{
    "household": {
        "@id": "1552366",
        "@uri": "https://demo.fellowshiponeapi.com/v1/Households/1552366",
        "@oldID": "1340151",
        "@hCode": "CYQVRnq3sKZi8rBKr7IGyg==",
        "householdName": "Greg and Kristin Cannon",
        "householdSortName": "Cannon",
        "householdFirstName": "Greg and Kristin",
        "lastSecurityAuthorization": null,
        "lastActivityDate": "2006-09-09T17:00:00",
        "createdDate": null,
        "lastUpdatedDate": "2008-11-04T13:15:14"
    }
}

Method: edit [GET]

The edit method will return a single household for a given id. The purpose of the edit method is to retrieve a resource in its most recent condition with its latest values.

Content-types ::

• application/json
• application/xml
• application/help

Format ::

• json
• xml
• help

Parameters ::

• {format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}/edit.{format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}/edit?format={format}
  • [Header] Accept : {Content-type}
• {id}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/{id}/edit

Sample Response ::

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/1552366/edit

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 07 Apr 2009 20:56:09 GMT
Content-Length: 562

<?xml version="1.0" encoding="utf-8"?>
<household id="1552366" uri="https://demo.fellowshiponeapi.com/v1/Households/1552366" oldID="1340151" hCode="CYQVRnq3sKZi8rBKr7IGyg==">
  <householdName>Greg and Kristin Cannon</householdName>
  <householdSortName>Cannon</householdSortName>
  <householdFirstName>Greg and Kristin</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate></createdDate>
  <lastUpdatedDate>2008-11-04T13:15:14</lastUpdatedDate>
</household>

Method: new [GET]

The new method will return a single household. The purpose of the new method is to retrieve an empty resource with the proper structure.

Content-types ::

• application/json
• application/xml
• application/help

Format ::

• json
• xml
• help

Parameters ::

• {format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/new.{format}
  • [GET] https://demo.fellowshiponeapi.com/v1/Households/new?format={format}
  • [Header] Accept : {Content-type}

Sample Response ::

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/new

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 07 Apr 2009 20:57:55 GMT
Content-Length: 389

<?xml version="1.0" encoding="utf-8"?>
<household id="" uri="" oldID="" hCode="">
  <householdName></householdName>
  <householdSortName></householdSortName>
  <householdFirstName></householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate></lastActivityDate>
  <createdDate></createdDate>
  <lastUpdatedDate></lastUpdatedDate>
</household>

Given: [GET] https://demo.fellowshiponeapi.com/v1/Households/new.json

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Fri, 01 May 2009 17:54:49 GMT
Content-Length: 229

{
    "household": {
        "@id": "",
        "@uri": "",
        "@oldID": "",
        "@hCode": "",
        "householdName": null,
        "householdSortName": null,
        "householdFirstName": null,
        "lastSecurityAuthorization": null,
        "lastActivityDate": null,
        "createdDate": null,
        "lastUpdatedDate": null
    }
}

Method: create [POST]

The create method will create a single household.

Notes ::

• This method will return a 201 - Created if successfully created

Content-types ::

• application/json
• application/xml

Format ::

• json
• xml

Parameters ::

• {format}
  • [POST] https://demo.fellowshiponeapi.com/v1/Households.{format}
  • [POST] https://demo.fellowshiponeapi.com/v1/Households?format={format}
  • [Header] Accept : {Content-type}

Required Fields ::

• householdName

Sample Response ::

Given: [POST] https://demo.fellowshiponeapi.com/v1/Households

Request body:

<?xml version="1.0" encoding="utf-8"?>
<household id="" uri="" oldID="" hCode="">
  <householdName>Nick and Rebecca Floyd</householdName>
  <householdSortName>Floyd</householdSortName>
  <householdFirstName>Nick and Rebecca</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate></createdDate>
  <lastUpdatedDate></lastUpdatedDate>
</household>

Response:

HTTP/1.1 201 Created
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Location: https://demo.fellowshiponeapi.com/v1/Households/14338644
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 07 Apr 2009 21:00:38 GMT
Content-Length: 555

<?xml version="1.0" encoding="utf-8"?>
<household id="14338644" uri="https://demo.fellowshiponeapi.com/v1/Households/14338644" oldID="" hCode="Fj02xVGqxMkMosbz+UqFzQ==">
  <householdName>Nick and Rebecca Floyd</householdName>
  <householdSortName>Floyd</householdSortName>
  <householdFirstName>Nick and Rebecca</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate>2009-04-07T16:00:38</createdDate>
  <lastUpdatedDate></lastUpdatedDate>
</household>

Given: [POST] https://demo.fellowshiponeapi.com/v1/Households.json

Request body:

{
    "household": {
        "@id": "",
        "@uri": "",
        "@oldID": "",
        "@hCode": "",
        "householdName": "Nick Floyd",
        "householdSortName": null,
        "householdFirstName": null,
        "lastSecurityAuthorization": null,
        "lastActivityDate": null,
        "createdDate": null,
        "lastUpdatedDate": null
    }
}

Response:

HTTP/1.1 201 Created
Cache-Control: private
Content-Type: application/json; charset=utf-8
Location: https://demo.fellowshiponeapi.com/v1/Households.json/14338685
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Fri, 01 May 2009 17:56:15 GMT
Content-Length: 339

{
    "household": {
        "@id": "14338685",
        "@uri": "https://demo.fellowshiponeapi.com/v1/Households/14338685",
        "@oldID": "",
        "@hCode": "B52zZE1vuNRVPKU3M+/VQg==",
        "householdName": "Nick Floyd",
        "householdSortName": null,
        "householdFirstName": null,
        "lastSecurityAuthorization": null,
        "lastActivityDate": null,
        "createdDate": "2009-05-01T12:56:13",
        "lastUpdatedDate": null
    }
}

Method: update [PUT] [POST (Low REST)]

The update method will update a single household.

Content-types ::

• application/json
• application/xml

Format ::

• json
• xml

Parameters ::

• {format}
  • [PUT] https://demo.fellowshiponeapi.com/v1/Households/{id}.{format}
  • [PUT] https://demo.fellowshiponeapi.com/v1/Households/{id}?format={format}
  • [Header] Accept : {Content-type}
• {id}
  • [PUT] https://demo.fellowshiponeapi.com/v1/Households/{id}

Required Fields ::

• household id
• householdName

Sample Response ::

Given: [PUT] https://demo.fellowshiponeapi.com/v1/Households/14338644

Request body:

<?xml version="1.0" encoding="utf-8"?>
<household id="14338644" uri="https://demo.fellowshiponeapi.com/v1/Households/14338644" oldID="" hCode="Fj02xVGqxMkMosbz+UqFzQ==">
  <householdName>Nick and Rebecca Floyd</householdName>
  <householdSortName>Floyd</householdSortName>
  <householdFirstName>Nick and Rebecca</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate>2009-04-07T16:00:38</createdDate>
  <lastUpdatedDate></lastUpdatedDate>
</household>

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/xml; charset=utf-8
Content-Location: https://demo.fellowshiponeapi.com/v1/Households/14338644
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Tue, 07 Apr 2009 21:01:27 GMT
Content-Length: 574

<?xml version="1.0" encoding="utf-8"?>
<household id="14338644" uri="https://demo.fellowshiponeapi.com/v1/Households/14338644" oldID="" hCode="Fj02xVGqxMkMosbz+UqFzQ==">
  <householdName>Nick and Rebecca Floyd</householdName>
  <householdSortName>Floyd</householdSortName>
  <householdFirstName>Nick and Rebecca</householdFirstName>
  <lastSecurityAuthorization></lastSecurityAuthorization>
  <lastActivityDate>2006-09-09T17:00:00</lastActivityDate>
  <createdDate>2009-04-07T16:00:38</createdDate>
  <lastUpdatedDate>2009-04-07T16:01:27</lastUpdatedDate>
</household>

Given: [PUT] https://demo.fellowshiponeapi.com/v1/Households/14338685.json

Request body:

{
    "household": {
        "@id": "14338685",
        "@uri": "https://demo.fellowshiponeapi.com/v1/Households/14338685",
        "@oldID": "",
        "@hCode": "B52zZE1vuNRVPKU3M+/VQg==",
        "householdName": "Nick Floyd",
        "householdSortName": null,
        "householdFirstName": null,
        "lastSecurityAuthorization": null,
        "lastActivityDate": null,
        "createdDate": "2009-05-01T12:56:13",
        "lastUpdatedDate": null
    }
}

Response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Content-Location: https://demo.fellowshiponeapi.com/v1/Households/14338685.json
Server: Microsoft-IIS/7.0
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Fri, 01 May 2009 17:58:59 GMT
Content-Length: 356

{
    "household": {
        "@id": "14338685",
        "@uri": "https://demo.fellowshiponeapi.com/v1/Households/14338685",
        "@oldID": "",
        "@hCode": "B52zZE1vuNRVPKU3M+/VQg==",
        "householdName": "Nick Floyd",
        "householdSortName": null,
        "householdFirstName": null,
        "lastSecurityAuthorization": null,
        "lastActivityDate": null,
        "createdDate": "2009-05-01T12:56:13",
        "lastUpdatedDate": "2009-05-01T12:58:57"
    }
}

• Overview
• People API realm
• Giving API realm
• Groups API realm
• Events API realm
• Authentication
• HTTP Status Codes
• HTTP Headers

• ---

  Ten Commandments of API Consumption
• Test your API key