Frequently Asked Questions

How do I get started using Rev.io's API?

I'm new to using Rev.io's API. Where should I begin?

Here are some resources you can use to start developing with our APIs:
REST: https://developers.rev.io/docs/getting-started
SOAP: SOAP vs REST API Comparison

Can I view specific fields?

When I make a request to view a resource, can I specify which fields I want to see?

No. We're interested in this feature but don't have plans to add it yet.

Is Rev.io using the API internally?

Are you currently using your API in your own code?

Not yet, but we will be! Up until now, we've focused on making the API available to you. Now, we're going to start improving it and using it in our own services, including Rev.io.

Do I have to use basic authentication?

When I authorize my requests, can I do that without using basic authentication each time?

Not yet. We're testing OAuth 2.0 right now, which you'll be able to use instead once it's available.

How do I authenticate my credentials?

How do I authenticate my credentials for the REST and SOAP API?

REST: In your request’s authorization header, add your credentials in the format Username@Client_Code:Password, encrypted as a Base64 token.

username@clientcode:password

Please review this page for more details about Basic Authentication.

Why are my API Explorer credentials not working?

If I can't get into the API Explorer with my credentials, what should I do?

Make sure to specify your instance name or client code after your username, separated with an @ symbol. In example: Username@Client_Code

Ensure your username is not an email address. The additional @ symbol will cause validation to fail.

Ensure the user account you’re trying to send requests with exists. You can check this under Settings > Users.

Verify that your user role has the necessary permissions to send API requests. You can check this under Settings > Permissions.

Why are my requests setting null or empty values?

Why are my SOAP API requests setting null or empty values?

When you create a new request template (after importing our WSDL file), you’ll need to remove fields that you aren’t using. The API will interpret empty fields in a PATCH or PUT request as an attempt to set those fields to null.

What fields are required for this endpoint?

Our API Explorer shows required fields with a red asterisk* next to them.

How many records can I request at once?

What is the record limit?

There isn’t a limit. Ten records are returned by default. You can paginate the records and send additional requests for more as needed.

Use the following parameters to control pagination:

Search.page_size: The number of records per page.
Search.page: The specific page of results to return.
Search.sort: Specifies a field to sort by. Defaults to ascending. Add “-” before the name of the field to sort in descending order.

What does this API error message mean?

I received an error, what do I do now?

Most error messages are descriptive, so use the feedback to check your request for bad inputs or missing required fields. If an error message is generic and doesn’t explain the problem clearly, please reach out to our Client Success team here.

How do I format a PATCH request?

The request will need to be in JSON Patch format
The content-type header should be set to “application/json-patch+json”.
PATCH requests are explained in more detail here.

How do I complete orders using the REST API?

Submit a PATCH request to change the order status to complete. Here is an example below of what your patch data could look like:

curl -X PATCH \ https://restapi.rev.io/v1/Orders/1234 \ 
-H 'Content-Type: application/json-patch+json' \ 
-d '[ { "op": "replace", "path": "/status", "value": "COMPLETE" }, { "op": "replace", "path": "/effective_date", "value": "2019-09-11" } ]'

Where do I find the ID for this record?

How do I find IDs for the records I want to access in my requests?

Most grids in Rev.io will show IDs in the left-most column, such as the “Bills” and “Payment History” tabs shown on the customer profile page. IDs can also be found in URL parameters. For example, while viewing a customer profile, there is a “Customer_ID=” parameter that can be seen in the URL. The integer following that parameter is the primary key of that customer as it exists in the database. The “search” (REST) or “query” (SOAP) endpoints can also be used to find IDs.

How should I format datetime values?

What time zone should I use for datetime values in my request?

Datetime values generated by Rev.io use US Central Standard Time. Any dates posted to our database will not be converted to CST. This should be considered when submitting data with timestamps based on a time zone outside of CST. In most cases, we recommend stripping the timestamp from your dates.

How do I handle dropdown fields in the API?

How do I create or update an object with fields that utilize dropdowns?

If you attempt to update a dropdown, the value you supply must be one of the predefined options or your request may fail and you will get an “INVALID VALUE” message.

Are custom fields available through the API?

Both our REST and SOAP APIs support custom fields.
To update a custom field, you will need to supply an array called fields, and each item in the array must contain either the field_id or the field_label (the label you assigned to your custom field) as well as the value for the custom field.
Refer to the API documentation here for examples in the REST API.
When retrieving data from either API, any object that has custom fields will return fields as an array containing field_id, field_label and value.

How do I get data from Rev.io that doesn't have an existing endpoint?

Our APIs have the ability to run any of your user-created reports and return their results. Using this functionality, you can essentially create your own GET endpoints. Refer to these endpoints for running reports:

REST
SOAP

How do I get access to the sandbox?

How do I request access to the Rev.io API sandbox for developer testing?

Contact our Client Success team and we’ll create an account for you. You can read more about our API sandbox here.

How do I request new functionality for the REST or SOAP API?

We are always looking for ways to improve our APIs! If you have a suggestion, please feel free to submit a “Rev.io Idea”. If our API is missing functionality that is critical for your organization, please reach out to our Client Success Team.

Is there a maximum URL length for queries to the REST API?

Yes, but it is more of a limit to the query string or the total characters without the Path. The query string is limited to 2,048 characters.