Skip to content

Plan Rollouts API (v1)

Download OpenAPI description
swagger.json
swagger.yaml
Languages
Servers
Sandbox

https://api.rollouts.sb3.plannotice.com/

Production

https://api.planrollouts.com/

OAuth

Operations

Participants

Operations

Request Rollout Notice

Request

This API submits a Participant Rollout Request to initiate the sending of a rollout notice.

Body
Array [
erisaEINstringnon-empty^\d{2}-\d{7}$required

Erisa EIN must be in the format XX-XXXXXXX (e.g., 12-3456789)

erisaPlanNumberstringnon-empty^\d{3}$required

Erisa Plan Number must be exactly 3 digits (e.g., 123).

erisaPlanNamestringnon-emptyrequired

Erisa Plan Name

planSponsorCompanystringnon-emptyrequired

Plan Sponsor Company

externalReferenceIdstring or null[ 0 .. 100 ] characters

External reference ID associated with the rollout notice.

reasonstringnon-empty^(SBR|TERM)$required

The reason the rollout is being requested. Valid values: SBR or TERM

firstNamestring[ 0 .. 100 ] charactersrequired

Participant First Name

lastNamestring[ 0 .. 100 ] charactersrequired

Participant Last Name

ssnstring or null[ 0 .. 11 ] characters^(?:\d{9}|\d{3}-\d{2}-\d{4})$

SSN in 9-digit or XXX-XX-XXXX format. Required if ExternalReferenceId is empty.

addressLine1stringnon-emptyrequired

Participant Address Line 1

addressLine2string or null

Participant Address Line 2

citystringnon-emptyrequired

Participant City

statestringnon-emptyrequired

Participant State

zipstringnon-emptyrequired

Participant Zip

countryCodestring or null^$|^US$

Participant Country Code (must be 'US' if provided).

totalBalancenumber(double)

Participant Total Balance. Required for TERM.

vestedBalancenumber or null(double)

Participant Vested Balance. Required for SBR.

balanceAsOfstring(date-time)required

Balance as of

gracePeriodinteger(int64)required

The amount of time the participant has to respond to the rollout notice.

Default 30
noticeLogoUrlstringnon-emptyrequired

Notice Logo Url

noticeFileContentUrlstringnon-emptyrequired

Notice File Content Url

helpNamestringnon-emptyrequired

The name of the entity the participant should contact for assistance.

helpPhonestringnon-emptyrequired

The phone number the participant should call for help.

helpWebsitestring or null

The website the participant should visit for help.

helpEmailstring or null

The email address the participant should use for help.

helpAddressLine1stringnon-emptyrequired

Help Address Line 1

helpAddressLine2string or null

Help Address Line 2

helpCitystringnon-emptyrequired

Help City

helpStatestringnon-emptyrequired

Help State

helpZipstringnon-emptyrequired

Help Zip

helpCountryCodestring or null^$|^US$

Help Country Code (must be 'US' if provided).

]
curl -i -X POST \
  https://api.rollouts.sb3.plannotice.com/api/v1/Participants \
  -H 'Content-Type: application/json' \
  -d '{
    "erisaEIN": "12-3456789",
    "erisaPlanNumber": "001",
    "erisaPlanName": "Plan 1",
    "planSponsorCompany": "ABC Company",
    "externalReferenceId": "987654321",
    "reason": "SBR",
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789",
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "city": "Anytown",
    "state": "CA",
    "zip": "12345",
    "countryCode": "US",
    "totalBalance": 1000,
    "vestedBalance": 10,
    "balanceAsOf": "2025-11-04T12:56:13.1265208Z",
    "gracePeriod": 30,
    "noticeLogoUrl": "Add Your Notice Logo URL",
    "noticeFileContentUrl": "Add Your Notice File Content URL",
    "helpName": "Support Team",
    "helpPhone": "555-555-5555",
    "helpWebsite": "www.support.com",
    "helpEmail": "help@support.com",
    "helpAddressLine1": "123 Main St",
    "helpAddressLine2": "Apt 4B",
    "helpCity": "Anytown",
    "helpState": "CA",
    "helpZip": "12345",
    "helpCountryCode": "US"
  }'

