2interact

Open Social Security Administration Inter-Application Communication Protocol


 

SSAXML API

Overview

The SSAXML API is a Layer 7 Inter-Application Protocol based on SOAP and supports various Markup Languages. It is schema-based and will grow to include approx.100 schemas. Each schema will handle specific segments of Social Security Administration Data such as Employers, Employees, Beneficiaries, Financial Institutions, Healthcare Providers, Individuals, Social Security Numbers, Benefit Contributions, Contribution Payments, Benefit Claims, Benefit Claims Payments, Documentation, Compliance, Delinquencies, Court Orders, Refunds, and Payment Adjustments. The aim of the SSAXML API is to enable software providers who provide software for Social Security Administration to communicate with each other using one Global SSA API that is open to all, thus lowering the cost to clients and providers.

The SSASXML API is a set of web services (servers) that are used to provide access to Interact SSAS Data and Processes to external Applications. External applications/systems will be able to use Web Service Clients to request a service from the SSAXML API. The SSAXML API is based on a REST API Architecture. It offers a mechanism that enables an application or service to access a resource within another application or service, in this case SSAS. The application or service that accesses resources is the client, and the application or service that contains the resource is the server.

Since SSAXML API is based on a RESTful design, clients of the service will benefit from the following key REST design principles:

Uniform interface – All API requests for the same resource look the same, no matter where the request comes from. The REST API ensures that the same piece of data, such as the name or email address of a user, belongs to only one uniform resource identifier (URI). Resources will contain every piece of information that the client might need.

Client-server decoupling – Client and server applications are completely independent of each other. The only information that the client application needs to know is the URI of the requested resource; it can’t interact with the server application in any other ways. Similarly, a server application cannot modify the client application other than passing it to the requested data via HTTP.

Statelessness – Each request needs to include all the information necessary for processing it. In other words, SSAXML APIs do not require any server-side sessions. Server applications aren’t allowed to store any data related to a client request.

Cacheability – When possible, resources are cacheable on the client or server side. Server responses also will contain information about whether caching is allowed for the delivered resource. This will improve performance on the client side, while increasing scalability on the server side.

Layered system architecture – In SSAXML APIs, the calls and responses can go through different layers. Client and server applications do not need to connect directly to each other. There may be a number of different intermediaries in the communication chain. Neither the client nor the server can tell whether it communicates with the end application or an intermediary.

SSAXML API Framework

The SSASXML API is based on REST API Server/Client Framework at the lower level, and consists of the following framework components at the higher level as shown in Figure-1:


Figure-1: SSAXML API Framework

Security – This component is used to handle the security and access control of the Web Service Clients. It defines each Web Service Client as a user with a User ID, Password, Public and Private Keys, License, and the Granular Access Control of the Web Service Client. Before any Web Service Client can talk to SSAS Web Service Server, it needs to be defined as a user and consumer of SSAXML Web Services (API). Once defined, the Web Service Client can connect through a URL and submit its credentials to be authenticated buy the Security component of the SSAXML API Framework.

Policies – Policies are used to define the general parameters and rules used by the Web Service Servers and include Web Service Servers definition, Transaction Types, Error Codes and Messages, Alert Codes and Messages, Web Service Messages XML Schemas, etc.

Configurations – These are configuration files used by the Web Service Servers that define how each Web Service Server is configured.

Transaction Types – Transaction type define all the transaction types that are handled by the API. There is one Transaction Type per Web Service Server. Once Web server Service handles one transaction type. Transaction types include Employer, Registration, Social Security Number, Social Security ID Card, Contribution Filing, Benefit Claim, Benefit Claim Payment, Social Security Statement, etc.

Actions – These are the actions that can be performed on a transaction type such as Create/Add, Update, Delete, Review, Approve, and Reject. When a client web service submits a request to the web service server it needs to specify the transaction type and the action.

Classes – Classes are used to implement the business logic and input control of each Web Service Server. Each Web Service Server is implemented using one PhP Class, which handles all the business logic and input control and output associated with the Transaction type handled by the Web Service Server.

Web Service Servers – Web Service Servers are the Web Services that provide services to the Web Service Clients. Each Web Service Server is responsible for handling one Transaction Type and is implemented using one PhP Class. The Web Service Servers are implemented using REST API framework and PhP.

Web Service Clients – Web Service Clients are the Web Services that request services from the Web Service Servers. Web Service Clients can be implemented in any language as long as they comply with the REST API guidelines. For a Web Service Client to access a Web Service Server, it needs a set of credentials and needs to know how to communicate with the Web Service Server through the API messaging Protocol.

