This section of the document provides detailed specifications describing all supported message transmissions that the ROC System can process and all responses it can generate. Using this specification, the Resp Orgs can create a new system capable of generating and receiving such messages. Once an incoming message is validated, it will be accepted by the ROC System for processing.
Definition of ROC Web Service
The ROC Web Service is an Extensible Markup Language (XML) based application which transports ROC related data between the Resp Org applications and the ROC System.
A Resp Org program can send ROC related request information, by creating an XML document in the form of a SOAP message, to the Web Service via the internet and receive a response which is also in the form of an XML document. Upon receiving an XML document as a request, the Web Service interface will validate the data against business rules and then will transform it so it can be sent to the ROC System.
Resp Orgs will be able to access the Web Service only after being authorized by Somos®. The Web Service listens to all incoming requests but only responds to requests carrying the authorized credentials originating from registered Internet Protocol (IP) addresses. For more information about getting authorized, refer to Getting Authorized for using ROC Web Services.
If the Source IP address of the request is not registered with the ROC System Web Service, the request will be declined and an appropriate error will be returned. |
Connectivity & Transmission Security
To secure the integrity of the data being transferred between the ROC System and the ROC Notification Subscriber Web Service, the Web Service must be published and configured to use the Secure Socket Layer (SSL) protocol (often referred to as HTTPs) and Transport Layer Security (TLS 1.2 or above). Standard port used by Somos is 443 to encrypt the messages. Please Note: If you request to communicate using a port other than 443, the time it takes to establish the Notification Subscriber for the ROC WSI can take longer. Somos recommends using port 443 for a faster turnaround time.
The following table provides the available environments and URLs for the ROC Web Service:
ROC WSI URLs |
||
Environment |
New URL |
Old URL |
Production |
https://wsi-tfnregistry.somos.com/ROC.svc |
https://rocwsi-portal.somos.com/ROC.svc |
Sandbox (formerly Beta) |
https://sandbox-wsi-tfnregistry.somos.com/ROC.svc |
https://beta-rocwsi-portal.somos.com/ROC.svc |
Simple Object Access Protocol (SOAP) Specifications
The XML syntax for expressing a SOAP message is based on the soap-envelope namespace (http://www.w3.org/TR/2000/NOTE-SOAP-20000508/). This XML namespace identifier points to an XML Schema that defines the structure of what a SOAP message looks like.
Extensible Markup Language (XML) Specifications
The ROC Web Service currently uses Extensible Markup Language (XML) version 1.1 as defined by the W3C (http://www.w3.org/standards/techs/xmlschema#).
Web Service Security Specifications
Each Resp Org user must use valid credentials (Login ID/Password). As of November 6, 2022, the ROC WSI can be accessed via the new URLs listed in the table above. If you have an existing TFNRegistry™ (tfnregistry.somos.com) Login ID and password for either environment, you can use the same credentials that you have today for the ROC WSI. If you only have ROC System permissions in the Somos Portal Website, you can use your existing Login ID; however, you will need to change your password to access the ROC WSI in the TFNRegistry. To complete a password reset, please navigate to the TFNRegistry (tfnregistry.somos.com) and/or the Sandbox TFNRegistry (sandbox-tfnregistry.somos.com) and select the “Forgot Password” link.
Please Note: TFNRegistry passwords will expire after 90 days to align with Somos' password reset policy and the users will be locked due to inactivity after 180 days. Users are not yet required to set up MFA for the ROC WSI in the TFNRegistry; however, this policy is subject to change.
The credentials passed should be valid website credentials and must have the permissions to submit a ROC request. |
Each message sent to the ROC Web Service will be validated by the Web Service security infrastructure and would require that the submitter is properly authorized by Somos.
Getting authorized for using ROC Web Service
The Resp Orgs need to submit the following information for requesting Resp Org Change to use the ROC Web Service:
- IP address where requests will be coming from.
- List of Login ID’s that will be enabled for Web Service access.
After successful registration, the Resp Orgs will be given access to the requested environment.
ROC Web Service Operation Summary
The following table defines the ROC Web Service public methods that Resp Org users can use to interact with the ROC System:
ROC Web Service - Public Methods |
||
S.No. |
Method Name |
Description |
1 |
SubmitRespOrgChange |
Allows a Resp Org to submit a Resp Org Change request to another Resp Org. |
2 |
SearchRespOrgChangeRequests |
Allows both the requesting and controlling Resp Orgs to search Resp Org Change requests. Controlling Resp Orgs will only receive a list of Dial numbers that have been requested of them. |
3 |
GetRespOrgChangeRequest |
Retrieve detail information about a particular Resp Org Change Request. |
4 |
ProcessRespOrgChangeRequest |
Allows the controlling Resp Org to process a Resp Org Change request. |
5 |
GetLOAFile |
Allows a Resp Org to retrieve the Letter of Agency (LOA) file of a particular Resp Org Change as long as they participated in that transaction. |
6 |
GetDocument |
Allows a Resp Org to retrieve a document from a particular Resp Org Change as long as they had participated in that transaction. |
7 |
AddDocument |
Allows a submitting Resp Org to add a document to an existing Resp Org Change request. |
8 |
RemoveDialNumber |
Allows a submitting Resp Org to remove a number (or a set of) from a Resp Org Change Request as long as the numbers are still in a Pending, Overdue or Due Date Approval status. |
9 |
CancelROCRequest |
Allows a submitting Resp Org to cancel a ROC request. |
10 |
GetMissedChangeRequestNotifications |
Allows a subscriber to pull retrieving failed NewIncomingChangeRequest subscriber notifications. |
11 |
GenerateStandardLOA |
Allows a submitting Resp Org to generate a Standard LOA document. Request: Please use the GenerateLOA method. |
12 |
EscalateROCtoHDI |
Allows a submitting Resp Org to submit a ROC request to the Help Desk for processing. Request must have a LOA and only numbers with the status Expired, Declined (Except decline reason 22 - Dial number is already in control by your organization) or Overdue can be included in such request. |
13 |
SubmitHDIRequest |
Allows a submitting Resp Org to submit a Resp Org Change Help Desk Intervention request outside of the ROC System. |
14 |
ReSubmitHDIRequest |
Allows a submitting Resp Org to resubmit a Resp Org Change Help Desk Intervention request to Help Desk. Request must be in Rejected status and only Dial numbers can only be removed from request (i.e. the addition of a new Dial number(s) is not allowed). |
15 |
SearchHDIRequests |
Allows a submitting Resp Org to search Resp Org Change Help Desk Intervention requests. |
16 |
GetHDIRequest |
Allows a submitting Resp Org to retrieve detailed information about a particular Resp Org Change Help Desk Intervention request. |
17 |
GetHDILOAFile |
Allows a submitting Resp Org to retrieve the LOA file of a particular Resp Org Change Help Desk Intervention request. |
18 |
GetHDIDocument |
Allows a submitting Resp Org to retrieve the document of a particular Resp Org Change Help Desk Intervention request as long as they submitted that transaction. |
19 |
AddHDIDocument |
Allows a submitting Resp Org to add a document to an existing Resp Org Change Help Desk Intervention request. |
20 |
CancelHDIRequest |
Allows a submitting Resp Org to cancel a Resp Org Change Help Desk Intervention request. The user of the submitting Resp Org can only cancel a request when the request has not been processed by the Help Desk (i.e. in an Unprocessed status). |
21 |
SearchRespOrgChangeRequestsByTxnID |
Allows both the requesting and controlling Resp Orgs to search Resp Org Change requests and results are sorted as per the TxnIDs. Controlling Resp Orgs will only receive a list of Dial numbers that have been requested of them. |
22 |
CheckOutROCRequest |
Allows a controlling Resp Org to check out a Resp Org Change Request for processing. |
23 |
CheckInROCRequest |
Allows a controlling Resp Org to check in a Resp Org Change Request after processing. |
24 |
GenerateLOA |
Allows a submitting Resp Org to generate a LOA document. This is a new method for the GenerateStandardLOA method as it has new and updated fields available to ensure your Resp Org is using the standardized LOA. |
25 |
SubmitRespOrgChangeWithDocs |
The new SubmitRespOrgChangeWithDocs method allows a Resp Org to submit a Resp Org Change request along with an LOA and additional documents to another Resp Org. Maximum of 4 additional documents can be uploaded while submitting a new request.
DISCLAIMER: If the allowed size limit is reached, the document(s) will be compressed. |
26 |
GetRequestContactInformation |
The new GetRequestContactInformation method allows to download a Comma Separated Values (CSV) file with the controlling Resp Org's contact information. This information comes from the “Find Resp Org Contacts” portion of the “Resp Org Tools” section on the Somos Portal Website. This information is maintained by the Primary Contact and/or Company Administrators of the controlling Resp Org. |