Update TFNs
The Update API processes a set of commands for enabling and disabling Toll-Free Numbers (TFNs). This is a bulk API. Currently up to 1,000 commands in an array are allowed.
The following is an example REST/JSON update request from the user:
POST /api/v2/tss-text-update-tfn HTTP/1.0
Content-Type: application/json
Content-Length: <num>
{
"id":"user",
"pwd":"password",
"requests":[ // an array of requests to process
{ // the start of the first request
"command":"enable",
"tfn":"8005001212",
"routingTspid":"12345",
"ownerTspid":"12345",
"businessName":"Subscriber Business Name",
"contactName":"Subscriber Name",
"contactJobTitle":"Subscriber Job Title",
"contactPhone":"Subscriber Phone",
"contactEmail":"Subscriber Email"
}, // the end of the first request
{ // the start of the second request
"command":"disable",
"tfn":"8005001213"
}, // the end of the second request
{ // the start of the third request
"command":"enable",
"tfn":"8005001214",
"routingTspid":"01234",
"ownerTspid":"12345",
"businessName":"Subscriber Business Name",
"contactName":"Subscriber Name",
"contactJobTitle":"Subscriber Job Title",
"contactPhone":"Subscriber Phone",
"contactEmail":"Subscriber Email"
} // the end of the third request
] // the end of the request array
}
The TFNs in the request array are processed independent of each other; the Texting and Smart Services (TSS) Registry version 2.0 API supports partial success of the requests array.
A response similar to the following is issued by the TSS to the user if it was a valid request. Since it’s a
bulk API, the response includes a count of the TFNs in the request array, a success response, and a failure
response containing the error messages. The response array may not have the status in the same order as
the original request array. The failed TFNs can be resubmitted later.
The success response includes a count of the successful TFN updates and status(es) of the TFNs. The
failure response includes a count of the failed TFN updates and error message(s). Enable requests have
the following fields in the response: tfn and status. Disable requests have the following fields in the
response: tfn and errorMessage.
// The HTTP header is omitted for brevity. The JSON portion follows:
{
"url":"/api/v2/tss-text-update-tfn", // positive confirmation for
//debugging
"totalTfnCountInRequest":3, // total number of tfns in the request
"successResponse":{ // success response
"successCount":2, // total number of successful tfn updates
"responses":[ // an array of success responses to the requests
{"tfn":"8005551212","status":"<SeeStatusTableBelow>"},
// first success response
{"tfn":"8005551213","status":"<SeeStatusTableBelow>"}
// second success response
] // the end of the success responses array
} // the end of success response
"failureResponse":{ // failed response
"failureCount":1, // total number of failed tfn updates
"responses":[ // an array of failed responses to the requests
{"tfn":"8005551214","errorMessage":"<SeeErrorMessageTableBelow>"}
// first error response
] // the end of the failed responses array
} // the end of failure response
}
The following table describes the possible values for the status field.
A redundant enable request (for a TFN already enabled by the requesting SR) is allowed and results in
replacing the enable parameters for the TFN with a returned response of “Enabled”. Similarly, a
redundant disable request is allowed (for a TFN already disabled) -- the redundant disable request
appears to the TSS to be an attempt to disable a number that is not currently enabled -- in the initial
disabled event and any subsequent redundant disabled events, the response is “Disabled”.
The tables above enumerate the possible results of enabled and disabled requests as well as the error
messages as a result of failed TFN enable/disable requests. If an error occurs that prevents the TSS from
completing the request (such as authentication failure or bad request), then the above response is not
returned and instead a failure response, as discussed in the Error section, is returned.