f1Connect API

Getting Started

Enrollment process

  1. You request an API key and supply an Account Id to be used during testing;
  2. We setup a test f1Connect account for you, generate an API key, link the Account Id you supplied with the corresponding test f1Connect account, send you the API key and login to the One backend (the f1Connect management system);
  3. You make the changes in your code to push the relevant case information any time a case is created or modified in your management software;
  4. You submit a couple test cases and let us know you are ready;
  5. We review those submissions and give feedback if anything should be improved, or give the OK for you to start offering the integration to your customers;
  6. For each shared customer that wants to enroll in this integration, you send us the Account Id you'll want to use to identify that customer, along with the customer name and address (so we can find it in our records);
  7. We verify the request is legitimate and associate the Account Id you sent to your API key and our internal Account Id.

API key

The API key is used to identify your application. Treat this as a password, do not expose it to your customers.
A funeralOne engineer will provide your API Key. If you haven't received one already, please feel free to contact our team by sending an email to [email protected].

In the examples on this page, the API key will be "NzKOSAPIaB0LbX9X9D6GsvhyU8CLWKUu".

Account ID

Some API calls require you to specify the ID of an account. The Account ID is an immutable ID that uniquely identifies the customer your app is making the request for. You'll need one for each of your customers that wants to integrate with funeralOne.
These IDs can contain up to 50 ASCII characters and have any format you like. Typically our partners use their internal customers' account id/email/guid (so they don't have to manage another field just for the integration), but you can also generate a new value (that can be useful if your account ids are mutable).
To activate the integration for a new customer, just send us an email at [email protected] with the Account ID you want to use and the customer name and address (or website URL) it should be associated with.

Please note that the field for the Account ID used in the API requests and responses is called AccountExternalId.

In the examples on this page, the Account ID will be "LexCorpId".

Authentication

The funeralOne API uses HTTP Basic Authentication to authenticate requests from your app. When you make an API request you provide your API key as the username and the password portion can be blank or a dummy value, as it is not used for API authentication.

Here's how an example request will look like when using the "NzKOSAPIaB0LbX9X9D6GsvhyU8CLWKUu" API key and the "LexCorpId" Account ID:

cURL command line 
curl -u "NzKOSAPIaB0LbX9X9D6GsvhyU8CLWKUu:pass" https://api.funeralone.com/cases/AccountExternalId/LexCorpId -v
HTTP Request 
GET /cases/AccountExternalId/LexCorpId HTTP/ 1.1
Authorization: Basic TnpLT1NBUElhQjBMYlg5WDlENkdzdmh5VThDTFdLVXU6cGFzcw==
Host: api.funeralone.com
Accept: */*
HTTP Response when the authentication is successful 
HTTP/1.1 200 OK
Date: Wed, 18 Jul 2012 14:49:19 GMT
Content-Length: 470
Content-Type: application/json; charset=utf-8

[{
    "CaseExternalId": "MyFirstCaseIdentity",
    "AccountExternalId": "LexCorpId",
    "Prefix": "",
    "FirstName": "John",
    "MiddleName": "Gilbert",
    ...
HTTP Response when the authentication is unsuccessful 
HTTP/1.1 401 Unauthorized
Content-Length: 74
Content-Type: application/json; charset=utf-8
WWW-Authenticate: Basic realm="f1Connect Api"
Date: Thu, 02 Nov 2017 22:33:19 GMT

{"code":1001,"message":"Unauthorized access. No authentication provided."}

Input & Output

Data exchange is done through JSON.

When providing input you must ensure that your JSON complies with the syntax paying particular attention to character and entity encoding with both formats. Any input provided in the query string of any request should be url-encoded.

Header values should be encoded with UTF-8 encoding.

POST information must be sent along with the header "Content-type: application/json". If no charset is specified in Content-type, ISO 8859-1 will be used.

API Endpoints

Create or Update a case

To create or update a case using JSON as the input data format, you would make a HTTP POST request to the /cases endpoint. The CaseExternalId field is what allows us to determine if you are requesting the creation of a new case in the f1Connect website (submit a unique value) or if you want to update an existing one (submit a value you already used to update the corresponding case).

Example Creating a case
POSThttps://api.funeralone.com/cases 
Content-Type: application/json
Authorization: Basic TnpLT1NBUElhQjBMYlg5WDlENkdzdmh5VThDTFdLVXU6cGFzcw==
Accept: */*
Host: api.funeralone.com