Responses

OK

Bodyapplication/json
noticeParticipantRequestIdstring(uuid)
Response
application/json
{
  "noticeParticipantRequestId": "bb3cdece-5edb-44c0-a5e3-55df5a0571ae"
}

Get Status

Request

This API fetches the status of rollout notices based on Erisa EIN, Erisa Plan Number, SSN, and externalReferenceId. At least one parameter (Erisa EIN, Erisa Plan Number, ssn, or externalReferenceId) must be provided. If multiple parameters are used, they will be ANDed together to create the results.

Query
erisaEinstring

The Erisa EIN associated with the rollout notice.

erisaPlanNumberstring

The Erisa Plan Number associated with the rollout notice.

ssnstring

The SSN associated with the rollout notice.

externalReferenceIdstring

An external reference ID associated with the rollout notice.

skipinteger(int32)

Number of records to skip before returning results.

takeinteger(int32)

Maximum number of records to return.

curl -i -X GET \
  'https://api.rollouts.sb3.plannotice.com/api/v1/Participants/status?erisaEin=string&erisaPlanNumber=string&ssn=string&externalReferenceId=string&skip=0&take=0'

Responses

OK

Bodyapplication/jsonArray [
noticeParticipantRequestIdstring(uuid)

Unique identifier for the notice participant request.

erisaEINstring or null

ERISA Employer Identification Number associated with the plan sponsor.

erisaPlanNumberstring or null

ERISA plan number associated with the participant's plan.

externalReferenceIdstring or null

External Reference Id passed in the rollout notice request. Empty string if it was not provided

reasonstring or null

The reason the rollout is being requested. Valid values: SBR or TERM

firstNamestring or null

Participant First Name

lastNamestring or null

Participant Last Name

ssnstring or null[ 0 .. 9 ] characters

Participant SSN passed in the rollout notice request. Empty string if it was not provided

addressLine1string or null

Participant Address Line 1

addressLine2string or null

Participant Address Line 2

citystring or null

Participant City

statestring or null

Participant State

zipstring or null

Participant Zip

countryCodestring or null

Participant Country Code

totalBalancenumber or null(double)

Participant Total Balance. Required For TERM

vestedBalancenumber or null(double)

Participant Vested Balance. Required For SBR

deliveryStatusstring or null

Delivery Statuses:

  • Pending: – a request for the rollout has been accepted and is going through Plan Notices internal processes.
  • Sent: The request has been mailed
  • Success: The mail was successfully delivered
  • ReturnToSender: The mail could not be delivered and was returned to the sender by the postal service.
  • Undeliverable: The mail could not be delivered and was not returned (e.g., due to an invalid address or recipient refusal).
noticeIdstring or null(uuid)

The NoticeId created for the Rollout

gracePeriodinteger or null(int64)

The amount of time the participant have to respond to the rollout notice

gracePeriodExpirationstring or null(date-time)

The exact date and time when the participant's response deadline for the rollout notice expires.

skippedboolean

Indicates whether the participant was skipped during the processing of the notice participant request.

skippedReasonstring or null

Specifies the reason why the participant was skipped during the notice participant request processing.

]
Response
application/json
[
  {
    "noticeParticipantRequestId": "bb3cdece-5edb-44c0-a5e3-55df5a0571ae",
    "erisaEIN": "string",
    "erisaPlanNumber": "string",
    "externalReferenceId": "string",
    "reason": "string",
    "firstName": "string",
    "lastName": "string",
    "ssn": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "countryCode": "string",
    "totalBalance": 0.1,
    "vestedBalance": 0.1,
    "deliveryStatus": "string",
    "noticeId": "883819fa-2259-411f-a626-cf7cd9f1db6f",
    "gracePeriod": 0,
    "gracePeriodExpiration": "2019-08-24T14:15:22Z",
    "skipped": true,
    "skippedReason": "string"
  }
]

Get Status

Request

This API fetches the status of notices based on Erisa EIN and Erisa Plan Number or date range.

Body
erisaPlanRecordsArray of objects or null(ErisaPlanViewModel)
fromstring or null(date-time)

