Skip to main content

Implement Insurance API Calls

As described in Start Here, there are three insurance periods that are required to be tracked in order to capture all relevant data and price insurance accordingly. We will go over all insurance API calls that correspond to these periods in this section.

Insurance Period APIs​

The insurance periods you’ll be tracking are all represented by APIs within the Fairmatic SDK. These periods, along with the corresponding APIs, are listed below.

Here you can see how we have started/stopped our insurance periods with the startPeriodWithPeriodX() / stopPeriod() functions.

Please use the diagram below to see which periods are relevant to your use case. Accordingly, please only use the relevant sections below.

Insurance Period State Diagram

No Period​

When no Period is in progress, the stopPeriod() API should be called to make sure the SDK is not tracking any rides.

Trigger this API right when the driver signals that they want to go “Offline” or when they signal that they aren’t actively looking to pick up or match with an occupant.

Fairmatic.stopPeriod { success, error in
    // Code
}

If your drivers will drive for other ride-sharing services, you can use the P0 implementation so that coverage is not provided by Fairmatic Insurance during this period. This will prevent you from being charged when the driver isn’t driving for your company.

We recommend adding a button that calls stopPeriod() whenever the driver is driving for a different service, as shown in the above diagram, and then a resume button to enable tracking via startDriveWithPeriod1() or any other period based on your use case.

Period 1​

If your use case includes Period 1, which is the insurance risk period in which drivers are actively looking for occupants to pick up but haven’t matched with one yet, then implement the below API. Any driving activity within this period will be manually detected and recorded when this API is in use.

Trigger this API right when the driver has signaled that they’re ready to pair with an occupant. This can be them signaling “ready for rides” in a traditional rideshare use case. Usually does not apply to pre-scheduled pick-ups.

let trackingId = "alphanumeric_tracking_id"

Fairmatic.startDriveWithPeriod1(trackingId) { success, error in
    // Code
}

trackingId parameter explained​

info

The trackingId parameter accepts an alphanumeric string. While it is recommended to use a unique string for each startPeriod() call for this parameter, uniqueness is not mandatory.

This string serves as an identifier to search for trips using the server APIs provided by Fairmatic.
We recommend formatting your trackingId in a way that facilitates easy matching of trips between our system and your backend systems.

An example use case for trackingId:
Consider a scenario where you store insurance periods (P2, P3) of a single trip as one trip in your backend. In the Fairmatic system, these periods are stored as separate trips. By passing the same trackingId for both the startPeriod2() and startPeriod3() API calls, you can map the P2 and P3 trips in the Fairmatic backend to a single trip in your system.
This allows for correlation between your backend and the Fairmatic systems.

Period 2​

If your use case includes Period 2, which is the insurance risk period in which drivers are on their way to pick up a passenger or goods, and there are no passengers or goods in the vehicle, then implement the below API.

Trigger this API right when the driver is on their way to pick up the occupant. Depending on the use case, this can be a UI trigger or a pre-scheduled trigger.

let trackingId = "alphanumeric_tracking_id"

Fairmatic.startDriveWithPeriod2(trackingId) { success, error in
    // Code
}

Period 3​

If your use case includes Period 3, which is the insurance risk period in which there is at least one passenger in the vehicle, then implement the below API.

Trigger this API right when the driver has picked up the occupant. This can be a UI trigger.

Please refer to this explanation for the trackingId parameter in this API.

let trackingId = "alphanumeric_tracking_id"

Fairmatic.startDriveWithPeriod3(trackingId) { success, error in
    // Code
}

Implement Error Handling for Debugging​

In order to debug whether or not the Insurance APIs are being called successfully from your host application, implement the appropriate error handling for all Insurance APIs. This will give you feedback on whether the Insurance API was a success or a failure upon use.

Below is a sample implementation for error handling.

//Period 2 API as an example
Fairmatic.startDriveWithPeriod2(trackingId) { success, error in
    if success {
        print("Insurance period 1 successfully called. Manual tracking starting.")
    } else if let error = error {
        print("Error encountered while calling period: \(error.localizedDescription)")
    }
}

Refer to our sample implementation for a recommended approach to handling Insurance API errors. Some errors are not functionally inhibiting, so keep that in mind when handling errors: i.e. FairmaticErrorInsurancePeriodSame warns the application that the same Period API has been called twice, but does not affect any ongoing functionality of the SDK.

Switching Between Insurance APIs​

To switch between Insurance APIs, there’s no need to call an intermediate API. You can safely call the subsequent Insurance API to start the next period you’re going to.

For example, when switching from Period 2 to Period 3, if you’re currently in an ongoing Period 2 trip, you can safely call startDriveWithPeriod3() and the SDK will switch you into Period 3.

Testing the Insurance APIs​

Now that you’ve implemented all the Insurance APIs that you’ll be using, it’s time to test each of them to ensure that they’re in working order. The best way of testing is to go through an example use case of your host application. Below are some items to check off that will verify that your integration is correct.

  • Does stopPeriod() API trigger any time a driver goes “offline” or when they’re not “on-duty”?
  • Does startDriveWithPeriod1() API start a drive when the corresponding signal is given from the host application?
  • Does startDriveWithPeriod2() API start a drive when the corresponding signal is given from the host application?
  • Does startDriveWithPeriod3() API start a drive when the corresponding signal is given from the host application?
  • Does going through an example use case of your host application trigger all the relevant periods properly?

Please only use the checklist items that apply to your use case.

Disable SDK [Optional step]​

Call the teardown() API when the driver is no longer working with the application and logs out. This will completely disable the SDK on the application.

Fairmatic.teardown { [weak self] in
    print("Fairmatic SDK torn down")
}