Managing benefits for an engagement

Overview

The Benefits API enables you to manage benefits for EOR and Contractor engagements through Oyster’s platform.

This guide covers the end-to-end workflow for benefits management — from listing available offerings to provisioning packages, tracking enrollments, and requesting additional benefits.

Note for Reseller partners using the API - you will need to use the X-Oyster-Customer-Id header for all of the calls in this guide. For more information, see the Reseller guide to using the Oyster API.

Benefits Process Flow Diagram

flowchart TD
    A[List Available Benefits] --> B[Provision Benefits]
    B --> C[List Provisioning Benefits]
    C --> D[Track Enrollments]
    
    E[Request Additional Benefits] --> B
    subgraph States
        S1[REQUESTED]
        S2[APPLIED]
        S3[IN_PROGRESS]
        S4[ENROLLED]
        S5[PROVISIONED]
        S6[CANCELED]
        S7[FINISHED]
        S8[OPTED_OUT]
    end

 
    S1 --> S2 --> S3 --> S4
    S4 --> S6
    S4 --> S7
    S4 --> S8
    S5 --> S2

1. List Available Benefits

Before provisioning any benefits, first check what benefits are available for your engagement using Retrieve an employment's available benefits offerings.

When to use

Before provisioning any benefits
When reviewing available options for an engagement
To get plan IDs needed for provisioning

Example Request

curl --request GET \
     --url https://api.oysterhr.com/v0.1/benefits/engagements/ENGAGEMENT_ID/offerings \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Example Response – JSON

{
  "data": {
    "supplementary": {
      "plans": [
        {
          "id": "Bbc51b6b",
          "link": "http://example.com",
          "name": "Premium",
          "providerName": "Safety Wing",
          "category": "HEALTH",
          "guideUrl": "http://example.com/guide",
          "estimatedPrice": {
            "decimal": "70.0",
            "currencyCode": "EUR"
          },
          "fee": null
        }
      ]
    },
    "packages": [
      {
        "id": "B9965d2e",
        "name": "Essential package",
        "fee": null,
        "plans": [
          {
            "id": "D4c07300",
            "link": "http://example.com",
            "name": "Standard",
            "providerName": "Safety Wing",
            "category": "HEALTH",
            "guideUrl": "http://example.com/guide",
            "estimatedPrice": {
              "decimal": "45.0",
              "currencyCode": "EUR"
            }
          }
        ]
      }
    ]
  }
}

2. Provision Benefits

Once you’ve selected your benefits, use the Provision benefits endpoint to set them up. To know what acceptable values to use in your request, call the Retrieve benefits ruleset.

Important: This is a PUT request — every submission replaces previous provisioning.

Pre-conditions

Engagement must not be engaged yet

Example request

{
  "supplementary": {
    "plans": [
      {
        "id": "PLAN_ID",
        "employer_contributions": {
          "team_member": 0.5,
          "max_dependents_covered": 4,
          "dependents": 0.25
        }
      }
    ]
  },
  "package": {
    "id": "PACKAGE_ID",
    "plans": [
      {
        "id": "PLAN_ID",
        "employer_contributions": {
          "team_member": 0.55,
          "max_dependents_covered": 6,
          "dependents": 0.35
        }
      }
    ]
  }
}

Example Request – Bash

curl --request PUT \
     --url https://api.oysterhr.com/v0.1/benefits/engagements/ENGAGEMENT_ID/provisioning \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE' \
     --header 'content-type: application/json' \
     --data '{
       "package": {
         "id": "B9965d2e"
       }
     }'

Example Response – JSON

{
  "data": {
    "supplementary": {
      "enrollments": []
    },
    "packaged": {
      "enrollments": [
        {
          "id": "B552cefb",
          "plan": {
            "id": "D4c07300",
            "link": "http://example.com",
            "name": "Standard",
            "providerName": "Safety Wing",
            "category": "HEALTH",
            "guideUrl": "http://example.com/guide",
            "estimatedPrice": {
              "decimal": "50.0",
              "currencyCode": "USD"
            }
          },
          "package": {
            "id": "B9965d2e",
            "name": "Competitive package",
            "plans": [
              {
                "id": "D4c07300",
                "link": "http://example.com",
                "name": "Standard",
                "providerName": "Safety Wing",
                "category": "HEALTH",
                "guideUrl": "http://example.com/guide",
                "estimatedPrice": {
                  "decimal": "50.0",
                  "currencyCode": "USD"
                }
              }
            ]
          },
          "state": "PROVISIONED",
          "employerContribution": {
            "dependents": 0.35,
            "maxDependentsCovered": 6,
            "teamMember": 0.55
          }
        }
      ]
    }
  }
}

3. List Provisioning Benefits

To confirm successful provisioning, view current benefit structure, and check employer contributions use the Retrieve an employment's provisioned benefits endpoint.

Example Response – JSON

{
  "data": {
    "supplementary": {
      "enrollments": []
    },
    "packaged": {
      "enrollments": [
        {
          "id": "Bdae6827",
          "plan": {
            "id": "Je54b1c4",
            "link": "https://benefits-plan-external-link-1.example.com",
            "name": "standard",
            "providerName": "Borer-Schaden",
            "category": "HEALTH",
            "guideUrl": "https://benefits-plan-guide-url-1.example.com"
          },
          "package": {
            "id": "B9965d2e",
            "name": "Essential package"
          },
          "state": "ENROLLED"
        }
      ]
    }
  }
}

4. Track Enrollments

To see a list of all enrollments for an engaged team member use the Retrieve an engagement's enrollments endpoint.

Example Response – JSON

{
  "data": [
    {
      "id": "Bdae6827",
      "plan": {
        "id": "Je54b1c4",
        "link": "https://benefits-plan-external-link-1.example.com",
        "name": "standard",
        "providerName": "Wolff Group",
        "category": "HEALTH",
        "guideUrl": "https://benefits-plan-guide-url-1.example.com"
      },
      "package": {
        "id": "B9965d2e",
        "name": "Essential package"
      },
      "state": "ENROLLED",
      "employerContribution": {
        "dependents": 100,
        "teamMember": 100
      }
    }
  ]
}

5. Request Additional Benefits (optional)

You can request optional supplementary (add-on) plans for already engaged team members by using the Request benefits endpoint.

Payload Example

{
  "plan_id": "ANYSTRONGID",
  "employer_contribution": {
    "team_member": 55.5,
    "dependents": 25.2,
    "max_dependents_covered": 4
  }
}

Example Response – JSON

{
  "data": {
    "id": "F08d621d",
    "plan": {
      "id": "Bbc51b6b",
      "name": "Pension",
      "providerName": "Test nationale nederlanden",
      "category": "PENSION"
    },
    "state": "REQUESTED",
    "employerContribution": {
      "dependents": 0.35,
      "maxDependentsCovered": 6,
      "teamMember": 0.55
    }
  }
}