Request Message – This is the message sent by the Web Service Client to the Web Service Server requesting specific service and data.

Response Message – This is the message sent by the Web Service Server to the Web Service Client as a response to the Web Service Client request.

SSAXML API Messaging Protocol

The SSAXML APII messaging protocol define the format of the messages sent between the Web Service Client and the Web Service Server and vice versa. At the low level, all messages sent between the requester (Web Service Client) and the provider (Web Service Server) and back, are REST http messages (request/response), HTTP is the carrier of the message, while at the high level, the API message includes more detail errors handling that go beyond HTTP errors/codes. SSAXML Messaging is based on the HTTP Request and Response Messaging Protocol described below:


Figure-2: Messaging Protocol

HTTP Request Message

  • Verb − Indicates the HTTP methods such as GET, POST, DELETE, PUT, etc.
  • URI − Uniform Resource Identifier (URI) to identify the resource on the server.
  • HTTP Version − Indicates the HTTP version. For example, HTTP v1.1.
  • Request Header − Contains metadata for the HTTP Request message as key-value pairs. For example, client (or browser) type, format supported by the client, format of the message body, cache settings, etc.
  • Request Body − Message content or Resource representation.

HTTP Response Message

  • Status/Response Code − Indicates the Server status for the requested resource. For example, 404 means resource not found and 200 means response is ok.
  • HTTP Version − Indicates the HTTP version. For example HTTP v1.1.
  • Response Header − Contains metadata for the HTTP Response message as key value pairs. For example, content length, content type, response date, server type, etc.
  • Response Body − Response message content or Resource representation.
  • Request Body − Message content or Resource representation.

The formats of the Request Messages from the Client and the Response Messages from the Servers are known as the Messages XML Schemas. The Messages Schemas are framed by Version Number, Transaction Type, and Action based on REST API Methods that require data in the body of the request pass the data as an XML block. In addition, all API methods return data in the response using an XML block.

The schema for the XML used in requests and response is available in a schema (.xsd) file. When you construct XML for a request, you must make sure that the XML block is well formed and that it conforms to the schema.

A client can ask for JSON representation whereas another client may ask for XML representation of the same resource to the server and so on. It is the responsibility of the REST server to pass the client the resource in the format that the client understands.

Examples

Below are examples of functionalities of a web Service Server called Employer Management:

No. URI HTTP Method POST body Result
1 /EmployerService/listEmployers GET Empty Returns a list of all employers.
2 /EmployerService/addEmployer POST JSON String Adds new employer.
3 /EmployerService/getEmployer/:id GET Empty Returns the details of an employer given employer ID

In the same Web Service Server Employer Management – an employer is a resource which is represented using the following XML or JSON format:

Resource: Employer using XML: 

    
     <employer>
        <id>3460</id>
        <name>Bakery LLC</name>
        <EID>97899</EID>
        <city>New York</city>
        <country>USA</country>
     </employer>

Resource: Employer using JSON:

 
      {
        "id":3460,
        "name":"Bakery LLC",
        "city:"New York",
        "country:"USA"
      }



Figure3 – SSAXML API Policy Setup

SSAS Module SSAXML API Transaction Types
Employer Management Employer Management
Registration Management Individual Management
Registration Information Changes
Financial Institution Management Financial Institute Registration
Social Security Number Management Social Security Number Application
Temporary SSN to Permanent Conversion
Social Security ID Card Management Social Security ID Card Application
Social Security Contribution Filing Management Employer Contribution Filing
SE Contribution Filing
VC Contribution Filing
Social Security Contribution Payments Management Contribution Payment
Receivables Management Invoice
Cashier and Payment Management Cashier
Cashier Opening Balance
Cashier Payments
Cashier Closing Balance
Penalties Management Penalty
Social Security Benefit Claims Management Sickness Benefit Claim
Maternity Benefit Claim
Maternity Grant Benefit Claim
Employment Injury Benefit Claim
Medical Benefit Claim
Funeral Grant Benefit Claim
Disablement Benefit Claim
Invalidity Benefit Claim
Death Benefit Claim
Retirement Benefit Claim
Survivor Benefit Claim
Social Security Benefit Payments Management Sickness Benefit Payment
Maternity Benefit Payment
Maternity Grant Benefit Payment
Employment Injury Benefit Payment
Medical Benefit Payment
Funeral Grant Benefit Payment
Disablement Benefit Payment
Invalidity Benefit Payment
Death Benefit Payment
Retirement Benefit Payment
Survivor Benefit Payment
Payables Management Voucher
Medical Visits and Diagnosis Management Healthcare Provider Patient Visit
Medical Referee Request
Contribution Refunds & Adjustments Management Contribution Refund Request
Contribution Refund Payment
Contribution Adjustment Request
Benefit Payment Adjustments Management Benefit Payment Adjustment Request
Compliance Management Compliance Audit
Audit Checklist
Audit Action
Legal Action
Lawsuit
Court Order
Arrear Installment Agreement Management Arrears Installment Agreement
Arrears Installment Payment
Delinquency Management Delinquency
Third Party Payment Management Third Party Payments
Social Security Statements Social Security Statement
Document Management Document
Award Letters Management Award Letter
GL Posting Contribution Payment GL Posting
Benefit Payment GL Posting
KYC Management KYC Update
Case Management Case


