ECHO Hub API (v1)

Download OpenAPI specification:Download

ECHO Health Inc.: Echo.Hub@echohealthinc.com

API Endpoints for the PPM clients.

SandBox url: https://sandbox.echohealthincapi.com
Production Url : https://api.echohealthincapi.com

Authentication

Authentication is a process by which a system verifies the identity of a user accessing this API.

x-ApiKey

The API key

Security Scheme Type: API Key
Header parameter name: x-ApiKey

x-ClientKey

The Client key

Security Scheme Type: API Key
Header parameter name: x-ClientKey

Authorization

This endpoint helps to generate the Authorization Token for accessing the endpoints.

Get Authorization Token

Once the user is authenticated, this endpoint generates an authorization token by using the API key and the Client key. This authorization token is valid for 30 minutes.

Securityx-ApiKey or x-ClientKey
Request
header Parameters
x-ApiKey
required
string (AuthenticationHeader)

This is the ApiKey which has to be passed in Headers to obtain the Token

x-ClientKey
required
string (AuthenticationHeader)

This is the ClientKey which has to be passed in Headers to obtain the Token

Responses
200

Success

get/api/v1/GetToken
Request samples 
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ReponseCode": "Response for Payment Response Code 001",
  • "ReponseCodeDesc": "Transaction Approved",
  • "TransLog": [
    ]
}
Premium Payment Management (PPM)
 Premium Payment Management (PPM)  is a web-based application that offers a seamless experience to manage the Individual Coverage Reimbursement plan of the employees, associated with businesses of all sizes.
 The application is accessible on the following supported web browsers:-


    

  • Google Chrome
    • 

  • Mozilla Firefox
    • 

  • Microsoft Edge
    • 



Enrollment
The Enrollment endpoint is used to enroll an employee in PPM. Enrollment generates either a card or bank account to be used for premium payment to the employee’s insurance carrier.  An employee can be enrolled up to 90 days in the future. Coverage start dates are always the first of the month. If the employer does not have funds at the time of enrollment, the employee will be in a “funding pending” status until funding is available. Once funds are available, the broker can use either the PPM UI or the Payment Inquiry endpoint to access the card or bank account information.
   
Deployed On:

     
    
       
  • Sandbox: YES
    • 
       
  • Prod   : YES
    • 
     


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
This endpoint is used to create enrollments for an employee to make premium payments to the insurance carrier.


