Hosted Numbers
 
1-800-300-9525
 
  1. Introduction
  2. REST API
  3. Authentication
  4. Rate Limiting
  5. Responses and Errors
  6. Pagination
  7. API Actions

Introduction

The PATLive API is another way to access your PATLive information — one that makes it easy for third-party tools to interact with the service. Our API makes it easy to access your information from the desktop, mobile devices, and web applications.

REST API

Our API follows the REST conventions. The guide below should provide everything you need to implement software that works with PATLive.

Authentication

All authentication is handled with HTTP Digest Authentication. Use the same username/password you would use to log into our website.

Rate Limiting

Rating limiting is currently enabled and is counted against all calls for the logged in user. Limits are set to a max of 100 calls per minute and 2000 calls per hour.

Responses and Errors

By default all responses are returned in XML format. You may also request JSON format by using a query string parameter, ?format=json. Some methods also provide responses in RSS format, ?format=rss. All responses are encoded as UTF-8.

Return Structure:
All responses will return an object containing 3 items: ErrorCode, ErrorMessage, and Data. Successful responses will return an ErrorCode value of 0.

Data will contain a list of objects specific to the requested call. More details about the structure of the data is listed below with the description of each available call type.

Error Codes:

  • 0: No Error
  • 1001: Invalid User
  • 2001: Invalid Parameter List
  • 2002: Invalid Parameter Value
  • 3001: Unable To Connect To Server
  • 4001: API Limit Threshold Reached

Pagination

Most API actions that return data will abide by a standard set of pagination conventions. The response will contain metadata about the paged resultset. For example, requesting a list of messages will return:


    32 
    4 
    1 
    10

The following URL parameters can be used to obtain specific paged data:

  • Page - The number of the page to return.
  • PageSize - The number of results to return.

Note: the maximum PageSize is 100 ( PageSize=100 )

API Actions

List Services

Get /api/v1.0/Mailbox/

Provides a list of services for the authenticated user.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/

 

Response:

<DataInfo>
	<TotalResults>15</TotalResults>
	<TotalPages>2</TotalPages>
	<CurrentPage>1</CurrentPage>
	<ResultsPerPage>10</ResultsPerPage>
</DataInfo>

<Data>
	<Service>
		<MailboxId>OQGMEwyJAPZncIt4u1xwQw2</MailboxId>
		<PhoneNumberList>
			<PhoneNumberObj>
				<PhoneNumber>1-866-815-0130</PhoneNumber>
				<Description>(866) 815-0130</Description>
				<PhoneNumberId>yP7jum3y5QAETlGdsZIgLw2</PhoneNumberId>
			</PhoneNumberObj>
		</PhoneNumberList>
		<Prefix>300</Prefix>
		<Extension>3298</Extension>
		<ProductCode>SAR</ProductCode>
		<ProductDescription>PATLive Messaging Executive</ProductDescription>
		<Name>George Smith</Name>
		<FirstName>George</FirstName>
		<LastName>Smith</LastName>
		<NamePrefix />
		<NameSuffix />
		<MailboxStatus>0</MailboxStatus>
		<MainMailbox>false</MainMailbox>
		<Private>false</Private>
		<DateOn>2010-12-02T09:25:02.903</DateOn>
		<DateOff />
		<ExpirationDate />
		<InfoCode>0</InfoCode>
		<LastOnHold />
		<LastVacation />
		<AliasId>UhjBkuqqCkfBN6sahO2Low2</AliasId>
		<SpecialServicesRoutingQueue>99</SpecialServicesRoutingQueue>
		<LanguageId>ah7_rQfTLOMpMvGyAToFfA2</LanguageId>
		<FeatureGroupId>QfjkLKruC9cE7CFrCYnRxg2</FeatureGroupId>
		<FeatureGroupDescription>PATLive Messaging Executive</FeatureGroupDescription>
		<ServiceName>PATLive Messaging Executive</ServiceName>
		<OrgGroupId>UhjBkuqqCkfBN6sahO2Low2</OrgGroupId>
		<NumberOfLogins />
	</Service>
	[...]
</Data>