Appendix-C – Web Services Servers

Transaction Types Web Service Servers
Employer Management EmployerService
Individual Management IndividualService
Registration Information Changes RegistrationChangeService
Financial Institute Registration InstituteRegistrationService
Social Security Number Application SSNService
Temporary SSN to Permanent Conversion TempSSNConversionService
Social Security ID Card Application SSIDCardService
Employer Contribution Filing EmployerContributionFilingService
SE Contribution Filing SEContributionFilingService
VC Contribution Filing VCContributionFilingService
Contribution Payment ContributionPaymentService
Invoice InvoiceService
Cashier CashierService
Cashier Opening Balance CashierOpeningBalanceService
Cashier Payments Cashier PaymentsService
Cashier Closing Balance CashierClosingBalanceService
Penalty PenaltyService
Sickness Benefit Claim SicknessClaimService
Maternity Benefit Claim MaternityClaimService
Maternity Grant Benefit Claim MaternityGrantClaimService
Employment Injury Benefit Claim InjuryClaimService
Medical Benefit Claim MedicalClaimService
Funeral Grant Benefit Claim FuneralClaimService
Disablement Benefit Claim DisablementClaimService
Invalidity Benefit Claim InvalidityClaimService
Death Benefit Claim DeathClaimService
Retirement Benefit Claim RetirementClaimService
Survivor Benefit Claim SurvivorClaimService
Sickness Benefit Payment SicknessBenefitPaymentService
Maternity Benefit Payment MaternityBenefitPaymentService
Maternity Grant Benefit Payment MaternityGrantBenefitPaymentService
Employment Injury Benefit Payment InjuryBenefitPaymentService
Medical Benefit Payment MedicalBenefitPaymentService
Funeral Grant Benefit Payment FuneralBenefitPaymentService
Disablement Benefit Payment DisablementBenefitPaymentService
Invalidity Benefit Payment InvalidityBenefitPaymentService
Death Benefit Payment DeathBenefitPaymentService
Retirement Benefit Payment RetirementBenefitPaymentService
Survivor Benefit Payment SurvivorBenefitPaymentService
Voucher VoucherBenefitPaymentService
Healthcare Provider Patient Visit HealthcareProviderVisitService
Medical Referee Request MedicalRefereeRequestService
Contribution Refund Request ContributionRefundRequestService
Contribution Refund Payment ContributionRefundPaymentService
Contribution Adjustment Request ContributionAdjustmentRequestService
Benefit Payment Adjustment Request BenefitPaymentAdjustmentRequestService
Compliance Audit ComplianceAuditService
Audit Checklist AuditChecklistService
Audit Action AuditActionService
Legal Action LegalActionService
Lawsuit LawsuitService
Court Order CourtOrderService
Arrears Installment Agreement ArrearsInstallmentService
Arrears Installment Payment ArrearsInstallmentPaymentService
Delinquency DelinquencyService
Third Party Payments ThirdPartyPaymentService
Social Security Statement StatementService
Document DocumentService
Award Letter AwardLetterService
Contribution Payment GL Posting ContributionPaymentGLService
Benefit Payment GL Posting BenefitPaymentGLService
KYC Update KYCUpdateService
Case CaseService


Web Service Servers Description

EmployerService

  • Employer List
  • Employer by ID
  • Add New Employer
  • Update Employer
  • Delete Employer
  • Approve Employer
  • Activate Employer
  • Inactivate Employer

Employer List

HTTP Method
 GET
URI https://**********/****/***/**/EmployerService/listEmployers

 

XML Web Service Request Body: –

    
    <listEmployers>
       <user_id></user_id>
       <password></password>
       <public_key></public_key>
      <private_key></private_key>
    </listEmployers>

JSON Web Service Request Body: –

   
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": ""
    }

Get Employer by ID

