Nayya fits into your existing user flow to empower a seamless user experience. See the diagram below for an overview.

As you can see, your platform hands off to Nayya for decision support with the expected outcome being a set of plans bookmarked by the employee. Your platform can then retrieve those plans to create a great user experience and enable employees to make the best elections for themselves and their families.

Integrating in this way with Nayya is really quite simple, and we'll go through each step in detail.

You'll perform three main steps:

1. Mapping your system's entities to ours, including the use of external IDs.
2. Writing requests to configure employers, plans, employees, and eligibility in Nayya with support for external IDs.
3. Embed our user experience into yours.

That's it!
Let's look at this in more detail.

Step One: Mapping Entities

Nayya's entities are relatively basic and match up well with most benefit admin platforms. To support integration with external systems, Nayya now ingests and returns external IDs for entities.

Every POST request will include a response with the Nayya ID and external_id for the entities that you have created.

Here is the list of entities that you'll need to plan for, including their external IDs:

• Employer (name, address, etc., and external_id)
• Plan (name, type, deductible, other metadata, etc., and external_id)
• Employee (name, email, dob, last_four_ssn, premiums for plan selections, etc., and external_id)
• Eligibility (plans and rates for which a specific employee is eligible)

The keys in your system that represent these entities can be used to interact with the entities created in Nayya once they are live.

NOTE: When using your own internal IDs to CRUD with the API, ensure that you have created the entities in Nayya with your own internal IDs in order to allow for Nayya to establish the correct references. Your IDs must be used when the entities are initially created--Nayya's MODIFY API endpoints cannot accommodate updating IDs or changing from the use of Nayya IDs to the use of your own internal IDs.

So how do you provide this data? On to Step Two!

Step Two: Configuration

The creation and maintenance of this configuration data is expected and required to make Nayya’s decision support accurate and effective. Once we provide API credentials, your data will be a blank slate, ready for you to begin.

Send us the environment for which you want access (production, staging) at [email protected] and we will send you:

1. An API key for requests
2. Expiration date

Let's walk through how to set up all the entities that were mapped in Step One, including the support for external IDs.

Employers

Employers are the hub of all other relations that you'll be configuring.

First, set up an employer using the Add Employer action:

// Add Employer

POST /api/employers

{ "name": "Employer Name", "address": "employer address", "external_id": "<your_employer_id>"...}

This will return a 201 with the Nayya ID and external_id for that employer.

[Continue with the existing steps for Plans, Employees, and Eligibility, including instructions for adding external_id in the requests where applicable.]

Plans

Let's make some plans for which one or more employees might be eligible.

// Add Plan

POST /api/employers/{'external:<your_internal_employer_id>'}/plans

{"name": "Major Medical Gold Plan","external_id": "your_internal_plan_id", "medical_metadata": {...}, ... }

This will return a 201 with the Nayya ID and external_id for that plan.

And that's that! We can now enter employees into the system and get them ready to make some great decisions.

📘

NOTE

Adding new plans requires more data than the other entities in our system, and the documentation should be read carefully to make sure that all of the required data is supplied and will display correctly in the Nayya user experience.

Employees

We now arrive at employees.

Employees can be added in bulk, since you likely want to dump a large amount of them to us up front, though the endpoint does handle adding one at a time, if that is your preference.

// Add One or More Employees

POST /api/employer/{'external:<your_internal_employer_id>'}/employees

[{"first_name": "Gloria", "external_id":"your_internal_employee_id_1" ...}, {"first_name": "Antoine",  "external_id":"your_internal_employee_id_2" ...}]

ID's for all added employees are returned in a 201 request so that you can map them to users in your system.

📘

NOTE

The Nayya employee ID is needed in Step 4: Encode and Add JWT to URL as a part of our auth flow.

Eligibility

The last thing for configuration is eligibility. How do you tell Nayya which plans an employee has access to and at what rate?

This is done by specifying all of the plans and rates for an employee in a single payload:

// Attach Eligibility