Optional Parameters:

  • Page - The number of the page to return. Default = 1
  • PageSize - The number of results to return. Default = 20
  • SearchString - Search mailboxes by MailboxName, PhoneNumber, or PhoneNumberDescription.

Return Formats:

  • XML - Default
  • JSon

 

 

List Messages(Call Recordings)

Get /api/v1.0/Mailbox/[MailboxId]/Messages/

Provides a list of messages for a given mailbox. These messages are call recordings/voicemails and even faxes. You can pass a parameter that is listed below to select if you only want voice or faxes to be returned.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/Messages/

 

Response:

<DataInfo>
	<TotalResults>5<TotalResults>
	<TotalPages>1</TotalPages>
	<CurrentPage>1</CurrentPage>
	<ResultsPerPage>20</ResultsPerPage>
</DataInfo>

<Data>
	<Message>
		<MessageId>53S1b6rfHfqjlCS3RVT7cA2</MessageId>
		<MessageType>Voice</MessageType>
		<DateCreated>2011-03-30T14:18:00</DateCreated>
		<From>(850) 555-5224</From>
		<Size>0:06</Size>
		<Status>New</Status>
		<MessageURL>https://my.hostednumbers.com/mailbox/messages/get.aspx?MsgID=53S1b6rfHfqjlCS3RVT7cA2&format=mp3</MessageURL>
	</Message>
	[...]
</Data>

Optional Parameters:

  • Page - The number of the page to return. Default = 1
  • PageSize - The number of results to return. Default = 20
  • SortDir - Specifiy the direction the results are sorted.
    • asc - Sort results ascending.
    • desc - Sort results descending. Default
  • SortBy - The field by which to sort the results.
    • To - Sort by the 'To' field.
    • From - Sort by the 'From' field.
    • Size - Sort by the 'Size' field.
    • Status - Sort by the 'Status' field.
    • Comment - Sort by the 'Comments' field.
    • Date - Sort by the 'Date' field. Default
  • MessageType - Request messages of a specific type.
    • Fax - Fax messages.
    • Voice - Voicemail messages.
    • All - All messages. Default
  • MessageStatus - Request messages of a specific status.
    • New - New messages.
    • Saved - Saved messages.
    • Sent - Sent messages.
    • NotDeleted - Not Deleted messages.
    • Deleted - Deleted messages.
    • Uploaded - Uploaded messages.
    • All - All messages.
    • Inbox - Messages in your 'Inbox'. Default

Return Formats:

  • XML - Default
  • JSon
  • RSS

 

 

Search Messages

Get /api/v1.0/Mailbox/[MailboxId]/SearchMessages/

Provides a list of messages based on given search parameters.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/SearchMessages/?MessageTo=1-800-775-7790

 

Response:

<DataInfo>
	<TotalResults>5<TotalResults>
	<TotalPages>1</TotalPages>
	<CurrentPage>1</CurrentPage>
	<ResultsPerPage>20</ResultsPerPage>
</DataInfo>

<Data>
	<Message>
		<MessageId>53S1b6rfHfqjlCS3RVT7cA2</MessageId>
		<MessageType>Voice</MessageType>
		<DateCreated>2011-03-30T14:18:00</DateCreated>
		<From>(850) 555-5224</From>
		<Size>0:06</Size>
		<Status>New</Status>
		<MessageURL>https://my.hostednumbers.com/mailbox/messages/get.aspx?MsgID=53S1b6rfHfqjlCS3RVT7cA2&format=mp3</MessageURL>
	</Message>
	[...]
</Data>

Search Parameters:

  • MessageTo - Search the 'To' field
  • MessageFrom - Search the 'From' field
  • MessageStartDate - The start of a date range. YYYY-MM-DD.
  • MessageEndDate - The end of a date range. YYYY-MM-DD.
Note: At least one search parameter is required

Return Formats:

  • XML - Default
  • JSon
  • RSS

 

 

Update Message Status

Post /api/v1.0/Mailbox/[MailboxId]/Messages/[MessageId]/

Update the status of a message.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/Messages/53S1b6rfHfqjlCS3RVT7cA2/

 

Response:

<StatusMessage>
    Status updated successfully.
</StatusMessage>

