Get Plan Service

This XML API returns the list of the available plans for the enrollment on the basis of the Zip Code, State and Tribal status of the Zip Code. This api can also be used to check whether service is available for a specific Zip Code. Plans will be displayed on the basis of the Source selected in "Plan Permission" while creating it, and if no plan exists for a source then it will display all active plans for all the sources by default.

End Point https://www.vcareapi.com/vcareOssApi/GetPlanService/
Field (Short Description) Value/Tag Name Format Field Example Type Notes Validation rules
VENDOR ID string Vcarecorporation Required A unique Vendor ID is associated with the MVNO/OSS partner. This is used for authorization purpose and can be obtained by contacting your account manager.
USER NAME string Vcarecorporation Required A unique User name is associated with the MVNO/OSS partner. This is used for authorization purpose and can be obtained by contacting your account manager.
PASSWORD string Vcarecorporation Required This is a random string which is generated by Vcare and is tied to the MVNO/OSS user name. This is specifically used for authentication purpose and can be obtained by contacting your account manager.
PIN string 123456789 Required This is generated by Vcare to provide an additional layer of security in the Interim API. This is used for authentication purpose and can be obtained by contacting your account manager.
REFERENCENUMBER string 123456789 Required Auto generated unique reference number is required to be passed with each transaction.
STATE string MD Required Service address state of the subscriber. API will return all the Active plans in Telgoo5 in the State being passed in the API request. State should be standard abbreviated form which is two characters.
TYPE string LIFELINE Required Type determines the type of plan to be returned. If type is 'LIFELINE' then it will return the lifeline plans available on the supplied state and zip code. If type is 'NONLIFELINE' then it will return the list of all the prepaid plans available on the zip code. and if type is 'TRADITIONAL' then it will return the list of all the traditional plans available on the zip code. Traditional Plans are the plans which are similar to the NONLIFELINE/PREPAID plans these plans are used to switch the lifeline customer to nonlifeline status in case they no longer qualify for the lifeline services. This can be either of the following:
  • LIFELINE
  • NONLIFELINE
  • TRADITIONAL
TRANSACTIONTYPE string ENROLLMENT Optional Only those plans will be displayed for which agents have permission. Expected Value:ENROLLMENT
SERVICE TYPE string LIFELINE, ACP and COMBO Required This determines the type of service type. Service type should be LIFELINE,ACP and COMBO. Default value LIFELINE
AGENT ID string John Doe Required This is the Telgoo5 user id.For the Agent/Employee who is sending the API request.
AGENT PASSWORD string JohnDoe Conditional This is the password for the Agent Id mentioned above. This is configuration level field. If you have set the permissions for the Agent Id for the requirement of the password in API transactions then you will need to pass the Agent Password in all the XML API transaction, else if you have set the permissions to password not required then you don’t need to pass the Agent Password in the XML API.
SOURCE string API Optional Source of the order/application Expected Value:API, TABLET, IVR, WEBSITE
TRIBAL string Y Optional If this is passed as Y system will return all the tribal plans in the given state. If this is passed as N system will pass all the regular plans in the state. If type is NONLIFELINE or TRADITIONAL this will always be passed as N. Expected value Y or N.
ZIPCODE Numeric 21215 Required This is the zip code for the service address of the customer. Should not allow letters and special characters, only numbers. Should be exactly 5 digits.
Sample Request XML
<?xml version="1.0" encoding="utf-8"?>
<VCAREOSSAPI xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CREDENTIALS>
	<VENDORID></VENDORID>
	<USERNAME></USERNAME>
	<PASSWORD></PASSWORD>
	<PIN></PIN>
	<REFERENCENUMBER></REFERENCENUMBER>
</CREDENTIALS>
<VCAREOSS>
  <GETPLANSERVICE>
	<STATE></STATE>
	<TYPE></TYPE>
	<TRANSACTIONTYPE></TRANSACTIONTYPE>
	<SERVICETYPE></SERVICETYPE>
	<AGENTID></AGENTID>
	<AGENTPASSWORD></AGENTPASSWORD>
	<SOURCE></SOURCE>
  </GETPLANSERVICE>
  <CHECKSERVICEAVAILABILITY>
	<TRIBAL></TRIBAL>
	<ZIPCODE></ZIPCODE>
  </CHECKSERVICEAVAILABILITY>
 
 </VCAREOSS>