{
	"AccountExternalId": "LexCorpId",
	"CaseExternalId": "MyFirstCaseIdentity",
	"Prefix": "",
	"FirstName": "John",
	"MiddleName": "Gilbert",
	"LastName": "Doe",
	"Suffix": "III",
	"DisplayName": "John Doe",
	"Gender": "M",
	"BirthDate": "09/22/1932",
	"DeathDate": "07/14/1998",
	"Obituary": "After years of suffering some bad health problems John Gilbert Doe died and went to be with his Lord on July 14, 1998. Born in Kankakee, IL on September 22, 1932. His family moved to Michigan in 1950 and he lived in Madison Heights over 65 years. Preceded in death by his parents Everet and Gladys Doe and brother Dan. John went to Thomas Jefferson High School where he met his loving wife of sixty years Jane. He Graduated from St. Mary's University where he was president of Tau Delta Sigma fraternity. John served in Korea with the 45th infantry division where he received a purple heart. Home from the war he worked at Straus Frank Co. and then Paul Anderson Co. as an outside sales rep for 28 years. After they closed he and Jane traveled, did volunteer words, and cared for their aging parents. He was a member of Blinded Veterans Association The Low Vision Club and the Tau Delta's Old Timer's Club. John loved photography and was also a great wood worker and gardener. He wants to be remembered as a good friend. John is survived by his loving wife Jane Dow and many beloved friends. Donations in John honor may be made to The Humane Society. We would like to thank our dear friends, and care givers for all the love and support you have given us these past months. You all know who you are.",
	"Picture": "R0lGODdhCgAKAIAAAAQCBAAAACwAAAAACgAKAAACCISPqcvtD2MrADs=",
	"ExternalVideoURL": "http://DEPRECATED/See/ExternalVideoUrls",
	"ExternalVideoUrls": [
		{ "Type": "Tribute", "Url": "https://videos.lifetributes.com/1234"},
		{ "Type": "Tribute", "Url": "https://example.org/", "Caption": "Foo Bar Baz"},
		{ "Type": "Webcast", "Url": "https://www.example.com/something", "Caption": null}
	],
	"ServingLocation": {
		"ExternalId": "mylocationid",
		"Name": "ABC Funeral Home",
		"Address": "123 N River Rd",
		"Address2": "",
		"City": "Detroit",
		"State": "MI",
		"PostalCode": "48266",
		"Country": "US"
	},
	"FamilyAddress": {
		"ExternalId": "familylocationid",
		"FirstName": "Jane",
		"LastName": "Doe",
		"Phone": "810-555-1234",
		"Address": "987 N Woodward St",
		"Address2": "",
		"City": "Madison Heights",
		"State": "MI",
		"PostalCode": "48701",
		"Country": "US"
	},
	"Events": [{
			"Type": "Visitation",
			"Date": "07/15/1998",
			"StartTime": "14:00",
			"EndTime": "16:00",
			"Location": {
				"ExternalId": "churchlocationid",
				"Name": "ABC Church",
				"Address": "456 W Jefferson St",
				"Address2": "",
				"City": "Detroit",
				"State": "MI",
				"PostalCode": "48266",
				"Country": "US"
			},
			"Private": true
		}, {
			"Type": "Service",
			"Date": "07/16/1998",
			"StartTime": "10:00",
			"EndTime": "",
			"Location": {
				"ExternalId": "churchlocationid",
				"Name": "ABC Church",
				"Address": "456 W Jefferson St",
				"Address2": "",
				"City": "Detroit",
				"State": "MI",
				"PostalCode": "48266",
				"Country": "US"
			}
		}, {
			"Type": "Shiva",
			"Date": "07/17/1998",
			"StartTime": "10:00",
			"EndDate": "07/23/1998",
			"EndTime": "23:00",
			"Location": {
				"Type": "Residence",
				"Name": "Doe's Residence",
				"Address": "407 E. Fort St.",
				"Address2": "Ste 300",
				"City": "Detroit",
				"State": "MI",
				"PostalCode": "48266",
				"Country": "US"
			},
			"Information": "We'll be gathering with friends for coffee first, then please bring food to share dinner at 8:pm."
		}
	],
	"Cemetery": {
		"ExternalId": "cemeterylocationid",
		"Name": "ABC Cemetery",
		"Address": "456 W Jefferson St",
		"Address2": "",
		"City": "Detroit",
		"State": "MI",
		"PostalCode": "48266",
		"Country": "US",
		"Latitude": "25.001788",
		"Longitude": "-71.000086"
	},
	"FamilyAdmins": [
		"[email protected]",
		"[email protected]"
	]
}
HTTP Response when the case is created 
Status Code: 201
date: Thu, 02 Nov 2017 22:48:10 GMT
x-caseid: 8169935
content-length: 0
HTTP Response when the case is updated 
Status Code: 200
date: Thu, 02 Nov 2017 22:48:25 GMT
x-caseid: 8169935
content-length: 0
Input validation
AccountExternalId Mandatory, Maximum 50 chars. See Your Account ID for more info.
CaseExternalId Mandatory, Maximum 39 chars. Specify the same ID if you want to update a previously submitted case.
ServingLocation Mandatory
ServingLocation.Name Mandatory
ServingLocation.Country A valid 2-letter country code. Default: US
FamilyAddress.Country A valid 2-letter country code. Default: US
Cemetery.Name Mandatory
Cemetery.Country A valid 2-letter country code. Default: US
Events.Location Mandatory
Events.Location.Name Mandatory
Events.Location.Country A valid 2-letter country code. Default: US
Events.Private true or 1 to indicate that the event should not be disclosed to the public; false or 0 to show the event on the public website. Default: false
Notes
Events->Type Can be anything you like, but the predefined values Visitation, Service, Cemetery, and Shiva will receive special treatment.
Picture Content of a jpeg image file, encoded with Base64.
ExternalId This field allows us to distinguish locations with the same name and treat them as separate entities.
You can put anything in ExternalId, as long as it is unique for the API Key (a good candidate for this value is the location primary key from your DB).
Shiva Events These events can span on multiple days, are generally held at a private residence, and can contain special instructions for visitors.
The following snippet highlights the new fields you can provide for this event type { "Type": "Shiva", "Date": "07/17/1998", "StartTime": "10:00", "EndDate": "07/23/1998", "EndTime": "23:00", "Location": { "Type": "Residence", "Name": "Doe's Residence", "Address": "407 E. Fort St.", "Address2": "Ste 300", "City": "Detroit", "State": "MI", "PostalCode": "48266", "Country": "US" }, "Information": "We'll be gathering with friends for coffee first, then please bring food to share dinner at 8:pm." } Events->Location->Type If set to Residence, the ExternalId (if any) will be ignored and the location won't be displayed with the other locations commonly used by the funeral home.
FamilyAdmins An array of email addresses that will be invited to moderate the content of the case on the website.
ExternalVideoUrls An array of objects representing video URLs. Deprecates the ExternalVideoURL field (if both are present in the request, ExternalVideoUrls will take precedence).

