Partnership APIs at Ethos
Brian Lambert, Software Engineer
In pursuit of Ethos’ quest to protect the next one million families, we have worked to expand beyond our D2C and agent channels into the enterprise space. As part of this initiative, we collaborated with our partners to better understand their needs and how Ethos could best support them. One of our current and potential partners’ key desires was to control the branding and UX experience for customers, while relying on our APIs to handle the backend process. Subsequent to these discussions, the decision was made to expose the power of Ethos’s technologies, including our underwriting and interview engines, through a set of APIs. These APIs allow our partners to not only retrieve customized quotes, but also conduct interviews and instant underwriting, collect the required policy and billing information, and generate signed policy documents using Ethos’s technology. Our partners were thus able to build and customize their experiences while benefiting from Ethos’s technologies.
With the above charter in hand, how did we accomplish delivering these APIs, in a safe and secure manner, all while keeping outcomes consistent with our other verticals? We can divide our approach into a few key sections, auth and data security, stream processors, and general system improvements.
Authorization and Data Security
Two important aspects of any system, particularly one processing the personal information disclosed in a life insurance application, are authorization and data security, given the sensitive nature of the collected data.
In designing our authorization system, we desired one that would enable small, individual payloads containing only the information required for a given API call. Therefore, we chose a form of token auth, wherein a bearer token generated is using a partner’s API key, which is then tied to an individual application session. A token’s session information is stored server side for use in the hydration of subsequent API calls. This authorization configuration allows invalidation by Ethos and, crucially, secures personal information.
In terms of data security, we took several steps to secure our applicants’ information. A crucial aspect of maintaining data security lies in the construction of our API interfaces and the data exposed. One facet of our approach was to reduce the amount of data required for a given API request to only include the necessary information for a given action. Each request is annotated with information and metadata previously collected by Ethos in a process called hydration. Similarly, our decision to assign session information to the token protects our applicant’s information by keeping details about the application and user internal to the Ethos ecosystem. Additionally, we only return the relevant information for the next step of an application, such as the information to ask the next interview question. Our error reports expose input errors relevant to our partners, while consuming further error information internally.
Stream Processors
A crucial aspect of our charter for delivering Ethos’s APIs to our partners was to do so in a manner that kept parity with our extant flows, while presenting a consistent external interface. Stream processors allow us to implement several improvements to the API flow, while also hooking into our extant internal APIs used for our first party application, reducing development time. Overall, our reuse of our internal APIs aids in the maintenance of consistent behavior across verticals, and reduces the time it takes to complete development.
Validate Request Schemas & Rate Limiting
An important aspect of our external gateway, beyond validating auth, is providing request schema validation. We have found that by moving validation to the edge, we are able to more quickly provide responses when expected fields are missing or contain the wrong type of data, and reduce response time, in particular for malformed requests. In addition to providing more responsive APIs, edge validation has reduced resource consumption by our core resources. In a similar vein, we applied rate limiting across multiple factors to mitigate the potential for DDoS attacks.
Gate Requests
An important aspect of the Ethos application flow is the requirement for the completion of predicate actions before a given action can be performed. We validate the completion of an action’s predicates at our stream processor layer. This system also allows our partners to implement flexible application flows tailored to their own particular needs and clientele. Our system accomplishes this through comparison of the completed steps against the predicates for any given action. This allows for Ethos to provide a snapshot of the current status of a given application showing all the completed actions and the currently available actions. It is this structure of constrained flexibility that enables our partners to provide a tailored solution to their clientele while fully leveraging Ethos’s technologies.
Hydrate API Requests
The stream processors are also responsible for the hydration of API requests. As previously described, we link a specific application session to a specific token, allowing us to retrieve the requisite information to hydrate our internal APIs, based on the user, application, request, etc. This hydration allows us to pull in specific information contained within the Ethos ecosystem about an application and apply it to the request. Internal hydration enables Ethos to reduce the requirements for external API users to maintain state, and reduces the potential for the potential leakage of sensitive user data. Additionally, request hydration reduces the size of the average API request, and helps ensure the accuracy and security of user application data.
Consolidate API Requests
Finally, our stream processors enabled us to streamline the API flow for our partners by combining internal API calls. One example of this lies in the validate and quote endpoint, which not only runs Ethos’s identity validation tasks, but upon validation will generate a customized quote using the validated applicant information. Another example of this consolidation would be merging the confirmation questions at the start of the interview flow into the interview flow, allowing us to present a simplified interface for that section of the application to the implementation team. This consolidation of API calls reduces the number of unique API calls required for partners to implement the Ethos API suite, not only reducing integration time but also reducing potential errors.
General Systems Improvements
In the process of our API work, we were able to include several general improvements to the Ethos ecosystem. These changes largely impacted our partner attribution workflows, improving the accuracy and performance of cross-application attribution. One of the largest changes was promoting attribution to an application level concept from the policy level. This change enables more accurate and rapid attribution of policies across an application lifecycle. It serves as the basis for the new attribution logic used by our marketing teams to deliver better ad targeting and improved analytics by tying the application journey together. We also streamlined and condensed a few of our API calls, improving performance and reducing the number of required API calls. One example of what we did to improve the experience from a user perspective was to consolidate multiple calls associated with the creation of an account and the pre-interview into a single api call, reducing the number of API calls from three to one.
Conclusion
In creating our partners APIs, we wanted to make a secure, and easy to use system. Through the intelligent use of our stream processors and linking sessions to specific tokens, we achieved our goal.
Brian Lambert joined Ethos in March, 2020 as a Software Engineer. When Brian isn’t working on various systems across the Ethos ecosystem, he enjoys reading, cooking, hiking, board games, video games, Magic the Gathering, learning about new things, and hanging out with his cats, Moe & Sugar. Interested in joining Brian’s team? Learn more about our career opportunities here.
