API 4 Developer Guide

Getting Started

In order to start calling the API v4 you will need API credentials. The credentials are a username and password and are tied to a specific Ventures site. If you are just starting out building your integration with Ventures you should have been given credentials for the test_integration site by the Ventures support team. It is against the test_integration site that you will develop and test your code.

Once your code is ready you’ll need credentials for the actual live Ventures site you intend to operate on.

Test your Credentials

Note: This documentation refers to the test Ventures instance (test_integration), but if you are using a production site then you would just replace the test URL with your production URL. For example https://test_integration.venturesgo.com would become https://myproductionsite.venturesgo.com.

It’s a good idea to verify that you can call the API with your credentials. To do this you can use the Ventures API Documentation (swagger) page on https://test_integration.venturesgo.com. Alternatively you could use something like Postman

Pro Tip: Postman will import the OpenAPI JSON file linked from the swagger page creating all endpoints.

Follow these steps to test your credentials:

1. Open https://test_integration.venturesgo.com in a browser.
2. Log in with your credentials.
3. In the footer click the Ventures API Documentation link. This opens the swagger page which documents the API and provides a basic test harness to call the endpoints.
4. Expand the token endpoint and click the Try it out button.
5. Enter test_integration for the client.
6. Enter your username and password.
7. Click Execute.
8. A successful response will look like this:
   

As you can see the swagger page shows the request (curl command) and response.

It is possible to test all endpoints directly on the swagger page. Note, to do so you’ll need to authorize your calls by clicking the Lock Icon and pasting your token string.

This page also shows you schema for the responses such as:

API URL

When calling the API endpoints you should use the URL:

https://api.venturesgo.com

not your Ventures site URL. Only use the Ventures URL to log into Ventures or view the swagger documentation. For example, the token url is https://api.venturesgo.com/api/v4/token.

Authorization

When calling the API the first thing you must do is retrieve an authorization token from the token endpoint. The token endpoint has three parameters:

1. The name of the Ventures site you are operating on. The sandbox name is test_integration.
2. Your username.
3. Your password.

If those three values are correctly passed then the token endpoint will return to you a token string. You will then use the token to authorize your calls to the other API endpoints. The token is passed to the other endpoints as a bearer token using the Authorization HTTP header. Here is a curl example:

curl -X 'GET' 'https://api.venturesgo.com/api/v4/objects' -H 'accept: application/json' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhcGl1c2VyIiwiY2xpZW50IjoidGVzdCIsImV4cCI6fTY1NDY0NTQxNiwiaXNzIjoiaHR0cDovz2FwaS52ZW50dXJlc2dvLmNvbSIsImF1ZCI6Imh0dHA6Ly9hcGkudmVudHVyZXNnby5jb20ifQ.JnxXkwwcwTAlITg81dzMBJgcYfBgiin3Vc4lty4Z-uw'

The issued token will expire after 60 minutes. You will need to get a new token at that point by calling the token endpoint again.

Objects Endpoints

The endpoints in the /api/v4/objects path are designed to provide typical CRUD operations for data objects in the Ventures system. Some objects may support extended operations beyond CRUD. Also some objects may only support read operations (list, get).

What objects are supported and the operations they support are discovered by calling the objects and describe endpoints.

• /api/v4/objects (GET) returns a list of the object types you can operate on. Examples of object types are Company and Contact.
• /api/v4/objects/{objectTypeName}/describe (GET) takes the name of the object type in the URL path and returns metadata about that object which includes the endpoints it supports. For example, /api/v4/objects/contact/describe returns the following endpoints:
  • api/v4/objects/contact (GET) - lists contacts
  • api/v4/objects/contact/{objectId} (GET) - returns a specific contact
  • api/v4/objects/contact (POST) - creates a contact
  • api/v4/objects/contact/{objectId (POST) - updates a contact
  • api/v4/objects/contact/{objectId} (DELETE) - deletes a contact

The describe endpoint further describes the fields for an object type. Knowing the fields on the object is important when calling the create and update endpoints. The metadata includes which fields are required when creating, their data type, etc. In addition, the metadata provides an example of how to construct the JSON for the object type.

Note: The list of objects supported by the API, and the fields they support, are continuously being expanded. If you find that the data you want to operate on is not currently supported, please reach out to Ventures support and let us know. We will do our best to accommodate the request.

Viewing your Data in Ventures

As you utilize the API you’ll often want to see how the data looks from Ventures. To do this you can log into Ventures using your API credentials.

Go to https://test_integration.venturesgo.com and log in. Once logged in you can view the loans, contacts and company information that you’re manipulating via the API.

You can also create new data directly in Ventures which you can then read back via the API.