Getting Started

📘
New to Rev.io or APIs? Learn more about us.

With our REST API, it's easy to manage your customers and your billing. Let's get started!

On this page, we'll walk you through an example workflow: adding a new customer, creating a request or quote for new service, and opening a task on that customer for someone to come back and review the request at a later date.

Add a customer

First, let's add a new customer.

Search for a bill profile

Bill profiles define how you want to bill your customer, including billing cycle rules, collection templates, and fees. Every customer needs a bill profile, so let's see what's available.

curl --request GET
  --url https://restapi.rev.io/v1/BillProfiles

Here's what we get:

{
  "ok": true,
  "has_more": false,
  "record_count": 3,
  "records": [
    {
      "bill_profile_id": 1001,
      "description": "Sample Bill Profile",
      "lead_days": 0,
      "advance_months": 1,
      "term_days": 9,
      "cycle_type": "CYCLE",
      "cycle_direction": "BACKWARD"
    },
    {
      "bill_profile_id": 1002,
      "description": "Sample Bill Profile- Auto Debit required",
      "lead_days": 2,
      "advance_months": 2,
      "term_days": 5,
      "cycle_type": "CYCLE",
      "cycle_direction": "BACKWARD"
    },
    {
      "bill_profile_id": 1003,
      "description": "Late Fee Test Profile",
      "lead_days": 0,
      "advance_months": 1,
      "term_days": 9,
      "cycle_type": "CYCLE",
      "cycle_direction": "BACKWARD"
    }
  ]
}

Looks like there are 3 bill profiles available. Let's say we want to put our new customer on the "Sample Bill Profile." We'll remember its ID, 1001, for later.

Create a customer

Time to add our customer. Notice how that bill profile ID is specified near the end of the request.

curl --request POST
  --url https://restapi.rev.io/v1/Customers
  --data '{
    "profile":{
  	  "class":"Business",
      "language":"Spanish"
    },
    "billing_address":{
      "company_name":"My New Company",
      "line_1":"514 S Magnolia St",
      "city":"Orlando",
      "state_or_province":"FL",
      "postal_code":"32806",
      "country_code":"USA"
    },
    "service_address":{
      "company_name":"My New Company",
      "line_1":"514 S Magnolia St",
     "city":"Orlando",
     "state_or_province":"FL",
     "postal_code":"32806",
      "country_code":"USA"
    },
    "finance":{
      "bill_profile_id":1001
    }
  }'

We get this response back:

{
    "ok": true,
    "id": 1029
}

Our new customer's ID is 1029.

Put in a service request

Now that we've created that customer, let's put in a request to set them up with new service.

Create the request

Let's say we know our user ID is 77, the request status ID is 15, and we want to assign this request to ourselves.

curl --request POST
  --url https://restapi.rev.io/v1/Requests
  --data '{"customer_id":1029,"request_status_id":15,"assigned_to":77}'

Here's the response, telling us our newly created request has ID 2908:

{
    "ok": true,
    "id": 2908
}

Find a product

Let's see what products we can request for our new customer. We'll search through our product catalog, which contains all the products we offer, for data products.

curl --request GET \
  --url https://restapi.rev.io/v1/Products?description=data

Looks like we have 1 data product in our catalog, ID 1004:

{
  "ok": true,
  "has_more": false,
  "record_count": 1,
  "records": [
    {
      "product_id": 1004,
      "product_type_id": 5,
      "description": "MySQL Database",
      "code_1": "",
      "code_2": "",
      "rate": 0,
      "cost": 10,
      "buy_rate": 10,
      "created_date": "2009-05-21T17:49:36",
      "created_by": 13,
      "active": true,
      "creates_order": true,
      "provider_id": 1002,
      "bills_in_arrears": false,
      "prorates": true,
      "customer_class": null,
      "long_description": "",
      "ledger_code": null,
      "free_months": null,
      "automatic_expiration_months": null,
      "order_completion_billing": false,
      "tax_class_id": null
    }
  ]
}

Add a service

Before we can get that data product onto the request we just created, we need to add a service it'll be attached to. Let's say we know we want this service to be service type 29 and have provider ID 1000.

curl --request POST
  --url https://restapi.rev.io/v1/RequestServices
  --data '{
   "request_address_id": 1503,
   "request_id": 2908,
   "service_type_id": 29,
   "provider_id": 1000
}'

We get back a new request service with ID 2793.

{
    "ok": true,
    "id": 2793
}

Add a product

Now let's go ahead and add that product to the service we just created.

curl --request POST \
  --url https://restapi.rev.io/v1/RequestProducts \
  --data '{
   "request_service_id": 2793,
   "request_id": 2908,
   "product_id": 1004,
   "quantity": 1
}'

Here's our new request product:

{
    "ok": true,
    "id": 1295
}

Open a task

Looks like our request is all set! Finally, let's add a task to that customer to make sure we remember to review and approve that request at some point.

View task types

First, let's see what task types we have available.

curl --request GET \
  --url https://restapi.rev.io/v1/TaskTypes

{
  "ok": true,
  "has_more": false,
  "record_count": 2,
  "records": [
    {
      "task_type_id": 1,
      "description": "Contact Customer"
    },
    {
      "task_type_id": 2,
      "description": "Review Request"
    }
  ]
}

Add a task

Task type 2 looks perfect. Let's go ahead and create a task with that type. We'll assign it to ourselves.

curl --request POST \
  --url https://restapi.rev.io/v1/Tasks \
  --data '{
   "assigned_to": 77,
   "subject": "Review request",
   "description": "Review this customer'''s request for new service!",
   "customer_id": 1029,
   "task_type_id": 2
}'

{
    "ok": true,
    "id": 553
}

Finished!

Great work! You've now set up your first customer through the API. But there's lots more you can do. Check out what's next below:

Need us to break down the basics of our API? Take a look at our API 101.
Want a more detailed look at how to make requests? Check out our tutorial.
Curious about what else you can do with our API? We've got some more examples ready for you.
Or jump right into our API explorer to see what else you can accomplish.