Parameters:

  • Status - The status to set the message to. Needs to be one of the following:
    • New
    • Saved
    • Deleted

Return Formats:

  • XML - Default
  • JSon

 

 

List Phone Numbers On Mailbox

Get /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/

Provides a list of phone numbers for a given mailbox.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/PhoneNumbers/

 

Response:

<ResultSet>
	<TotalResults>3</TotalResults>
</ResultSet>

<Data>
    <PhoneNumber>
      <PhoneNumber>1-866-555-9544</PhoneNumber>
      <Description>Billboard Ad</Description>
	  <PhoneNumberId>yP7jum3y5QAETlGdsZIgLw2</PhoneNumberId>
    </PhoneNumber>
     [...]
</Data>

 

If the mailbox is a Call Tracker, then the transfer number will also be returned:

Response:

<ResultSet>
	<TotalResults>3</TotalResults>
</ResultSet>

<Data>
    <PhoneNumber>
      <PhoneNumber>1-866-555-9544</PhoneNumber>
      <Description>Billboard Ad</Description>
	  <TransferNumber>8505551234</TransferNumber>
	  <PhoneNumberId>yP7jum3y5QAETlGdsZIgLw2</PhoneNumberId>
    </PhoneNumber>
     [...]
</Data>

Return Formats:

  • XML - Default
  • JSon

 

 

Update Phone Number on Mailbox

Post /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/[PhoneNumberId]/?Method=UpdatePhoneNumber

Updates a Phone Number's information, currently only supports updates on Call Trackers to the Transfer Number

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/PhoneNumbers/yP7jum3y5QAETlGdsZIgLw2/

 

Response:

<StatusMessage>
    The calltracker has been updated successfully.
</StatusMessage>

Parameters:

  • transferNumber - The new number for the Call Tracker to forward to.

Return Formats:

  • XML - Default
  • JSon

 

 

Add Phone Number To Mailbox

Put /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/[PhoneNumberId]/

Post /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/[PhoneNumberId]/?Method=AddPhoneNumber

Add a phone number to a mailbox.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/PhoneNumbers/ABT3PingbSzdYsRflv3HVylRx0If4GVvSfZq_MixZ1tJqWZzhayFrIKTD3FIuxIn1-wOmvZ3rswbEMjgs7PsnBr1K0TjT3RyQ19-R0snZ2Q1/

 

Response:


    Phone number added to mailbox successfully.

Return Formats:

  • XML - Default
  • JSon

 

 

Delete Phone Number From Mailbox

Delete /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/[PhoneNumberId]/

Post /api/v1.0/Mailbox/[MailboxId]/PhoneNumbers/[PhoneNumberId]/?Method=DeletePhoneNumber

Delete a phone number from a mailbox.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/PhoneNumbers/yP7jum3y5QAETlGdsZIgLw2/

 

Response:

<StatusMessage>
    Phone number delete from mailbox successfully.
</StatusMessage>

Return Formats:

  • XML - Default
  • JSon

 

 

List Call Details

Get /api/v1.0/Mailbox/[MailboxId]/CallDetails/

Get Call Details for a given mailbox.

 

Example:


https://my.hostednumbers.com/api/v1.0/Mailbox/BO5b5YxwML_p0t7ohahZbA2/CallDetails/

 

Response:

<ResultSet>
	<TotalResults>12</TotalResults>
	<CurrentPage>1</CurrentPage>
	<ResultsPerPage>20</ResultsPerPage>
</ResultSet>

<Data>
    <CallDetail>
      <DateTime>2011-04-05T13:10:33.283</DateTime>
      <CallDuration />
      <PhoneNumber>1-866-555-9544</PhoneNumber>
      <PhoneNumberName>Billboard Ad</PhoneNumberName>
      <CallResolution>Processing</CallResolution>
      <MSG />
      <CallerId>(850) 544-5544</CallerId>
      <FirstName />     <!-- Only populated if Advanced Caller ID is enabled on mailbox -->
      <LastName />      <!-- Only populated if Advanced Caller ID is enabled on mailbox -->
      <Business />      <!-- Only populated if Advanced Caller ID is enabled on mailbox -->
      <Address />       <!-- Only populated if Advanced Caller ID is enabled on mailbox -->
      <City>Tallahassee</City>
      <State>FL</State>
      <ZipCode />
      <PhoneNumberFormatted>(866) 805-9544</PhoneNumberFormatted>
      <PageCount>0</PageCount>
      <Group />
      <User />
      <CallDirection>Inbound</CallDirection>
      <Access />
      <Status />
      <NPA>850</NPA>
      <NXXX>544</NXXX>
      <CallType />
      <CurrentURL />
      <WidgetName />
      <SourceType>0</SourceType>
      <Category />
    </CallDetail>
	[...]