HTTP Method GET
URI https://**********/****/***/**/EmployerService/getEmployer/800005

 

XML Web Service Request Body: –

   
    <getEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
    </getEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": ""
    }

Add New Employer

HTTP Method POST
URI https://**********/****/***/**/EmployerService/addEmployer

 

XML Web Service Request Body: –

    
    <addEmployer>
       <user_id></user_id>
       <password></password>
       <public_key></public_key>
       <private_key></private_key>
       <EIN_NUMBER></EIN_NUMBER>
       <ESSRN></ESSRN>
       <EMPLOYER_NAME></ EMPLOYER_NAME>
       <BUSINESS_TYPE></BUSINESS_TYPE>
       <EMPLOYER_GROUP></EMPLOYER_GROUP>
       <REGISTRATION_DATE></REGISTRATION_DATE>
       <TYPE_OF_EMPLOYER></TYPE_OF_EMPLOYER>
       <ACTIVE_STATUS></ACTIVE_STATUS>
       <DELINQUENT_STATUS></DELINQUENT_STATUS>
    </addEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": "",
      "EIN_NUMBER": "",
      "ESSRN": "",
      "EMPLOYER_NAME": "",
      "BUSINESS_TYPE": "",
      "EMPLOYER_GROUP": "",
      "REGISTRATION_DATE": "",
      "TYPE_OF_EMPLOYER": "",
      "ACTIVE_STATUS": "",
      "DELINQUENT_STATUS": ""
    }

Update Employer

HTTP Method PUT
URI https://**********/****/***/**/EmployerService/updateEmployer/800005

 

XML Web Service Request Body: –

    
    <updateEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <EIN_NUMBER></EIN_NUMBER>
      <ESSRN></ESSRN>
      <EMPLOYER_NAME></ EMPLOYER_NAME>
      <BUSINESS_TYPE></BUSINESS_TYPE>
      <EMPLOYER_GROUP></EMPLOYER_GROUP>
      <REGISTRATION_DATE></REGISTRATION_DATE>
      <TYPE_OF_EMPLOYER></TYPE_OF_EMPLOYER>
      <ACTIVE_STATUS></ACTIVE_STATUS>
      <DELINQUENT_STATUS></DELINQUENT_STATUS>
    </updateEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": "",
      "EIN_NUMBER": "",
      "ESSRN": "",
      "EMPLOYER_NAME": "",
      "BUSINESS_TYPE": "",
      "EMPLOYER_GROUP": "",
      "REGISTRATION_DATE": "",
      "TYPE_OF_EMPLOYER": "",
      "ACTIVE_STATUS": "",
      "DELINQUENT_STATUS": ""
    }

Delete Employer

HTTP Method DELETE
URI https://**********/****/***/**/EmployerService/deleteEmployer/800007

 

XML Web Service Request Body: –

   
    <deleteEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
    </deleteEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": ""
    }

Approve Employer

HTTP Method PUT
URI http://**********/****/***/**/EmployerService/approveEmployer/800006

 

XML Web Service Request Body: –

    
    <approveEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <ESSRN_ISSUED_NUMBER></ESSRN_ISSUED_NUMBER>
      <ESSRN_APPROVED_BY_SSN></ESSRN_APPROVED_BY_SSN>
      <ESSRN_APPROVED_DATE></ESSRN_APPROVED_DATE>
      <ESSRN_ISSUED_BY_SSN></ESSRN_ISSUED_BY_SSN>
      <ESSRN_ISSUED_DATE></ESSRN_ISSUED_DATE>
      <ESSRN_ISSUED_APPROVED_BY_SSN></ESSRN_ISSUED_APPROVED_BY_SSN>
      <ESSRN_ISSUED_APPROVED_DATE></ESSRN_ISSUED_APPROVED_DATE>
    </approveEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": "",
      "ESSRN_ISSUED_NUMBER": "",
      "ESSRN_APPROVED_BY_SSN": "",
      "ESSRN_APPROVED_DATE":"",
      "ESSRN_ISSUED_BY_SSN": "",
      "ESSRN_ISSUED_DATE": "",
      "ESSRN_ISSUED_APPROVED_BY_SSN": "",
      "ESSRN_ISSUED_APPROVED_DATE": ""
    }

Activate Employer

HTTP Method PUT
URI http://**********/****/***/**/EmployerService/activateEmployer/800005

 

