Swyfft Partner API

REST API overview

The Swyfft Partner API uses HTTP methods and a RESTful endpoint structure. The API authentication framework is based on API key. Requests and responses have JSON-formatted data.

Use the Swyfft REST APIs in these environments:

Sandbox/Test Use your test SwyfftApiKey sent to you to make calls to the Sandbox URI: https://beta.swyfft.com/partnerapi/v1
Live/Production Use your production SwyfftApiKey sent to you to make calls to the Live/Production URI: https://www.swyfft.com/partnerapi/v1

Note: Swyfft uses secure HTTPS protocol and it replies with HTTP 403 (Forbidden) "SSL Required" when HTTP is used.

To construct a REST call, combine:

The HTTP method
The full URI to the resource
HTTP headers
The JSON-formatted payload

Swyfft also provides a simple, easy-to-use widget that you can load onto your website with as little as two lines of code. See the Widget page for more details.

Who do I talk to?

If you have questions about how to use the Swyfft Partner API, contact our support team at partnerapi@swyfft.com.

While Swyfft continues to support its API for legacy partners, we are no longer accepting new partners into our API program.

Authentication

Swyfft uses API keys to allow access to the API.

Swyfft expects the API key to be included in all API requests to the server in a header that looks like the following:

X-SwyfftApiKey: SwyfftApiKey

You must replace SwyfftApiKey with your personal API key.

Note: SwyfftApiKeys are different for Test and Production environments and sent separately to you.

If authentication fails an HTTP 401 is returned with an error response in the body.

{ "StatusCode": 1010, "Error": { "Code": 1010, "Message": "Unrecognized api key." } }

Quote

var quote = @"
{
  'FullAddress': '20 Cedar Dr, Rochelle Park NJ 07662',
  'LivingSpace': 1200
}
";

