Query TFN
The following is an example REST/JSON query request from the user:
POST /api/v2/tss-text-query-tfn HTTP/1.0
Content-Type: application/json
Content-Length: <num>
{
"id":"user",
"pwd":"password",
"tfn":"8005551212"
}
]A response similar to the following is issued by TSS to the user on success:
// The HTTP header is omitted for brevity. The JSON portion follows:
{
"url":"/api/v2/tss-text-query-tfn", // positive confirmation
"tfn":"8005551212", // positive confirmation
"status":"<seeTableBelow>", // see table below
"routingTspid":"12345", // OPTIONAL, see below
"ownerTspid":"12345", // OPTIONAL, see below
"businessName":"Subscriber Business Name", // OPTIONAL, see below
"contactName":"Subscriber Contact Name", // OPTIONAL, see below
"contactPhone":"Subscriber Contact Phone", // OPTIONAL, see below
"contactEmail":"Subscriber Contact Email", // OPTIONAL, see below
"ownerSrName":"Owner SR Name", // OPTIONAL, see below
"routingSrName":"Routing SR Name" // OPTIONAL, see below
}
It is acceptable to query TFNs that are owned by other SRs. All of the above information is returned
in this case, with the exception that the routing Tspid can have a value of null to protect the private
data of the owner of the TFN. The other fields are not considered to be private.
Failure responses are discussed in the Error section.
The following table enumerates the possible values for the status field on a successful request.
Status Field Values | |
| Status | Comments |
| “Enabled” | The TFN is enabled for text. |
| “Pending” | The TFN has been enabled by a Service Registrar and is pending validation by the Resp Org. |
| “Port_Pending” | The TFN is already enabled by a different Service Registrar and another Service Registrar enables it and is pending validation by the Resp Org. |
| “Unavailable” | The TFN is not in the TSSRegistry DB, nor is it found in the SCP database. The TFN is not in a state to be text enabled |
| “Available” | The TFN is not in the TSSRegistry DB, however it is found as a Working TFN in the SCP database. This TFN can be text enabled. |
Query TFN Response Fields | |
| Field | Comments |
| url | Repeated in the response to make debugging easier. |
| tfn | The TFN associated with this pending entry. |
| status | See the Status table above. |
routingTspid | The TSPID used for text routing. It identifies a Service Registrar. TSS assigns a unique TSPID to each Service Registrar. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null "routingTspid":null Also, when the user does not have permissions to view the routing tspid for the TFN, the field is returned as null. |
ownerTspid | Typically the same as the routingTspid field, but it can be populated with a different TSPID to identify a Service Registrar that is responsible for the TFN; for example, billing responsibilities. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null |
businessName | The toll-free subscriber’s business name using the TFN. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null |
contactName | The name of the toll-free subscriber responsible for enabling the TFN. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null |
contactPhone | The phone of the toll-free subscriber responsible for enabling the TFN. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null |
contactEmail | The email of the toll-free subscriber responsible for enabling the TFN. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null |
| ownerSrName | The name of the Owner Service Registrar who is responsible for the text-enabled TFN; for example, billing responsibilities. All users have permissions to see this field. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null " ownerSrName ":null |
| routingSrName | The name of the Routing Service Registrar used for text routing. This field is only valid for the Enabled and Pending status. Otherwise it is set to: null " routingSrName ":null Also, when the user does not have permissions to view the routing service registrar for the TFN, the field is returned as null. |
Response HTTP Status Codes | |
| HTTP Status Codes | Reason |
| 200 | The request has succeeded. |
| 400 | Bad request (invalid JSON format, failed validation). |
| 401 | Authentication failed. |
| 403 | The user does not have permission to query for <TFN>. |
| 500 | An error occurred within the TSSRegistry. |