ROCRetrieveRequests

Description

ROCRetrieveRequests allows the controlling and requesting Resp Orgs to search all requests for requests matching a set of search criteria. Controlling Resp Orgs may only receive a list of numbers that have been requested of them; numbers not belonging to them may not be queried. The following are the allowed fields in reqparams:

	rocusername	The username registered at SMS/800 for ROC requests.
	rocpasswd	The password associated with the username registered at SMS/800 for ROC requests.
	entity	The SMS/800 entity for ROC requests.
	resporg	To limit the returned results to requests involving this Resp Org.
	dn	To limit the returned results to requests involving this single number.
*	type	To limit the returned results to requests with the specified request type. Valid values are: incoming outgoing
	status	To limit the returned results to requests with the specified request status. Valid values are: all pending processing ported declined expired escalated invalid failed overdue duedateapproval status defaults to all if no value is provided.
	progress	To limit the returned results to open or closed requests. Valid values are: all open closed progress defaults to all if no value is provided.
	rejectcode	A single code as defined in ROCManageRequest.
	startdatetime	To limit the returned results to requests with the submitted after and including this date/time. The format of this value is: mm/dd/yy hh:mmX/Y where X is the meridiem (A or P), and Y is the SMS/800 timezone indicator. An example of a valid date/time would be: 07/01/16 10:15A/C.
	enddatetime	To limit the returned results to requests with the submitted up to and including this date/time. The format of this value is: mm/dd/yy hh:mmX/Y where X is the meridiem (A or P), and Y is the SMS/800 timezone indicator. An example of a valid date/time would be: 07/01/16 10:15A/C.
	bytxnid	To eliminate all toll-free number detail, resulting in a much smaller XML, returned faster, and faster to process, set this to the value 1. To get the number detail, either set this to the value 0 or don't specify this parameter.

Either the single parameter entity or the pair of parameters rocusername and rocpasswd must be specified.

Results

A RocRetrieveRequests response is an XML document embedded within the normal API response.

The ErrorList section will only be included if an error has occurred.

A typical XML response, when bytxnid is either not specified or set to 0, will have the following fields.

<SearchRespOrgChangeRequestsResponse>
<StatusCode>1</StatusCode>
<DialNumberResultList>
<DialNumber>
<Dial>8443202161</Dial>
<TxnID>7671548c-9a43-4fb6-8b82-2cd35fed8f41</TxnID>
<SubmittedDateTime>2016-05-04T12:21:28</SubmittedDateTime>
<ProcessedDateTime>2016-05-05T06:14:09.253</ProcessedDateTime>
<DueDateTime>2016-05-06T12:21:00</DueDateTime>
<SubmittingRespOrg>art01</SubmittingRespOrg>
<ControllingRespOrg>ART04</ControllingRespOrg>
<Status>3</Status>
<LOAID>143</LOAID>
<LOAFileName>Test 143.pdf</LOAFileName>
<DocumentList>
<Document>
<DocumentID>144</DocumentID>
<FileTitle>Test 144.pdf</FileTitle>
<FileNotes>Test Comments</FileNotes>
</Document>
</DocumentList>
<RejectReasonList>
<RejectReason>
<ReasonCode>01</ReasonCode>
<ReasonDescription>Customer name mismatch/missing</ReasonDescription>
</RejectReason>
<RejectReason>
<ReasonCode>02</ReasonCode>
<ReasonDescription>Address mismatch/missing (verification done if address is different but all other information is the same)</ReasonDescription>
</RejectReason>
</RejectReasonList>
<RejectNote>Test Reject Note</RejectNote>
</DialNumber>
<DialNumber>
<Dial>8443202162</Dial>
<TxnID>16ac084c-be8e-4b6f-b9d5-8ca62b70ab74</TxnID>
<SubmittedDateTime>2016-05-04T12:24:10</SubmittedDateTime>
<ProcessedDateTime>2016-05-05T06:14:09.257</ProcessedDateTime>
<DueDateTime>2016-05-06T12:24:00</DueDateTime>
<SubmittingRespOrg>art01</SubmittingRespOrg>
<ControllingRespOrg>ART04</ControllingRespOrg>
<Status>3</Status>
<LOAID>143</LOAID>
<LOAFileName>Test 143.pdf</LOAFileName>
<DocumentList>
<Document>
<DocumentID>144 <FileTitle>Test 144.pdf</FileTitle>
<FileNotes>Test Comments</FileNotes>
</Document>
</DialNumber>
</DialNumberResultList>
<ErrorList>
<Error>
<Code>ErrorCode1>/Code>
<Description>ErrorDescription1</Description>
<AdditionalInfo>AdditionalInfo1</AdditionalInfo>
<Error>
<ErrorList>
</SearchRespOrgChangeRequestsResponse>

A typical XML response, when bytxnid is set to 1, will have the following fields.

<SearchRespOrgChangeRequestsByTxnIDResponse>
<StatusCode>1</StatusCode>
<TransactionResultList>
<Transaction>
<TxnID>8C1D4C99-8D45-49C2-899E-32B3BA3212B0</TxnID>
<TFNCount>25</TFNCount>
<ExpediteROC>Yes</ExpediteROC>
<SubmittedDateTime>2018-07-01T00:00:00</SubmittedDateTime>
<DueDateTime>2018-07-03T00:00:00</DueDateTime>
<IsRequestCheckedOut>Yes</IsRequestCheckedOut>
<RequestCheckedOutBy>xxxxxxx</RequestCheckedOutBy>
<SubmittingRespOrg>ZATXT</SubmittingRespOrg>
<LOAID>43</LOAID>
<LOAFileName>Test 43.pdf</LOAFileName>
<DocumentList>
<Document>
<DocumentID>1122</DocumentID>
<FileTitle>TEST 1122.PDF</FileTitle>
<FileNotes />
</Document>
<Document>
<DocumentID>3344</DocumentID>
<FileTitle>TEST 3344.PDF</FileTitle>
<FileNotes />
</Document>
</DocumentList>
<ControllingRespOrgList>
<ControllingRespOrg>
<RespOrg>ABC01</RespOrg>
<Count>7</Count>
</ControllingRespOrg>
<ControllingRespOrg>
<RespOrg>TST99</RespOrg>
<Count>15</Count>
</ControllingRespOrg>
</ControllingRespOrgList>
<UnavailRespOrgTFNCount>3</UnavailRespOrgTFNCount>
</Transaction>
</TransactionResultList>
<ErrorList>ErrorList>
</SearchRespOrgChangeRequestsByTxnIDResponse>

Most data validation is left to Somos to perform. In some cases, 8MS may provide some up-front validation. In that event, the following XML will be returned.

<err>
<code>E0000000</code>
<context>param-in-error</context>
<description>text describing error.</description>
<err>

Possible errors returned for this API call include

Code	Context	Description
E0000093	entity/rocusername	A valid 'entity' or 'rocusername' must be specified.
E0000094	type	Parameter 'type' was not specified.