var client = new HttpClient();
var request = new HttpRequestMessage()
{
    Method = HttpMethod.Put,
    RequestUri = new Uri(baseUrl + "quote"),
    Content = new StringContent(quote, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-SwyfftApiKey", swyfftApiKey);

var response = client.SendAsync(request).Result;
response.EnsureSuccessStatusCode();
var result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine("Result: " + result);

<?php
define('SWYFFTKEY', 'SwyfftApiKey');
define('BASEURL','https://beta.swyfft.com/partnerapi/v1/');

$postData = [ 'FullAddress' => '20 Cedar Dr, Rochelle Park NJ 07662', 'LivingSpace' => 1200 ];

$opts = array(
    'http' => array(
        'method' => 'PUT',
        'header' => 'X-SwyfftApiKey: ' . SWYFFTKEY . "\r\n".
            'Content-Type: application/json' . "\r\n",
        'content' => json_encode($postData)
    )
);

$context = stream_context_create($opts);

echo file_get_contents(BASEURL . 'quote', false, $context);

# With shell, you can just pass the correct header with each request
curl
  -X PUT
  -v <base URL>/quote
  -H "X-SwyfftApiKey: SwyfftApiKey"
  -H "Content-Type: application/json"
  -d "{\"FullAddress\": \"20 Cedar Dr, Rochelle Park NJ 07662\", \"LivingSpace\": 1200}"

Make sure to replace SwyfftApiKey with your API key.

The above command returns JSON structured like this:

{
    "Quote": {
        "QuoteGuid": "b2c6a8eb-8c35-4e9d-a05a-8e5a2d4dc54e",
        "Address": {
            "AddressKey": "07662320220",
            "Street1": "20 Cedar Dr",
            "City": "Rochelle Park",
            "State": "NJ",
            "Zip5": "07662",
            "FullAddress": "20 Cedar Dr, Rochelle Park NJ 07662"
        },
        "ChangeQuoteUrl": "<base URL>/quote?quoteid=b2c6a8eb8c354e9da05a8e5a2d4dc54e",
        "PurchaseQuoteUrl": "<base URL>/purchase?quoteid=b2c6a8eb8c354e9da05a8e5a2d4dc54e",
        "Elements": [{
            "ElementName": "YearUpgraded",
            "ElementDisplay": "Year Upgraded",
            "ElementValueType": "Decimal",
            "Value": "1960.0000000"
        }, {
            "ElementName": "LiquidFuelRiskClass",
            "ElementDisplay": "Liquid Fuel Risk Class",
            "ElementValueType": "String",
            "Value": "100"
        }, {
            "ElementName": "CoverageELimit",
            "ElementDisplay": "Personal Liability",
            "ElementValueType": "Decimal",
            "Value": "500000.0000000"
        }, {
            "ElementName": "CoverageFLimit",
            "ElementDisplay": "Medical Expenses",
            "ElementValueType": "Decimal",
            "Value": "5000.0000000"
        }, {
            "ElementName": "CoverageDLimit",
            "ElementDisplay": "Living Expenses",
            "ElementValueType": "Decimal",
            "Value": "80000.0000000"
        }, {
            "ElementName": "CoverageBLimit",
            "ElementDisplay": "Other Structures",
            "ElementValueType": "Decimal",
            "Value": "25000.0000000"
        }, {
            "ElementName": "CoverageCLimit",
            "ElementDisplay": "Personal Property",
            "ElementValueType": "Decimal",
            "Value": "120000.0000000"
        }, {
            "ElementName": "PrivateResidenceFullTimeOutservantCount",
            "ElementDisplay": "Residence Outservants",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "PrivateEstateFullTimeOutservantCount",
            "ElementDisplay": "Estate Outservants",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "PrivateResidenceEstateFullTimeInservantCount",
            "ElementDisplay": "Estate/Residence Inservants",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "PersonalPropertyEnhancementLimit",
            "ElementDisplay": "Enhanced Personal Property Coverage",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "LeadRiskClass",
            "ElementDisplay": "Lead Risk Class",
            "ElementValueType": "String",
            "Value": "500"
        }, {
            "ElementName": "ReplacementCost",
            "ElementDisplay": "Home Value",
            "ElementValueType": "Decimal",
            "Value": "235827.0000000"
        }, {
            "ElementName": "ProtectiveDevicesSprinklersYesNo",
            "ElementDisplay": "Sprinklers Discount",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "LivingSpace",
            "ElementDisplay": "Square Footage",
            "ElementValueType": "Decimal",
            "Value": "1200.0000000"
        }, {
            "ElementName": "ProtectiveDevicesBurglarAlarms",
            "ElementDisplay": "Burglar Alarm Discount",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "NumLosses",
            "ElementDisplay": "Loss History",
            "ElementValueType": "Decimal",
            "Value": null
        }, {
            "ElementName": "EscapedLiquidFuelLeadLiabilityCoverage",
            "ElementDisplay": "Escaped Liquid Fuel/Lead Liability Coverage",
            "ElementValueType": "Boolean",
            "Value": "False"
        }, {
            "ElementName": "PersonalInjuryCoverage",
            "ElementDisplay": "Personal Injury",
            "ElementValueType": "Boolean",
            "Value": "False"
        }, {
            "ElementName": "LimitedWaterBackupLimit",
            "ElementDisplay": "Water Back-Up/Sump Discharge Coverage",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "YearBuilt",
            "ElementDisplay": "Year Built",
            "ElementValueType": "Decimal",
            "Value": "1960.0000000"
        }, {
            "ElementName": "Deductible",
            "ElementDisplay": "Deductible",
            "ElementValueType": "Decimal",
            "Value": "1000.0000000"
        }, {
            "ElementName": "IdentityFraudCoverage",
            "ElementDisplay": "Identity Fraud Expense Coverage",
            "ElementValueType": "Boolean",
            "Value": "False"
        }, {
            "ElementName": "NumStories",
            "ElementDisplay": "Stories",
            "ElementValueType": "Decimal",
            "Value": "1.5000000"
        }, {
            "ElementName": "SinkholeCollapseLimit",
            "ElementDisplay": "Sinkhole Collapse Coverage",
            "ElementValueType": "Boolean",
            "Value": "False"
        }, {
            "ElementName": "FungiWetDryRotBacteriaPropertyLimit",
            "ElementDisplay": "Fungi/Rot/Bacteria Property Limit",
            "ElementValueType": "Decimal",
            "Value": "10000.0000000"
        }, {
            "ElementName": "ProtectiveDevicesFireAlarms",
            "ElementDisplay": "Fire Alarm Discount",
            "ElementValueType": "Decimal",
            "Value": "0.0000000"
        }, {
            "ElementName": "RoofAge",
            "ElementDisplay": "Roof Age",
            "ElementValueType": "Decimal",
            "Value": "10.0000000"
        }, {
            "ElementName": "Construction",
            "ElementDisplay": "Construction",
            "ElementValueType": "String",
            "Value": "Frame"
        }, {
            "ElementName": "OccasionalServantCount",
            "ElementDisplay": "Occasional Servants",
            "ElementValueType": "Decimal",
            "Value": "1.0000000"
        }],
        "Fees": [{
            "Name": "PligaFeeNJ",
            "DisplayName": "Property-Liability Guaranty Association Fee (NJ PLIGA)",
            "Type": "Annual",
            "Value": "4.2000"
        }, {
            "Name": "MonthlyInstallmentFee",
            "DisplayName": "Monthly Installment Fee",
            "Type": "Monthly",
            "Value": "6.0000"
        }],
        "ManualPremiumAdjustment": 0.0000,
        "DownPayment": 58.3300,
        "MonthlyInstallmentFee": 6.0000,
        "RawAnnualPremium": 699.7882,
        "AnnualPremium": 700.0000,
        "MonthlyPayment": 64.3300,
        "GrossAnnualPayment": 704.2000,
        "GrossDownPayment": 62.5300,
        "AnnualFeesTotal": 4.2000,
        "QuotePremiumErrors": [],
        "QuoteWarnings": []
    },
    "StatusCode": 0,
    "Error": null
}

Get or Retreive a specific Quote

HTTP Request

PUT <base URL>/quote

JSON Parameters

Parameter	Required	Description
FullAddress	Yes	The full address of the home. E.g. "20 Cedar Dr, Rochelle Park NJ 07662"
LivingSpace	No	The number of square feet in the home. E.g. "1200"

Return Value

Elements

The following values can appear in the ElementValueType attribute:

Type
Decimal
Boolean
String

Note that the Value attribute values are always quoted.

Address

var address = "2300 ha";
var client = new HttpClient();
var request = new HttpRequestMessage()
{
    RequestUri = new Uri(baseUrl + "addresses?partialAddress=" + HttpUtility.UrlEncode(address))
};
request.Headers.Add("X-SwyfftApiKey", swyfftApiKey);
var response = client.SendAsync(request).Result;
response.EnsureSuccessStatusCode();
var result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine("Result: " + result);

<?php
define('swyfftkey', 'SwyfftApiKey');
define('BASEURL','https://beta.swyfft.com/partnerapi/v1/');

$opts = array(
    'http' => array(
        'method' => 'GET',
        'header' => 'X-SwyfftApiKey: ' . SWYFFTKEY . "\r\n".
            'Content-Type: application/json' . "\r\n"
    )
);

$context = stream_context_create($opts);

$partial = '2300 ha';

echo file_get_contents(BASEURL . 'addresses?partialAddress=' . urlencode($partial), false, $context);

curl
  -X GET
  -v <base URL>/addresses?partialAddress=2300%20ha
  -H "X-SwyfftApiKey: SwyfftApiKey"
  -H "Content-Type: application/json"

Make sure to replace SwyfftApiKey with your API key.

The above command returns JSON structured like this:

{
    "Addresses": [{
        "AddressKey": "36617251500",
        "Street1": "2300 Hathcox St",
        "City": "Mobile",
        "State": "AL",
        "Zip5": "36617",
        "FullAddress": "2300 Hathcox St, Mobile AL 36617"
    }],
    "StatusCode": 0,
    "Error": null
}

Get addresses formatted in a manner that Swyfft recognizes.

HTTP Request

GET <base URL>/address?partialAddress=<partial address>

Query Parameters

Parameter	Required	Description
partialAddress	Yes	A partial address for the home. E.g. "2300%20ha" - remember to urlencode the value. The system does a "starts with" comparison so trying to seach for a town name will not work.

Although the Swyfft API provides control and flexibility, it also comes "with some assembly required". If what you want is a simple way to show an address box on your web page, the Swyfft Widget may be closer to what you need. With two lines of code, you can add a widget to your website that will look something like this:

The way you do this is very simple. You decide where on your web page you want the Swyfft widget to appear, and place an HTML element there with an appropriately styled height and width. (We recommend at least 500 pixels high and 500 pixels wide.)

    <script type="text/javascript" src="//www.swyfft.com/Widgets/Dist/widgets.bundle.js"></script>
    <script type="text/javascript">
        swyfft.widgets.addressWidget.show('#PutYourTargetElementIdHere', 'PutYourApiKeyHere', SetToTrueToOpenQuoteOnNewTab);

        // Optionally override the widget's error handling.
        swyfft.widgets.addressWidget.onError(function(err) {
            return new Promise(function (resolve, reject) {
                try {
                    if (err.Message && err.Message.indexOf("underwriting guidelines") > 0) {
                        // Show your own error message here, and then resolve the promise with
                        // "true" value to indicate that you handled it.
                        resolve(true);
                    } else {
                        // Resolve the promise with a "false" value to indicate that Swyfft's
                        // widget should proceed with its default handling.
                        resolve(false);
                    }
                } catch (ex) {
                    // If an error happens, and you don't want to deal with it yourself, 
                    // reject the promise and send it back to the Swyfft widget.
                    reject(ex);
                }
            });
        });
    </script>

Then add the javascript to the right to your page:

(Obviously, replacing the #PutYourTargetElementIdHere, PutYourApiKeyHere and SetToTrueToOpenQuoteOnNewTab with the appropriate element id, API key and boolean value.)

You can see an example of how to do it on the ~/Swyfft.ApiDemo.Web/Views/Home/Widget.cshtml page in the Swyfft API Demo project.

If you need to override any of the CSS styling, you can do that by overriding the styles defined in the widget's (automatically loaded) stylesheet.

We've also added support for customizable error handling. If you'd like to override Swyfft's error handling for the widget, you can pass a callback function to the AddressWidget's onError method. The callback should return a Promise that resolves to true if you've handled the error or to false if you haven't. In the event an error occurs in your handler and you want Swyfft's error handling to take care of it, you can reject the promise with the exception.

Errors

Swyfft returns standard HTTP status codes for successful and error responses.

HTTP status codes

Status Code	Meaning
200	Request OK
400	Validation error
401	Authentication errors or Unauthorized request
403	Forbidden
500	Swyfft server error

Error responses

The response body for all errors includes additional error details in this format:

{ "StatusCode": 1104, "Error": { "Code": 1104, "Message": "Invalid request. Invalid LivingSpace value." } }

Error Codes and Messages

Every response has a "StatusCode" and "Error" attribute. StatusCode is a number. Non-zero indicates an error occured. Error is an optional object with "Code" and "Message" attributes. This attribute will be NULL if no error occured. Code is a number and matches StatusCode. Message is a string and is a human readable description about the error suitable for displaying to the user.

Status Code	Meaning
0	No error.
1000	Unknown error occurred.
1010	Unrecognized api key.
1101	Invalid request.
1102	Invalid request. FullAddress is empty.
1103	Could not find property information for specified address.
1104	Invalid request. Invalid LivingSpace value.
1105	Invalid request. Invalid QuoteGuid.
1201	Sorry, we don't support this property yet. We're working on it.
1202	Sorry, we don't cover this type of property.
1203	A quote for this address has already been purchased.
1204	Could not create quote. Coverage is declined.
1205	The agent's license information is missing or does not cover this area.
1206	Property does not appear to be a single family residence.
1207	The agent's E&O information is missing or has expired.
1208	Your agency is not configured to write quotes for this county.
1209	The requested property doesn't have a precise location set.
1301	Failed to create quote. There is not enough data on this property to generate an automatic quote.
1401	Your agency is over daily API call limit.
1402	Your agency is over 5 minute API call limit.
1403	Your agency does not have API call limits set.

Swyfft Partner API

REST API overview

Website Widget

Who do I talk to?

Authentication

Quote

HTTP Request

JSON Parameters

Return Value

Elements

Address

HTTP Request

Query Parameters

Widget

Errors

HTTP status codes

Error responses

Error Codes and Messages