</Data>

Optional Parameters:

  • Page - The number of the page to return. Default = 1
  • PageSize - The number of results to return. Default = 20
  • StartDate - The start of a date range. YYYY-MM-DD
  • EndDate - The end of a date range. YYYY-MM-DD
  • Numbers - A comma delimited list of phone numbers to include call details for. If blank all numbers are mailbox will be included.Ex. 1-888-555-1234,1-888-555-5678 Default = All numbers on mailbox.
  • RequestType - Preset date range options.
    • Today - Return call details for today. Default
    • PreviousDay - Return call details for yesterday.
    • PreviousWeek - Return call details for last week.
    • Previous7Days - Return call details for the previous 7 days.
    • PreviousMonth - Return call details for last month.
    • PreviousQuarter - Return call details for the previous quarter.
    • MonthToDate - Return call details from the beginning of the month through today.
    • YearToDate - Return call details from the beginning of the year through today.
    • Custom - Specify the date range using StartDate and EndDate
  • SortBy - The column to sort the results by.
    • DateTime Default
    • Minutes
    • PhoneNumber
    • Results
    • Message
    • ANI
    • Name
    • City
    • State
    • Zip
    • Pages
    • Direction
    • Access
    • Status
  • SortDir - The direction to sort the results.
    • ASC - Ascending
    • DESC - Descending Default
  • CallType - Limit results based on call type.
    • Voice - Limit to voice calls.
    • Fax - Limit to faxes.
    • - Leave blank to return all call types. Default

Return Formats:

  • XML - Default
  • JSon

 

 

List Phone Numbers

Listing phone numbers is broken into two categories, local and toll-free. For toll-free phone numbers supply the toll-free area code to get a list of phone numbers. For local phone numbers you'll need to supply a state and city/npa combo to receive a list of phone numbers. Our pool of phone numbers is constantly growing. When you request a list of phone numbers we will return, along whith the list, a SearchId and let you know if more phone numbers are available for that search criteria. If there are more phone numbers available simply append the SearchId onto your request and we will send you the next set of phone numbers in our list.

Note: In addition you will need to enable the storage of cookies between requesting a list of phone numbers and requesting subsequent pages of the result set.

Return Formats:

  • XML - Default
  • JSon

 

 

Toll-Free Area Codes

Get /api/v1.0/PhoneNumbers/Toll-Free/

Returns the list of available toll-free area codes.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/Toll-Free/

 

Response:


	4



    
      800
      true
    
	[...]

Return Formats:

  • XML - Default
  • JSon

 

 

Toll-Free Phone Numbers

Get /api/v1.0/PhoneNumbers/Toll-Free/[toll-free area code]/

Returns a list of phone numbers for a given area code.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/Toll-Free/800/

 

Response:

<PhoneNumberDataInfo>
    <MoreResults>true</MoreResults>
    <SearchId>89d549d6-9bef-4ec8-8f21-eeda4873e417</SearchId>
</PhoneNumberDataInfo>

<Data>
    <TollFreePhoneNumber>
      <PhoneNumber>8008270677</PhoneNumber>
      <PhoneNumberFormatted>(800) 827-0677</PhoneNumberFormatted>
      <PhoneNumberId>TzIcEiEq860VjaXngsDjTCBO4BL3uSUkehkQ0c9Nruw1</PhoneNumberId>
      <PhoneNumberPrice>10</PhoneNumberPrice>
      <IsPremium>false</IsPremium>
      <IsVanity>false</IsVanity>
	</TollFreePhoneNumber>
	[...]
</Data>

Return Formats:

  • XML - Default
  • JSon

 

 