</VCAREOSSAPI>
List of status code, description and resolution.
Status Code Description How to Resolve?
00 SUCCESS SUCCESS
13 Password is invalid. Provide a valid Password.
15 Zip code is invalid. Please enter valid zip code.
16 Vendor not found. Wrong credentials. Please enter valid vendor credentials.
19 Service is not available for this Zip Code. No service for the provided Zip Code. Please enter the right Zip code.
22 Plan not found. Provide a valid plan available in system
113 Zip Code is required. Zip code cannot be blank. You should enter a valid Zip code.
356 Agent ID cannot be blank. Please provide Agent ID as it cannot be blank.
457 Invalid Source. Please provide a valid Source. Given value is invalid for Source.
517 State Code is required. Provide correct State Code. A valid State code is required.
731 Type should be lifeline OR nonlifeline OR traditional. Provide a correct Type. Type should be lifeline or nonlifeline or traditional.
751 Custom message. This is dynamic message.
Response XML
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <credentials>
        <vendorId></vendorId>
        <referenceNumber></referenceNumber>
    </credentials>
    <GetPlanService>
        <statusCode>00</statusCode>
        <description>SUCCESS</description>
        <errorDescription>SUCCESS</errorDescription>
        <plan>
            <planDetail>
                <planName></planName>
                <planID></planID>
                <planPrice></planPrice>
                <talk></talk>
                <text></text>
                <data></data>
                <PlanServiceType></PlanServiceType>
				<is_unlimited_plan>Y</is_unlimited_plan>
				<data_unlimited>Y</data_unlimited>
				<text_unlimited>N</text_unlimited>
				<minute_unlimited>N</minute_unlimited>
            </planDetail>
        </plan>
    </GetPlanService>
</VcareOssApi>

SUCCESS

This API also checks the service availability on the provided zip code.

If the response returned by this API is SUCCESS however it does not return a list of the plans that means that there are no plans set up for the given state and zip code.

If the response is failure then the error description will be returned.

We need Y or N in the request because in Telgoo5 tribal plans are setup with tribal flag and if the tribal flag is sent as Y in response we only return the list of the tribal plan in that state if available.

<planName> This is the plan name.

<planID> This is the plan id to the corresponding plan and this plan id needs to be passed in the createcustomer API for the plan customer chooses.

<planPrice> This is the price of the plan which needs to be paid be the customer.

<talk> This is the number of talk minutes subscriber gets in the plan.

<text> This is the number of texts which are given in the plan.

<data> This is the amount of data (MB) provided on the plan.
<PlanServiceType> These are the NLAD service types for the corresponding plans.
V for Voice, BD for Broadband, BV for Bundled Voice, BBD for Bundled Broadband, BVBD for Bundled Voice and Broadband

Sample Fail Response: 1
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>13</statusCode>
	<description>FAIL</description>
	<errorDescription>Password is invalid.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Password is invalid.
How to Resolve?: Provide a valid Password.
Sample Fail Response: 2
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>15</statusCode>
	<description>FAIL</description>
	<errorDescription>Zip code is invalid.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Zip code is invalid.
How to Resolve?: Please enter valid zip code.
Sample Fail Response: 3
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>16</statusCode>
	<description>FAIL</description>
	<errorDescription>Vendor not found. Wrong credentials.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Vendor not found. Wrong credentials.
How to Resolve?: Please enter valid vendor credentials.
Sample Fail Response: 4
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>19</statusCode>
	<description>FAIL</description>
	<errorDescription>Service is not available for this Zip Code.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Service is not available for this Zip Code.
How to Resolve?: No service for the provided Zip Code. Please enter the right Zip code.
Sample Fail Response: 5
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>22</statusCode>
	<description>FAIL</description>
	<errorDescription>Plan not found.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Plan not found.
How to Resolve?: Provide a valid plan available in system
Sample Fail Response: 6
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>113</statusCode>
	<description>FAIL</description>
	<errorDescription>Zip Code is required.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Zip Code is required.
How to Resolve?: Zip code cannot be blank. You should enter a valid Zip code.
Sample Fail Response: 7
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>356</statusCode>
	<description>FAIL</description>
	<errorDescription>Agent ID cannot be blank.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Agent ID cannot be blank.
How to Resolve?: Please provide Agent ID as it cannot be blank.
Sample Fail Response: 8
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>457</statusCode>
	<description>FAIL</description>
	<errorDescription>Invalid Source.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Invalid Source.
How to Resolve?: Please provide a valid Source. Given value is invalid for Source.
Sample Fail Response: 9
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>517</statusCode>
	<description>FAIL</description>
	<errorDescription>State Code is required.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: State Code is required.
How to Resolve?: Provide correct State Code. A valid State code is required.
Sample Fail Response: 10
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>731</statusCode>
	<description>FAIL</description>
	<errorDescription>Type should be lifeline OR nonlifeline OR traditional.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Type should be lifeline OR nonlifeline OR traditional.
How to Resolve?: Provide a correct Type. Type should be lifeline or nonlifeline or traditional.
Sample Fail Response: 11
<?xml version="1.0" encoding="utf-8"?>
<VcareOssApi xmlns="http://www.oss.vcarecorporation.com/oss" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<credentials>
	<vendorId>Vcarecorporation</vendorId>
	<referenceNumber>11111</referenceNumber>
</credentials>
	<GetPlanService>
	<statusCode>751</statusCode>
	<description>FAIL</description>
	<errorDescription>Custom message.</errorDescription>
</GetPlanService>
</VcareOssApi>
Error Description: Custom message.
How to Resolve?: This is dynamic message.

All the status codes are listed under the status code sections. Please click here to go to the status code.