VoIP Reseller API Beginners Guide Part 2

The previous post explained how to obtain your credentials and how to authenticate against the VoIP Reseller API, in this post we'll discuss how to create your customers, and the best practices for keeping them correctly segregated.

Why Segregate my customers?

It is vital to create a unique customer object for all of your clients, this allows each customer to have their own set of extension numbers (1001, 1002 etc...) but more importantly it allows each customer to have an independent call history and PAYG credit balance. Without segregation all calls would come from the same balance plus there would be a single call history of everyone's calls.

How to create a customer

In order to create a customer, you need to POST a customer object to the Accounts/Sub-Reseller endpoint

The following JSON is the minimum valid request body to create a customer

{
    "name": "my_customer_name",
    "contact_name": "Customers Contact Name"
}

The name field is used to act on behalf of this customer later via the API, it must be unique to the platform, we generally recommend you use a random string for this field.

Using X-Auth-For to manage your customers

Now you have created your customers, you can use the VoIP Reseller API to create things such as domain names, SIP users or phone numbers for them. To do this we will introduce a new HTTP header that allows your to perform API commands on behalf of this customer, while still billing your primary account.

To create an object on behalf of your customer, you should provide an additional authentication header called X-Auth-For, the value of this header should be the name field for the customer you have created

When using this header, the command will execute on behalf of the customer, so anything created or updated will belong to this customer. However the cost will be charged to your primary account balance.

As an example, the below request would get all SIP users for the customer named my_customer_name

GET /voip/user HTTP/1.1
X-Auth-Reseller: reseller
X-Auth-User: user
X-Auth-Password: password
X-Auth-For: my_customer_name
Host: api.yay.com
Connection: close
User-Agent: MyAPIApp 1.0

How do I create a customer for one of my Stores?

If you are using our comprehensive VoIP reseller package, you might want to use the API to create a new customer for the store. In order to do this you need to provide the UUID of the store during the customer creation process above. Additionally you will need to create at least one address and user. Creating a user will allow your customer to log in to your store. role_id must be 3 to create a store user

{
    "name": "my_store_customer_1",
    "users": [{
        "contact_first_name": "Geoff",
        "contact_last_name": "Wilson",
        "name": "admin",
        "password": "password",
        "role_id": "3",
        "email": "customer@example.com"
    }],
    "addresses": [{
        "street_one": "Westbury House",
        "city": "Guildford",
        "state": "Surrey",
        "zip": "GU2 4AW",
        "country_code": "GB"
    }],
    "store_front": "3951ec81-cca4-4c4a-8efb-4bce76e04032",
    "contact_name": "Geoff Wilson"
}

Help! I forgot my customer or store details?

If you need to query your customers or stores to get the necessary details for the X-Auth-For header or the store_uuid to create new customers, you can use the following API commands to get a list of all customers and stores in your account

The GET Account / Sub-Resellers command will return a list of all of the customers under your control.

The GET Account / Stores command will return a list of all the reseller store fronts under your account

When using both of these commands the X-Auth-For header should NOT be provided

How do I allocate calling credit to my customers?

The final topic we will cover today, is allocating calling credit to your customers. This command works by taking the balance from your pre-pay account, and transferring it to your customer to spend on calls

In order to transfer calling credit, you will need the UUID of your customer, you can use the command above to query your customer data and obtain the UUID

PUT /account/reseller/uuid_of_your_customer HTTP/1.1
X-Auth-Reseller: reseller
X-Auth-User: user
X-Auth-Password: password
Host: api.yay.com
Connection: close
User-Agent: MyAPIApp 1.0

{"balance":"10.000"}

The URL of the request should include the UUID of the customer to move the credit to, the body is a simple JSON object that contains the balance you would like to move

You may transfer any amount from 0.01 up to your current balance. It is not possible to reverse the transfer, so please ensure you have collected the necessary payment from your customer before issuing this command