Local State List

Get /api/v1.0/PhoneNumbers/Local/

Returns a list of states you can list local phone numbers for.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/Local/

 

Response:

<ResultSet>
	<TotalResults>54</TotalResults>
</ResultSet>

<Data>
	<State>
		<StateName>Alabama</StateName>
		<StateAbbreviation>AL</StateAbbreviation>
	</State>
	[...]
</Data>

Return Formats:

  • XML - Default
  • JSon

 

 

Local City/NPA List

Get /api/v1.0/PhoneNumbers/Local/[StateAbbreviation]

Returns a list of city/npa combinations you can list local phone numbers for.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/Local/FL/

 

Response:

<ResultSet>
	<TotalResults>68</TotalResults>
</ResultSet>

<Data>
	<CityNPACombo>
		<City>Alford</City>
		<NPA>850</NPA>
		<Lata>45012</Lata>
		<CityNPAId>fwSXYz_To7taoVs0bLGZioN9LnHvVJ4_Azf7iJiIoOI1</CityNPAId>
		<TotalAvailableNumbers>1</TotalAvailableNumbers>
	</CityNPACombo>
	[...]
</Data>

Return Formats:

  • XML - Default
  • JSon

 

 

Local Phone Numbers

Get /api/v1.0/PhoneNumbers/Local/[StateAbbreviation]/[CityNPAId]/

Returns a list of phone numbers for the requested state and city npa.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/Local/FL/Sw71R5ipp4Xi_mm8x_vIdA2/

 

Response:

<PhoneNumberDataInfo>
	<MoreResults>true</MoreResults>								 <!-- Indicates if more results are available -->
	<SearchId>a446efa5-fb8d-4967-b282-d6d6c8c22d66</SearchId>    <!-- Pass SearchId back as a URL parameter to get the next set of phone numbers -->
</PhoneNumberDataInfo>

<Data>
	<LocalPhoneNumber>
		<PhoneNumber>8634407563</PhoneNumber>
		<PhoneNumberFormatted>(863) 440-7563</PhoneNumberFormatted>
		<PhoneNumberId>2hbgFL6ry6t-gype6FTYoxJ8TWwAc2iKqQRErsjksopL1NPks2XHcH7NPqdT1v3fA9mZMn47mrUq2U7sUECAkNs5Bge0aZk3fnTYeZ9NdEk1</PhoneNumberId>
		<PhoneNumberPrice>5</PhoneNumberPrice>
		<Npa>863</Npa>
		<City>Bartow</City>
		<State>FL</State>
		<Lata>952</Lata>
		<IsVanity>false</IsVanity>
		<VanitySearchString />
	</LocalPhoneNumber>
	[...]
</Data>

Return Formats:

  • XML - Default
  • JSon

 

 

Local Phone Numbers By NPA/NXX

Get /api/v1.0/PhoneNumbers/NpaNxx/

Returns a list of phone numbers for the requested NPA and NXX.

 

Example:


https://my.hostednumbers.com/api/v1.0/PhoneNumbers/[NPA]/[NXX]

 

Response:


	true								 
	a446efa5-fb8d-4967-b282-d6d6c8c22d66    



	
		8634407563
		(863) 440-7563
		2hbgFL6ry6t-gype6FTYoxJ8TWwAc2iKqQRErsjksopL1NPks2XHcH7NPqdT1v3fA9mZMn47mrUq2U7sUECAkNs5Bge0aZk3fnTYeZ9NdEk1
		5
		863
		Bartow
		FL
		952
		false
		
	
	[...]

Return Formats:

  • XML - Default
  • JSon

 

 

Call Count

Get api/v1.0/Mailbox/[mailboxId]/callcount/startDate/endDate

Dates should be in the form of mm-dd-yyyy

Errors will be reported if the end date is before the start date or if the dates are more than a 12 month difference.

If no end date is supplied it will default to today's date.

The API call will return an xml response that will be similar to this

Response:


<ReturnDataCallCount>
    <ErrorCode>0</ErrorCode>
    <ErrorMessage />
    <count>6</count>
</ReturnDataCallCount>

Return Formats:

  • XML - Default
  • JSon