PUT /api/employees/{'external:<your_internal_employee_id>'/eligibility

[{id: <plan id>, rate: { e_only: 23.3, e_spouse: 33.3, ... }}, {...}] OR 
[{id: <your_internal_plan_id>, rate: { e_only: 23.3, e_spouse: 33.3, ... }}, {...}]

(Please refer to the docs for the exact structure of this payload.)

It is important that this eligibility payload is sent over close to the time that the employee will be going through the Nayya experience.

Eligibility and rates change as things in your system change, so sending it close to just-in-time for them to come through the Nayya experience is best.

Configuration is now done! Let's finalize the integration by embedding the Nayya experience in your web app in Step Three.

Step Three: Embed Nayya App iframe

For a seamless user flow, Nayya can be embedded in an iframe directly in your web app.

Note: If you are not integrating with Nayya using the iframe, congratulations! You have completed the necessary integration-related steps to get started using Nayya and can skip the rest of the content on this page.

To proceed with embedding an iframe, you can follow these next five steps:

1. Choose a secret for signing

Nayya accepts a JWT token signed with RS256 encoding as authentication. You will need to create a private/public key combination, providing Nayya with the public key so that we can verify you as the signer.

Send us the public key via email to [email protected] and we will send you:

1. Confirmation that it's configured
2. USID - the user ID (usid) that you must include in step 4 below

We recommend separate keys for different environments (production, staging, etc.).

2. Locate Transition Point

Next, locate the transition point in your user flow where it makes sense to go through Nayya decision support.

This should be before the employee is directed to select any plans that they'd like to participate in.

3. Add the iframe to your application.

It will look something like this:

<iframe
  src="https://app.nayya.com/choose/embed?token=<your token>"
  title="Nayya"
  width="1200px"
  height="900px">
</iframe>

4. Encode and Add JWT to URL

Add a signed JWT with authorization information and a exit URL as a GET param to the URL above.

There's a lot of good information out there on creating and managing JWTs, if you need help getting started working with them. The below example is merely pseudocode, but should give you an idea of the payload required when creating and signing.

JWT Payload Dictionary

• iss: The issuer name, i.e. your company name
• exit_url: This URL is where the iframe should break out to when the experience is over. It must have the same domain as the window in which the iFrame is being loaded.
• usid: The user ID is your API user ID, which the Nayya team provides to you in step 1 above.
• empe: The current employee’s Nayya user ID. This is returned with the response from POST /employees.
• exp: The expiration timestamp for this JWT. Usually 5 minutes is long enough, as long as you're generating a new expiration each time you create a JWT then using it immediately. The expiration date must be in the future. This should be formatted as a Unix timestamp.
• iat: The time the token was issued, which must be in the past.

// pseudocode

sample_jwt_payload = {
  "iss": "Your Platform",
  "exit_url": "https://your.desired.redirect",
  "usid": "3aoprgpahg2-auohpga4-78ef-2oi9-fc5w",
  "empe": "auohpga4-78ef-2oi9-fc5w-3aoprgpahg2",
  "exp": 1613682529,
  "iat": 1516239022
}

token = <sign with your secret and generate the token using the RS256 encryption algorithm via a generation method of your choosing>

You'll need to append this token as a parameter to the URL you provide the iframe, so it will end up looking like this:

<iframesrc="https://app.nayya.com/choose/embed?token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJUZXN0IElzc3VlciIsImVtcGUiOiI4NWNiODI2ZS01N2ViLTQ3ZGMtYTA4OC04YjUxZDM4OWJhMzYiLCJ1c2lkIjoiODAyMTRlNGUtOGIyZS00YTk4LTljMDEtNDQ3MTNkOGQ1YTM0IiwiZXhpdF91cmwiOiJodHRwczovL3N0YWdpbmcubmF5eWEuY29tLyIsImV4cCI6MTcwMjg1NzIwOCwiaWF0IjoxNjAyODUzNjA4fQ.Ccomi8oVU1Kao0S25SghA-hs_qxA9_e8IU499G52AgRLVW9tu-XPCQn_jVFYJ8Z80CPG65X8vePgcIXE5bJwiHif9gQJ3lNERcfrRMyPNGdXeZC9irNr3LkNaZafK9qlTNiPK1pBplCbGMsXJTteRzi_of86SA1xbOXXzcG0Zuwr_MUvZgXlJP2iLmqNvJxG66W3L4xPCxs0C1ayqfCZOOzf5l_9B-PeTxUKdcI8HcBY7_okNHuTHBPigDGDiFAKwZEIZVkQepM6_jzLmzvuhBw0Gz7OedBiO2Ro8q1wMDpSvP0aj6PyfjN6GCRNhehfXrmmyhObW4ZehHb8efjVcQ"
  title="Nayya"
  width="1200px"
  height="900px">
</iframe>

5. Fetch Employee-Bookmarked Plans from Nayya

Pull the user's plan choices from Nayya at: GET /api/employees/external:{your_employee_id}/choices

We'd recommend that the exit_url you provide in the JWT should be a route that will synchronously request employee choices from Nayya, cache them in your system, then optionally bust the iframe and redirect the user to the appropriate page to finalize their decisions in your system.

This has worked really well in our experience!