Retrieving previously submitted cases

Example Getting a list of cases

To get a list of all the previously submitted cases in JSON format, make a HTTP GET request to the /cases/AccountExternalId/<LexCorpId> endpoint:

GEThttps://api.funeralone.com/cases/AccountExternalId/LexCorpId 
[{
    "CaseExternalId": "MyFirstCaseIdentity",
    "AccountExternalId": "LexCorpId",
    "Prefix": "",
    "FirstName": "John",
    "MiddleName": "Gilbert",
    "LastName": "Doe",
    "Suffix": "III",
    "BirthDate": "1932-09-22T00:00:00",
    "DeathDate": "1998-07-14T00:00:00"
}, {
    "CaseExternalId": "MySecondCaseIdentity",
    "AccountExternalId": "LexCorpId",
    "Prefix": "",
    "FirstName": "John",
    "MiddleName": "Dilbert",
    "LastName": "Doe",
    "Suffix": "IV",
    "BirthDate": "1962-09-22T00:00:00",
    "DeathDate": "2008-07-14T00:00:00"
}]
Example Getting a specific case

To get all the details available for a case, make a HTTP GET request to the /cases/AccountExternalId/<LexCorpId>/CaseExternalId/<MyFirstCaseIdentity>

GEThttps://api.funeralone.com/cases/AccountExternalId/LexCorpId/CaseExternalId/MyFirstCaseIdentity 
{
    "AccountExternalId": "LexCorpId",
    "CaseExternalId": "MyFirstCaseIdentity",
    "Prefix": "",
    "FirstName": "John",
    "MiddleName": "Gilbert",
    "LastName": "Doe",
    "Suffix": "III",
    "DisplayName": "John Doe",                                 
    "Gender": "M",
    "BirthDate": "1932-09-22T00:00:00",                                 
    "DeathDate": "1998-07-14T00:00:00",
    "Obituary": "After years of suffering some bad health problems...

Response status codes

The responses returned by the API are accompanied by meaningful HTTP status codes which represent the status of the request. Here's the general approach we take when returning responses:

Success

GET requests will return a "200 OK" response if the resource is successfully retrieved.
POST requests which create a resource we will return a "201 Created" response if successful.
POST requests which perform some other action such as updating a case will return a "200 OK" response if successful.
DELETE requests will return a "200 OK" response if the resource is successfully deleted.

Errors

If you attempt to authenticate with an invalid API key or you attempt to use an invalid ID for a resource, you'll received a "401 Unauthorized" response.

Example response body:401 Unauthorized 
{
	"code": 1001,
	"message": "Unauthorized access. No authentication provided."
}

If there is an error in your input, you'll receive a "400 Bad Request" response, with details of the error.

Example response body:400 Bad Request 
{
	"code": 1005,
	"message": "CaseExternalId cannot be bigger than 39 chars."
}

If you attempt to request a resource which doesn't exist, you'll receive a "404 Not Found" response.

Response body:404 Not Found 
{
	"code": 1006,
	"message": "Case not found."
}

If an unhandled error occurs on the API server for some reason, you'll receive a "500 Internal Server Error" response.

Response body:500 Internal Server Error 
{
	"code": 5001,
	"message": "Case not upserted.",
	"stacktrace": "funeralOne.f1Connect.Api.Model.ApiException: Case not upserted.\r\n   at funeralOne.f1Connect.Api.Services.Impl.CaseServices.Upsert(Int32 userId, Int32 accountId, Case case, Boolean& createdNew) in C:\\Data\\funeralOne\\HI\\f1ConnectApi\\funeralOne.f1Connect.Api.Services\\Impl\\CaseServices.cs:line 92\r\n   at funeralOne.f1Connect.Api.Website.Controllers.CasesController.Upsert(Case case) in C:\\Data\\funeralOne\\HI\\f1ConnectApi\\funeralOne.f1Connect.Api.Website\\Controllers\\CasesController.cs:line 98\r\n   at lambda_method(Closure , Object , Object[] )\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClass17.<GetExecutor>b__10(Object instance, Object[] methodParameters)\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.Execute(Object instance, Object[] arguments)\r\n   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.<>c__DisplayClass5.<ExecuteAsync>b__4()\r\n   at System.Threading.Tasks.TaskHelpers.RunSynchronously[TResult](Func`1 func, CancellationToken cancellationToken)"
}

Changelog

  • 05/29/2015 added support for Shiva events.
  • 09/22/2017 added support for Latitude and Longitude in cemetery and events location fields.
  • 11/02/2017 improved documentation.
  • 12/04/2019 improved documentation.
  • 07/07/2020 introduced ExternalVideoUrls.
  • 07/31/2020 introduced Event->Private.
  • 04/27/2022 removed ExternalVideoUrls limitation (used to be only 1 video of Type Webcast and up to 2 videos of Type Tribute).