APIFormIdentifierID
required
integer
 Default:  250002
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
EmployeeFirstName
required
string  [ 1 .. 30 ] characters 
This is the first name of the employee. Apostrophe(') is not a supported character for EmployeeFirstName.


 
EmployeeLastName
required
string  [ 1 .. 30 ] characters 
This is the last name of the employee. Apostrophe(') is not a supported character for EmployeeLastName.


 
CarrierCode
required
string <XXXXX> 
This is the unique ID assigned to the carrier that will be provided by ECHO.


 
Plan
required
string  [ 1 .. 30 ] characters 
This is the insurance plan chosen by the employee.


 
CoverageStartDate
required
string  <= 10 characters 
 Default:  "Date"
This is the insurance coverage start date or the plan's effective date not greater than 90 days after current date. Format - 'CSD is always the 1st of a month.(ie, 2023-04-01)'


 
Premium
required
string  [ 1 .. 8 ] characters 
 Default:  "Money"
This is the premium amount paid for an insurance plan. Not greater than $10000


 
EmployeeState
required
string <XX> 
This must be valid state code.


 
EmployeePayPremium
required
integer  <= 1 characters 
It is a boolean. This field indicates whether employees are paying their own premiums. Default to 0 until further notice.


 
EmployeeEmail
string  <= 50 characters 
This is the email address of the employee. REQUIRED if EmployeePayPremium = 1


 
EmployeePhoneNumber
string  [ 1 .. 10 ] characters 
This is the phone number of the employee. Numbers only.


 
EmployeeHireDate
string  <= 10 characters 
 Default:  "Date"
This is the hire date of the employee. (ie, 2023-01-15)


 
Location
string  [ 1 .. 30 ] characters 
This is the employer location on the employer ID.


 
ICHRAAllotted
string  [ 1 .. 8 ] characters 
 Default:  "Money"
This is the amount that the employer contributes towards the premium.


 
ReimbursementTier
string  [ 1 .. 60 ] characters 
This is the tier type specific to the enrollment. Needs to be valid tier type currently mapped to the employer. 


    

  • 'Employee Only'
    • 

  • 'Employee & Spouse'
    • 

  • 'Employee & Children'
    • 

  • 'Family'
    • 



 Please note that if the Reimbursement tier is not provided, enrollment will be created using 'Employee Only' as default.


 
Lives
integer  <= 1 characters 
This is the number of dependents including self.


 
DateOfBirth
string  <= 10 characters 
 Default:  "Date"
This is the date of birth of the employee. Supported date formats are MM/DD/YYYY and YYYY-MM-DD.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Enrollment]
Request samples 
application/json
{
  • "APIFormIdentifierID": 250002,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "EmployeeFirstName": "string",
  • "EmployeeLastName": "string",
  • "CarrierCode": "string",
  • "Plan": "string",
  • "CoverageStartDate": "Date",
  • "Premium": "Money",
  • "EmployeeState": "string",
  • "EmployeePayPremium": 0,
  • "EmployeeEmail": "string",
  • "EmployeePhoneNumber": "string",
  • "EmployeeHireDate": "Date",
  • "Location": "string",
  • "ICHRAAllotted": "Money",
  • "ReimbursementTier": "string",
  • "Lives": 0,
  • "DateOfBirth": "Date"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Payment Inquiry
The Payment Inquiry endpoint is used to access the card or bank account details for an enrollment.  If the “Effective from” date is not passed, the active payment method is returned. If there is a CPP or future year enrollment, make sure to use the “Effective From” date to indicate the appropriate enrollment.
  
Deployed On:

     
    
       
  • Sandbox: YES
    • 
       
  • Prod   : YES
    • 
     


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
The Payment Inquiry endpoint enables one to view the premium payment information against an enrollment.


APIFormIdentifierID
required
integer
 Default:  250001
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
EffectiveFrom
string  <= 10 characters 
 Default:  "Date"
This is the specific date the insurance policy becomes active and begins to provide the protection and benefits mentioned in the policy. Supported date formats- MM/DD/YYYY and YYYY-MM-DD.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Payment Inquiry]
Request samples 
application/json
{
  • "APIFormIdentifierID": 250001,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "EffectiveFrom": "Date"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Enrollment CPP
The Enrollment CPP (Carrier Plan Premium) endpoint is used to change an existing, enrolled employee’s insurance coverage in PPM.  Changing the carrier, plan, or premium for the enrollment can apply to the first day of the next month(s) within 90 days. If funds have already been pulled for the next month. this CPP change will apply to the following month, and a premium correction will be necessary for the next month.

 
Deployed On:

 
    
   
  • Sandbox: YES
    • 
   
  • Prod   : YES
    • 
 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
This endpoint will help to create a pending enrollment, which will be effective from the 1st of future month within the current coverage year.


APIFormIdentifierID
required
integer
 Default:  260525
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
CarrierCode
required
string <XXXXX> 
This is the unique ID assigned to the carrier that will be provided by ECHO.


 
Plan
required
string  [ 1 .. 50 ] characters 
This is the insurance plan chosen by the employee.


 
EffectiveFrom
required
string  <= 10 characters 
 Default:  "Date"
This is the insurance effective from date or the plan's effective date not greater than 90 days after current date. The format is YYYYMMDD. The 'Effective From' is always the 1st of a month (e.g., 2023-04-01).


 
Premium
required
string  [ 1 .. 8 ] characters 
 Default:  "Money"
This is the premium amount paid for an insurance plan. Not greater than $10000


 
ICHRAAllotted
required
string  [ 1 .. 8 ] characters 
 Default:  "Money"
This is the amount that the employer contributes towards the premium.


 
ReimbursementTier
required
string  [ 1 .. 60 ] characters 
This is the tier type specific to the enrollment. Needs to be valid tier type currently mapped to the employer. 


    

  • 'Employee Only'
    • 

  • 'Employee & Spouse'
    • 

  • 'Employee & Children'
    • 

  • 'Family'
    • 



 
Lives
required
integer  <= 1 characters 
This is the number of dependents including self.


 
Notes
required
string  <= 350 characters 
This is the  additional information or comments.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Enrollment CPP]
Request samples 
application/json
{
  • "APIFormIdentifierID": 260525,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "CarrierCode": "string",
  • "Plan": "string",
  • "EffectiveFrom": "Date",
  • "Premium": "Money",
  • "ICHRAAllotted": "Money",
  • "ReimbursementTier": "string",
  • "Lives": 0,
  • "Notes": "string"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Employee Transaction
The Employee Transaction endpoint is used to access the history of an employee's carrier transactions within a provided date range. If a specific date range is not provided, this endpoint will return the last two years of data. Transaction types include credits, debits and declines.
  
Deployed On:

     
    
       
  • Sandbox: YES
    • 
       
  • Prod   : YES
    • 
     


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
The Employee Transaction endpoint allows to fetch the history of an employee's transactional activities.


APIFormIdentifierID
required
integer
 Default:  270545
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
TransactionStartDate
string  <= 10 characters 
 Default:  "Date"
Transaction start date is the start date to specify the time frame for which transaction details related to the premium payments are required. The format used is MM/DD/YYYY.


 
TransactionEndDate
string  <= 10 characters 
 Default:  "Date"
Transaction end date is the end date to specify the time frame for which transaction details related to the premium payments are required.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Employee Transaction]
Request samples 
application/json
{
  • "APIFormIdentifierID": 270545,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "TransactionStartDate": "Date",
  • "TransactionEndDate": "Date"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Employee Termination
The Employee termination endpoint is used to deactivate the employee which cancels their enrollment and associated card or account. The termination date must be within the current month. The coverage end date is calculated to be the last day of the termination month.

 
Deployed On:

   
    
     
  • Sandbox: YES
    • 
     
  • Prod   : YES
    • 
   


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
This endpoint allows deactivating the employee and canceling his/her enrollment and associated card or account.


APIFormIdentifierID
required
integer
 Default:  270543
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
TerminationDate
required
string  <= 10 characters 
 Default:  "Date"
Termination date is the date on which an employee's employment officially ends. The termination date must be a valid date within the current month.


 
TerminationReason
required
string  [ 1 .. 100 ] characters 
These are the Termination Reasons specific to the employee termination.


    

  • Terminated
    • 

  • Medicare - Eligible
    • 

  • Spousal Coverage
    • 

  • Deceased
    • 

  • Employee Wants To Cancel Policy
    • 

  • Not Eligible - Due to Hours Worked
    • 

  • Other
    • 



 
Notes
string  [ 1 .. 500 ] characters 
Notes are the additional information or comments. Notes are mandatory if the termination reason is 'Other'.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Employee Termination]
Request samples 
application/json
{
  • "APIFormIdentifierID": 270543,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "TerminationDate": "Date",
  • "TerminationReason": "string",
  • "Notes": "string"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Employee Balance
The Employee Balance (Remainder) will be retrieved against this Coverage year. It ranges from 2020 through the upcoming year.


Deployed On:

  
    
    
  • Sandbox: YES
    • 
    
  • Prod   : YES
    • 
  


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
Once the user is authenticated, the Get Token endpoint generates an authorization token by passing the respective consumer's API key and Client key. This authorization token is valid for 30 minutes.


 
Request Body schema: application/json
required
This endpoint fetches the Employee Balance (Remainder) in a valid Coverage Year.


APIFormIdentifierID
required
integer
 Default:  270559
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
 Default:  "string"
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
EmployeeUniqueID
required
string  [ 1 .. 20 ] characters 
This is the employee's Social Security Number or the unique employee ID provided by the employer.


 
CoverageYear
required
integer  = 4 characters 
 Default:  "integer"
The Employee Balance (Remainder) will be retrieved against this Coverage year. It ranges from 2020 through the upcoming year.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Employee Balance]
Request samples 
application/json
{
  • "APIFormIdentifierID": 270559,
  • "EmployerTIN": "string",
  • "EmployeeUniqueID": "string",
  • "CoverageYear": "integer"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Transaction Number",
  • "TransLog": [
    ]
}
Employer (Development - In Progress)
Create Employer

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to onboard a new employer into the system. 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Employer details to be created.


APIFormIdentifierID
required
integer
 Default:  280872
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
CompanyName
required
string  [ 1 .. 100 ] characters 
Legal name of the company/organization.


Validation:


    

  • Company Name must start with alphanumeric and can contain only ( & - . ' ) special characters
    • 



 
AgencyName
string  [ 0 .. 100 ] characters 
Legal or trade name of the agency.


Validation:


    

  • Agency Name must start with alphanumeric and can contain only ( & - . ' ) special characters
    • 



 
ContactFirstName
required
string  [ 1 .. 100 ] characters 
First name of the primary contact person.


Validation:


    

  • Contact first name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
ContactLastName
required
string  [ 1 .. 100 ] characters 
Last name (surname/family name) of the primary contact person.


Validation:


    

  • Contact last name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
Address
required
string  [ 1 .. 250 ] characters 
Primary street address (e.g., house number and street name).


Validation:


    

  • Address must start with alphanumeric characters
    • 

  • Must not include the following special characters:  ! { } ~ ` | "
    • 



 
Address2
string  [ 0 .. 250 ] characters 
Secondary address information such as apartment, suite, or unit


 
City
required
string  [ 1 .. 50 ] characters 
City or locality of the business mailing address.


Validation:


    

  • City must start with a letter 
    • 

  • Must not include the following special characters:  [ ] { } / | \
    • 



 
StateCode
required
string  = 2 characters 
State, province, or region of the business mailing address.


Validation:


    

  • State Code must contain only letters
    • 



 
ZipCode
required
string  = 5 characters 
Postal/ZIP code for the address.


Validation:


    

  • Zip Code must contain only numbers
    • 



 
Email
required
string <email> 
Work email address of the primary contact.


Validation:


    

  • Email must start with alphanumeric and can only contain( - _ + @ .) special characters
    • 



 
RegisteredTIN
required
string  = 9 characters 
Tax Identification Number (jurisdiction-specific). Provide as digits without spaces unless formatting is required by your jurisdiction.


Validation:


    

  • RegisteredTIN must contain only numbers
    • 



 
APITIN
required
string  = 9 characters 
If a TIN is shared across multiple Employer groups, designate an APITIN to uniquely identify this employer 
group.


Validation:


    

  • APITIN must alphanumeric
    • 



 
PhoneNumber
required
string  = 10 characters 
Primary contact phone number: 


    

  • Must contain exactly 10 numeric digits without spaces, country code, or special characters.
    • 



 
LogoFileBinaryString
string <png or jpg> 
A Base64-encoded string representing the company's logo image. 


Validation :
  maxFileSize : 1 MB
  maxDimensions: 800 x 800 pixels


 
HQEmployer
boolean
 Default:  "false"
Indicates whether the employer is the headquarters (HQ) entity. true = HQ employer, false = not HQ.


 
ReceiveChildEmployersEmail
boolean
 Default:  "false"
Flag to determine if the HQ employer should receive emails for child employers. true = receive emails, false = do not receive.


 
RestrictUserAccess
boolean
 Default:  "false"
If an employer is restricted, the users under the employer do not have PPM UI access but they do received all enabled emails. true = login restricted, false = normal access.


 
EmployerContractBinaryString
required
string <pdf> 
This is Base64 string encoded value of Employer Contract.


Validation :
  maxFileSize : 5 MB 


 
RoutingNumber
required
string  = 9 characters 
A 9-digit ABA routing number used in the United States to identify financial institutions.
Must be exactly 9 digits and pass checksum validation as per ABA standards.


Validation:


    

  • RoutingNumber must contain only numbers
    • 



 
AccountNumber
required
string  [ 1 .. 17 ] characters 
The U.S. bank account number associated with the customer.
Typically ranges from 4 to 17 digits depending on the financial institution.


 
AccountType
required
string
The type of bank account. Must be one of:


    

  • C: Standard checking account.
    • 

  • S: Savings account.
    • 



 Enum: "C" "S"  
Responses 
200
Success


post/api/PPM/v1/Portal [Create Employer]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280872,
  • "CompanyName": "string",
  • "AgencyName": "string",
  • "ContactFirstName": "string",
  • "ContactLastName": "string",
  • "Address": "string",
  • "Address2": "string",
  • "City": "New York",
  • "StateCode": "NY",
  • "ZipCode": "10001",
  • "Email": "user@example.com",
  • "RegisteredTIN": "123456789",
  • "APITIN": "123456789",
  • "PhoneNumber": "2125551234",
  • "LogoFileBinaryString": "string",
  • "HQEmployer": false,
  • "ReceiveChildEmployersEmail": false,
  • "RestrictUserAccess": false,
  • "EmployerContractBinaryString": "string",
  • "RoutingNumber": "021000021",
  • "AccountNumber": "123456789012",
  • "AccountType": "C"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Edit Employer

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to Edit Employer. 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Employer details to be edited.


APIFormIdentifierID
required
integer
 Default:  280969
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.    


 
AgencyName
string  [ 0 .. 100 ] characters 
Legal or trade name of the agency.


Validation:


    

  • Agency Name must start with alphanumeric and can contain only ( & - . ' ) special characters
    • 



 
Address
string  [ 1 .. 250 ] characters 
Primary street address (e.g., house number and street name).


Validation:


    

  • Address must start with alphanumeric characters
    • 

  • Must not include the following special characters:  ! { } ~ ` | "
    • 



 
Address2
string  [ 0 .. 250 ] characters 
Secondary address information such as apartment, suite, or unit


 
City
string  [ 1 .. 50 ] characters 
City or locality of the business mailing address.


Validation:


    

  • City must start with a letter 
    • 

  • Must not includethe following special characters:  [ ] { } / | \
    • 



 
StateCode
string  = 2 characters 
State, province, or region of the business mailing address.


Validation:


    

  • State Code must contain only letters
    • 



 
ZipCode
string  = 5 characters 
Postal/ZIP code for the address.


Validation:


    

  • Zip Code must contain only numbers
    • 



 
APITIN
string  = 9 characters 
If a TIN is shared across multiple Employer groups, designate an APITIN to uniquely identify this employer  group.


 
EmployeeEligibilityDay
integer
 Default:  30
Defines the waiting period (in days) before an employee becomes eligible. Supported values are limited to 1, 30, 60, or 90 days


 Enum: 1 30 60 90  
LogoFileBinaryString
string <png or jpg> 
    

  • A Base64-encoded string representing the company's logo image. 
    

    • 

  • Size : 1 MB ((Width, Height)<=(800px, 800px))
    

    • 



 
HQEmployer
boolean
 Default:  "false"
Indicates whether the employer is the headquarters (HQ) entity. true = HQ employer, false = not HQ.


 
ReceiveChildEmployersEmail
boolean
 Default:  "false"
Flag to determine if the HQ employer should receive emails for child employers. true = receive emails, false = do not receive.


 
RestrictUserAccess
boolean
 Default:  "false"
If an employer is restricted, the users under the employer do not have PPM UI access but they do received all enabled emails. true = login restricted, false = normal access.


 
EmployerContractBinaryString
string <pdf> 
    

  • This is Base64 string encoded value of Employer Contract.
    

    • 

  • Size : 5 MB
    

    • 



 
RoutingNumber
string  = 9 characters 
A 9-digit ABA routing number used in the United States to identify financial institutions. Must be exactly 9 digits and pass checksum validation as per ABA standards.


 
AccountNumber
string  [ 1 .. 17 ] characters 
The U.S. bank account number associated with the customer.
Typically ranges from 4 to 17 digits depending on the financial institution.


 
AccountType
string
The type of bank account. Must be one of:


    

  • C: Standard checking account.
    • 

  • S: Savings account.
    • 



 Enum: "C" "S"  
Responses 
200
Success


post/api/PPM/v1/Portal [Edit Employer]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280969,
  • "EmployerTIN": "123456789",
  • "AgencyName": "string",
  • "Address": "string",
  • "Address2": "string",
  • "City": "New York",
  • "StateCode": "NY",
  • "ZipCode": "10001",
  • "APITIN": "123456789",
  • "EmployeeEligibilityDay": 30,
  • "LogoFileBinaryString": "string",
  • "HQEmployer": false,
  • "ReceiveChildEmployersEmail": false,
  • "RestrictUserAccess": false,
  • "EmployerContractBinaryString": "string",
  • "RoutingNumber": "021000021",
  • "AccountNumber": "123456789012",
  • "AccountType": "C"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Create Agency

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to create agency details. 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Add Agency details.


APIFormIdentifierID
required
integer
 Default:  281017
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
AgencyName
required
string  [ 1 .. 100 ] characters 
Legal name of the Agency/organization.


Validation:


    

  • Agency Name must start with alphanumeric and can contain only ( & - . ' ) special characters
    • 



 
ContactFirstName
string  [ 1 .. 100 ] characters 
First name of the primary contact person.


Validation:


    

  • Contact First Name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
ContactLastName
string  [ 1 .. 100 ] characters 
Last name (surname/family name) of the primary contact person.


Validation:


    

  • Contact Last Name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
Address
required
string  [ 1 .. 250 ] characters 
Primary street address (e.g., house number and street name).


Validation:


    

  • Address must start with alphanumeric characters
    • 

  • Must not include the following special characters:  ! { } ~ ` | "
    • 



 
Address2
string  [ 0 .. 250 ] characters 
Secondary address information such as apartment, suite, or unit


 
PhoneNumber
string  = 10 characters 
Primary contact phone number: 


    

  • Must contain exactly 10 numeric digits without spaces, country code, or special characters.
    • 



 
Email
string <email> 
Work email address of the primary contact.


Validation:


    

  • Email must start with alphanumeric and can only contains ( - _ + @ .) special characters
    • 



 
City
required
string  [ 1 .. 50 ] characters 
City or locality of the business mailing address. 


Validation:


    

  • City must start with a letter 
    • 

  • Must not includethe following special characters:  [ ] { } / | \
    • 



 
StateCode
required
string  = 2 characters 
State, province, or region of the business mailing address. 
Validation: - State Code must contain only alphabetic characters


 
ZipCode
required
string  = 5 characters 
Postal/ZIP code for the address.


Validation:


    

  • Zip Code must contain only numbers
    • 



 
Responses 
200
Success


post/api/PPM/v1/Portal [Create Agency]
Request samples 
application/json
{
  • "APIFormIdentifierID": 281017,
  • "AgencyName": "string",
  • "ContactFirstName": "string",
  • "ContactLastName": "string",
  • "Address": "string",
  • "Address2": "string",
  • "PhoneNumber": "2125551234",
  • "Email": "user@example.com",
  • "City": "New York",
  • "StateCode": "NY",
  • "ZipCode": "10001"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Create User

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to create user. 


Securityx-ApiKey or x-ClientKey 
Request 
Request Body schema: application/json
required
User details to be created 


APIFormIdentifierID
required
integer
 Default:  281029
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
UserType
required
string
Specifies the type of user to be created in the system.
The value determines which additional fields are required
and what role-based validations will be applied.


Allowed values:


    

  • AGENT: Creates an Agent user under an existing Agency.
    • 

  • BROKER: Creates a Broker user.
    • 



 
FirstName
required
string  [ 1 .. 100 ] characters 
Legal first name of the agent being created.
This value will appear in the application interface,
reports, and audit records.


Validation:


    

  • First Name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
LastName
required
string  [ 1 .. 100 ] characters 
Legal last name of the agent being created.
Used for identification, reporting, and official system records.


Validation:


    

  • Last Name must start with a letter and can contain only ( - . ' ) special characters
    • 



 
Email
required
string <email> 
Unique work email address of the agent. Email must start with alphanumeric and can only contains ( - _ + @ . ) special characters 


 
PhoneNumber
required
string  = 10 characters 
Primary contact phone number of the agent:


    

  • Must contain exactly 10 numeric digits without spaces, country code, or special characters.
    • 



 
AgencyName
required
string  [ 1 .. 100 ] characters 
Name of the agency with which the agent is associated. The agency must already exist in the system.


 
RoleType
required
string
Defines the agent’s access level within the system.
Allowed values:


    

  • AGENT: Standard agent access.
    • 

  • ADMINAGENT: Agent with administrative privileges within the agency.
    • 



 
AlertsReviewGroupMember
string
 Default:  "false"
Indicates whether the agent should be included in the Alerts Review Group. When set to "true", the agent will receive and review system-generated alerts .


 
RestrictUserAccess
string
 Default:  "false"
Indicates whether the agent’s access should be restricted. When set to "true", the agent’s visibility and operational permissions may be limited based on predefined access rules.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Create User]
Request samples 
application/json
{
  • "APIFormIdentifierID": 281029,
  • "UserType": "AGENT",
  • "FirstName": "string",
  • "LastName": "string",
  • "Email": "user@example.com",
  • "PhoneNumber": "1234567890",
  • "AgencyName": "string",
  • "RoleType": "ADMINAGENT",
  • "AlertsReviewGroupMember": "false",
  • "RestrictUserAccess": "false"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Employer Open Enrollment

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to add Enrollments to the existing Employers. 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Employer Open Enrollment details.


APIFormIdentifierID
required
integer
 Default:  280891
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
CoverageYear
required
string <yyyy> 
This is the year in which the open enrollment is active.


 
FundsPullDate
required
string <yyyy-MM-dd> 
 Default:  "Date"
The scheduled date for pulling Single Binder Debit. Must be within the coverage year and before the payment due date. PreNote must have been successful to trigger this pull.


 
SingleBinderDebit
required
string
 Default:  "Money"
    

  • Initial amount of money that we are pulling to start an open enrollment
    • 

  • Allowed value : Maximum of two decimal places.
    • 



 
ReserveAmount
string
 Default:  "Money"
    

  • The minimum balance maintained to cover premium payments.
    • 

  • Allowed value : Maximum of two decimal places.
    • 



 
ThresholdAmount
string
 Default:  "Money"
    

  • The minimum acceptable reserve level before triggering an automatic debit.
    • 

  • Allowed value : Maximum of two decimal places.
    • 

  • ThresholdAmount must be less than Reserve Amount
    • 



 
Responses 
200
Success


post/api/PPM/v1/Portal [Employer Open Enrollment]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280891,
  • "EmployerTIN": "stringstr",
  • "CoverageYear": 2025,
  • "FundsPullDate": "2025-10-25",
  • "SingleBinderDebit": 2000.31,
  • "ReserveAmount": 1000.01,
  • "ThresholdAmount": 150.01
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Edit Employer Enrollment

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to Edit Employer Enrollment. 


Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Edit Employer Open Enrollment details.


APIFormIdentifierID
required
integer
 Default:  280941
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager.


 
CoverageYear
required
integer  = 4 characters 
This is the year in which the open enrollment is active.


 
FundsPullDate
any <yyyy-MM-dd> 
 Default:  "Date"
The scheduled date for pulling Single Binder Debit. Must be within the coverage year and before the payment due date.


 
SingleBinderDebit
any
 Default:  "Money"
    

  • Initial amount of money that we are pulling to start an open enrollment
    • 

  • Allowed value : Maximum of two decimal places.
    • 



 
ReserveAmount
any
 Default:  "Money"
    

  • The minimum balance maintained to cover premium payments.
    • 

  • Allowed value : Maximum of two decimal places.
    • 



 
ThresholdAmount
any
 Default:  "Money"
    

  • The minimum acceptable reserve level before triggering an automatic debit.
    • 

  • Allowed value : Maximum of two decimal places.
    • 



 
Responses 
200
Success


post/api/PPM/v1/Portal [Edit Open Enrollment]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280941,
  • "EmployerTIN": "stringstr",
  • "CoverageYear": 2025,
  • "FundsPullDate": "2025-10-25",
  • "SingleBinderDebit": 2000.31,
  • "ReserveAmount": 1000.01,
  • "ThresholdAmount": 150.01
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}
Employer Status

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to fetch Employer status details. 


      

Securityx-ApiKey or x-ClientKey 
Request 
header Parameters
x-Authorization
required
string (xAuthorization) 
AuthToken obtained from GetToken Endpoint


 
Request Body schema: application/json
required
Employer Status details.


APIFormIdentifierID
required
integer
 Default:  280909
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Employer Status]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280909,
  • "EmployerTIN": "stringstr"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": {
    }
}
Employer Fee Setup

  

  
      Development :  
  
  
      In Progress 
  
  

  




 This endpoint is designed to create Employer fee setup. 


Securityx-ApiKey or x-ClientKey 
Request 
Request Body schema: application/json
required
Employer Fee Setup Details


APIFormIdentifierID
required
integer
 Default:  280969
This is a unique identifier that serves the purpose of identifying a particular request. It helps identify and map the request to the correct endpoint.


 
EmployerTIN
required
string  = 9 characters 
This is the 9-digit unique identifier of Employer issued by the IRS. Must exist in Premium Payment Manager. Alphanumeric characters are allowed, while special characters are not allowed.


 
FeeModel
required
string
Specifies the fee model to be applied for a particular employer.
This determines how fees are calculated and charged.


Supported Fee Models:


    

  • FF   → Flat Fee
    • 

  • OTF  → One-time Fee
    • 

  • FFPEPM → Flat Fee & Per Employee Per Month
    • 

  • PEPM → Per Employee Per Month
    • 



 
EffectiveFrom
required
string
This is the specific date from which the fee setup becomes effective and fee charges begin to apply based on the selected fee model (Flat Fee, One-Time Fee, Flat Fee And Per Employee Per Month, or Per Employee Per Month). Supported date format(YYYY-MM)


 
required
Array of objects (BrokerageFeeComponent)   [ 1 .. 5 ] items 
Brokerage fee components (ComponentName + Amount).


 
DirectACHFee
string
 Default:  "false"
Direct ACH processing fee .


 
Notes
string
This is the additional information or comments.


 
Responses 
200
Success


post/api/PPM/v1/Portal [Employer Fee Setup]
Request samples 
application/json
{
  • "APIFormIdentifierID": 280969,
  • "EmployerTIN": "123456789",
  • "FeeModel": "FF",
  • "EffectiveFrom": "2026-02",
  • "BrokerageFeeComponents": [
    ],
  • "DirectACHFee": "false",
  • "Notes": "Flat fee with direct ACH Charge"
}
Response samples 
application/json
Please scroll the above dropdown list for more response codes


{
  • "ResponseCode": "001",
  • "ResponseCodeDesc": "Successful Transaction",
  • "ResponseTransactionID": "Response Transaction ID",
  • "TransLog": [
    ]
}