XML Web Service Request Body: –

 

    <activateEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <ACTIVATION_EFFECTIVE_DATE></ACTIVATION_EFFECTIVE_DATE>
      <ACTIVATION_REQUEST_REASON></ACTIVATION_REQUEST_REASON>
      <ACTIVATION_REQUESTED_DATE></ACTIVATION_REQUESTED_DATE>
      <ACTIVATION_REQUESTED_BY_SSN></ACTIVATION_REQUESTED_BY_SSN>
      <ACTIVATION_APPROVED_BY_SSN></ACTIVATION_APPROVED_BY_SSN>
      <ACTIVATION_APPROVED_DATE></ACTIVATION_APPROVED_DATE>
    </activateEmployer>

JSON Web Service Request Body: –

    
    {
     "user_id":"",
     "password": "",
     "public_key": "",
     "private_key": "",
     "ACTIVATION_EFFECTIVE_DATE": "",
     "ACTIVATION_REQUEST_REASON": "",
     "ACTIVATION_REQUESTED_DATE": "",
     "ACTIVATION_REQUESTED_BY_SSN": "",
     "ACTIVATION_APPROVED_BY_SSN": "",
     "ACTIVATION_APPROVED_DATE": ""
    }

Inactivate Employer

HTTP Method PUT
URI http://**********/****/***/**/EmployerService/InactivateEmployer/800005

 

XML Web Service Request Body: –

    
    <inactivateEmployer>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <INACTIVATION_EFFECTIVE_DATE></INACTIVATION_EFFECTIVE_DATE>
      <INACTIVATION_REQUEST_REASON></INACTIVATION_REQUEST_REASON>
      <INACTIVATION_REQUESTED_DATE></INACTIVATION_REQUESTED_DATE>
      <INACTIVATION_REQUESTED_BY_SSN></INACTIVATION_REQUESTED_BY_SSN>
      <INACTIVATION_APPROVED_BY_SSN></INACTIVATION_APPROVED_BY_SSN>
      <INACTIVATION_APPROVED_DATE></INACTIVATION_APPROVED_DATE>
    </inactivateEmployer>

JSON Web Service Request Body: –

    
    {
      "user_id":"",
      "password": "",
       "public_key": "",
      "private_key": "",
      "INACTIVATION_EFFECTIVE_DATE": "",
      "INACTIVATION_REQUEST_REASON": "",
      "INACTIVATION_REQUESTED_DATE": "",
      "INACTIVATION_REQUESTED_BY_SSN": "",
      "INACTIVATION_APPROVED_BY_SSN": "",
      "INACTIVATION_APPROVED_DATE": ""
    }

IndividualService

  • Individual List
  • Individuals List by ID
  • Add New Individual

List Individuals

HTTP Method GET
URI https://**********/****/***/**/IndividualService/listEmployees

 

XML Web Service Request Body: –

 

<listEmployees>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <individual_type></individual_type>
      <employee_status></employee_status>
      <page></page>
    </listEmployees>

JSON Web Service Request Body: –

 
    {
     "user_id":"",
     "password": "",
     "public_key": "",
     "private_key": "",
     "individual_type": "",
     "employee_status ": "",
     "page":
    }

Get Individual by ID

HTTP Method GET
URI https://**********/****/***/**/IndividualService/getEmployee/ABCD000000009

 

XML Web Service Request Body: –

 
    <getEmployee>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
    </getEmployee>

 

JSON Web Service Request Body: –

    
   {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": "",
    }

Add New Individual

HTTP Method POST
URI https://**********/****/***/**/IndividualService/addEmployee

 

XML Web Service Request Body: –

 
    <addEmployee>
      <user_id></user_id>
      <password></password>
      <public_key></public_key>
      <private_key></private_key>
      <individual_type></individual_type>
      <employee_ssn></employee_ssn>
      <login_username></login_username>
      <login_password></login_password>
      <first_name></first_name>
      <middle_name></middle_name>
      <last_name></last_name>
      <date_of_birth></date_of_birth>
      <place_of_birth></place_of_birth>
      <nationality></nationality>
      <gender></gender>
      <marital_status></marital_status>
      <residency_phone></residency_phone>
      <residency_email></residency_email>
      <employee_status></employee_status>
    </addEmployee>

JSON Web Service Request Body: -


 
    {
      "user_id":"",
      "password": "",
      "public_key": "",
      "private_key": "",
      "individual_type": "",
      "employee_ssn": "",
      "login_username": "",
      "login_password": "",
      "first_name": "",
      "middle_name": "",
      "last_name": "",
      "date_of_birth": "",
      "nationality": "",
      "gender": "",
      "marital_status": "",
      "residency_phone": "",
      "residency_email": "",
      "employee_status": "",
    }

Login

Lost your password?