Start of the date range filter (in UTC).

tostring or null(date-time)

End of the date range filter (in UTC).

skipinteger or null(int32)

Number of records to skip before returning results.

takeinteger or null(int32)

Maximum number of records to return.

curl -i -X POST \
  https://api.rollouts.sb3.plannotice.com/api/v1/Participants/status \
  -H 'Content-Type: application/json' \
  -d '{
    "erisaPlanRecords": [
      {
        "erisaEIN": "12-3456789",
        "erisaPlanNumber": "001"
      },
      {
        "erisaEIN": "98-7654321",
        "erisaPlanNumber": "002"
      }
    ],
    "from": "2025-10-05T12:56:13.1309707+00:00",
    "to": "2025-11-04T12:56:13.1309719+00:00",
    "skip": 0,
    "take": 100
  }'

Responses

OK

Bodyapplication/jsonArray [
noticeParticipantRequestIdstring(uuid)

Unique identifier for the notice participant request.

erisaEINstring or null

ERISA Employer Identification Number associated with the plan sponsor.

erisaPlanNumberstring or null

ERISA plan number associated with the participant's plan.

externalReferenceIdstring or null

External Reference Id passed in the rollout notice request. Empty string if it was not provided

reasonstring or null

The reason the rollout is being requested. Valid values: SBR or TERM

firstNamestring or null

Participant First Name

lastNamestring or null

Participant Last Name

ssnstring or null[ 0 .. 9 ] characters

Participant SSN passed in the rollout notice request. Empty string if it was not provided

addressLine1string or null

Participant Address Line 1

addressLine2string or null

Participant Address Line 2

citystring or null

Participant City

statestring or null

Participant State

zipstring or null

Participant Zip

countryCodestring or null

Participant Country Code

totalBalancenumber or null(double)

Participant Total Balance. Required For TERM

vestedBalancenumber or null(double)

Participant Vested Balance. Required For SBR

deliveryStatusstring or null

Delivery Statuses:

  • Pending: – a request for the rollout has been accepted and is going through Plan Notices internal processes.
  • Sent: The request has been mailed
  • Success: The mail was successfully delivered
  • ReturnToSender: The mail could not be delivered and was returned to the sender by the postal service.
  • Undeliverable: The mail could not be delivered and was not returned (e.g., due to an invalid address or recipient refusal).
noticeIdstring or null(uuid)

The NoticeId created for the Rollout

gracePeriodinteger or null(int64)

The amount of time the participant have to respond to the rollout notice

gracePeriodExpirationstring or null(date-time)

The exact date and time when the participant's response deadline for the rollout notice expires.

skippedboolean

Indicates whether the participant was skipped during the processing of the notice participant request.

skippedReasonstring or null

Specifies the reason why the participant was skipped during the notice participant request processing.

]
Response
application/json
[
  {
    "noticeParticipantRequestId": "bb3cdece-5edb-44c0-a5e3-55df5a0571ae",
    "erisaEIN": "string",
    "erisaPlanNumber": "string",
    "externalReferenceId": "string",
    "reason": "string",
    "firstName": "string",
    "lastName": "string",
    "ssn": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "countryCode": "string",
    "totalBalance": 0.1,
    "vestedBalance": 0.1,
    "deliveryStatus": "string",
    "noticeId": "883819fa-2259-411f-a626-cf7cd9f1db6f",
    "gracePeriod": 0,
    "gracePeriodExpiration": "2019-08-24T14:15:22Z",
    "skipped": true,
    "skippedReason": "string"
  }
]

Upload PDF File

Request

Accept PDF uploads, validate, store files, and return URLs for use in API requests.

Bodymultipart/form-data
filestring(binary)
curl -i -X POST \
  https://api.rollouts.sb3.plannotice.com/api/v1/Participants/upload-pdf \
  -H 'Content-Type: multipart/form-data' \
  -F file=string

Responses

OK

Bodyapplication/json
successboolean
dataobject(FileUploadData)
messagestring or null
Response
application/json
{
  "success": true,
  "data": {
    "fileName": "string",
    "fileUrl": "string"
  },
  "message": "string"
}