With Inperium API, you can easily access our apps and create integrations with other products. Our API is meant to be simple and human-readable: you send requests to endpoints and get responses, just like with any other REST API.

This API reference describes public Inperium endpoints and methods as well as explains important concepts that will help you create awesome integrations with Inperium products.

How is Inperium API organized?

Inperium allows access to all Inperium products as well as common services running under the hood. Depending on your goal, look for endpoints in a corresponding section:

• Sell API - provides access to contacts, companies, deals, and many more.
• Talk API - provides access to calls, auto-receptionist settings, etc.
• Hub API - provides access to common settings, user and role management, subscription settings, etc.
• Message Center API - facilitates sending and receiving emails within Inperium Sell.
• Object Bucket Storage API - manages documents and files stored with Inperium.
• Talk Call Queue API - manages call queue functionality in Inperium Talk.
• Talk Number Porting API - facilitates transferring phone numbers to Inperium Talk.

New to the API world? Need more details about REST API?

With an API (application programming interface), you can request data or send it to the app without any visual user interface (what you see on your screen). It’s handy for computer-to-computer interaction. In most cases, APIs sort of copy what humans do while using the app.

In REST APIs, the data is sent in and out through specially exposed gateways, called endpoints. A company with a public API allows access to its resources through a dedicated server. Together, the server name followed by an endpoint look like a regular URL. For example, for Inperium it can be https://api.inperium.com/v1/sell/companies.

While each service operates differently, in general you will leverage standard HTTP methods such as GET to query data and POST, PUT, or PATCH to submit data. Standard HTTP responses such as 200 OK or 401 Unauthorized will notify on the call results. Along with these requests, you’ll send or receive data. For example, after querying the list of companies, you’ll get a JSON with company objects. But to create a new company, you have to send a company object in a POST body instead.

To access Inperium resources, you’ve got to authenticate your API calls. Inperium allows authenticating with Bearer tokens and with API keys. The latter method is recommended.

API key authentication

The API key is a safe and reliable way to authenticate and authorize your apps with Inperium. Start by creating an API key in Inperium Account. Learn more about generating API keys. Note that Inperium doesn’t store the unencrypted API key, just the last four digits so make sure to copy it before closing the popup window.

To authenticate your calls, include X-API-KEY in the request header.

The API key has the same permissions as the user who generated it (for example, view-only rights). To see your permissions, send GET /users/me request. An API key is valid for 365 days. Once the key expires, the access to Inperium resources will be revoked.

Bearer authentication

When authenticating with a Bearer token, you leverage the same very token that is generated when you log in to the product online. With a token, you can send requests to Inperium API and get access to resources the user is authorized to see. The bearer token consists of the access token and the refresh token. Initially, look for them in the Local Storage.

The Authorization: Bearer should be provided in the request header for every call you make.

The token expires after 1 minute. To continue using API, you have to refresh it by sending a request to /auth/tokens/. The refresh token is valid for 10 minutes.

Ready to start? Let’s dive right in. Follow these steps to get started with Inperium API.

Get your Inperium account

Make sure you have an account with Inperium. It’s a good idea to create a new account dedicated to API integration.

If you are the first user and need more information on how to set a tenant, then refer to Inperium user documentation.

Generate an API key

To authenticate your calls to Inperium API, you have to provide an API key with each request. Otherwise, Inperium will return an error 401 Unauthorized.

To get a key:

1. Go Inperium Account, sign in, and proceed to the API key page.
2. Select Add API key, enter its name, and click Generate.
3. Copy the key and save it to a secure location. Note that Inperium doesn’t store the unencrypted key and you won’t be able to see it after closing the window.

Understand Inperium API structure

Depending on your goal, look for endpoints in a corresponding section:

• Sell API - provides access to contacts, companies, deals, and many more.
• Talk API - provides access to calls, auto-receptionist settings, etc.
• Hub API - provides access to common settings, user and role management, subscription settings, etc.
• Message Center API - facilitates sending and receiving emails.
• Object Bucket Storage API - manages documents and files stored with Inperium.
• Talk Call Queue API - manages call queue functionality in Inperium Talk.
• Talk Number Porting API - facilitates transferring phone numbers to Inperium Talk.

Send a test GET request

Note: for this tutorial, we assume your company has an active subscription to Inperium Sell.

Let’s start with a safe and easy API call. We’ll query the products currently offered by your company.

Request:

curl -i -X GET \
   -H "Accept:application/json" \
   -H "X-API-KEY:$YOUR-APIKEY" \
 'https://api.inperium.com/v1/sell/products'

Response:

200 OK

{
    "data":[
        {
        "id": "$ID-UUID",
        "tenantId": null,
        "properties":{
            "code": "fl",
            "cost": 350,
            "price": 520,
            "name": "Flute",
            "description": "Entry-level flute"}
        },
        {},
        ...
    ],
    "paging":{
        "pageNumber": 1,
        "pageSize": 20,
        "totalNumberOfRecords": 52,
        "totalNumberOfPages": 3,
        "hasNextPage": true,
        "hasPreviousPage": false,
        "sortingCriteria": "+createdAt",
        "hasMore": true
    }
}

Add query parameters

Like with any other REST API, you can modify your queries by adding parameters. For example, change the number of objects returned per page or query the objects from the next page. For example, let’s update the query to return 25 records per page and get the second page.

curl -i -X GET \
   -H "Accept:application/json" \
   -H "X-API-KEY:$YOUR-APIKEY" \
  'https://api.inperium.com/v1/sell/products?pageSize=25&pageNumber=2'

Send a test POST request

Let’s add a new product. Before sending a POST request, check the incoming object specification, i.e. the parameters the object must have to be accepted by Inperium API. You can always look for the request object in API reference.

In case the object has JSON-formatted properties (and the ProductRequest object does!), retrieve properties by sending GET to https://api.inperium.com/v1/sell/properties?objectType=Products.

Request:

curl -i -X POST \
   -H "Accept:application/json" \
   -H "X-API-KEY:$YOUR-APIKEY" \
   -H "Content-Type:application/json" \
   -d \
    '{
        "code": "hp",
        "cost": 7600,
        "price": 11990,
        "name": "Harp",
        "description": "Full-size pedal harp"
    }' \
 'https://api.inperium.com/v1/sell/products'

Response:

201 CREATED

Send a test DELETE request

1. To delete a newly created Harp object, you must find out its ID first. Let’s query products and search for “Harp”.

Request:

curl -i -X GET \
   -H "Accept:application/json" \
   -H "X-API-KEY:$YOUR-APIKEY" \
 'https://api.inperium.com/v1/sell/products?name=Harp'

Response:

200 OK

{
    "data":[
        {
            "id": "$ID-UUID",
            "tenantId": null,
            "properties":{
                "code": "hp",
                "cost": 7600,
                "price": 11990,
                "name": "Harp",
                "description": "Full-size pedal harp"
            }
        }
    ],
    "paging":{}
}

2. Now, knowing the Harp object ID, send a DELETE request to the /products URL ending with the ID of the object to be deleted.

Request:

curl -i -X DELETE \
   -H "Accept:application/json" \
   -H "X-API-KEY:$YOUR-APIKEY" \
 'https://api.inperium.com/v1/sell/products/$ID-UUID'

Response:

204 NO CONTENT

PUT or PATCH?

Inperium allows modifying data with PUT and PATCH requests. The former completely re-writes the object while the latter updates the parameters you pass and keeps remaining as they are.

Inperium APIs operate with objects. High-level objects can include smaller subordinary objects. For example the Quote object includes Items, PaymentPlans, and AdditionalFees.

In some cases, the object you submit and the object you receive may slightly vary in structure. The objects returned by Inperium API typically include the UUID generated by the server and other additional parameters. To distinguish models, the incoming object names typically end with “request”. For example, CompanyRequest, ProductRequest, or BillingCompanyRequest.

Incoming object model - CompanyRequest

{
    "companyName": "Arrow Inc.",
    "industry": "RETAIL",
    "type": "LEAD",
    "employeeCount": "100",
    "addressLine1": "232 1st street",
    "addressLine2": "Suite 2210",
    "city": "Newtown",
    "country": "US"
}

Inperium API uses standard HTTP responses for API calls. Depending on the request method (POST, GET, DELETE, PUT, or PATCH), you’ll receive a response that can either be successful or failed.

Successful responses

• 200 OK is returned for successful GET, PATCH, and PUT operations.
• 201 CREATED is returned for successful POST operations.
• 204 NO CONTENT is returned for successful DELETE operations.

200 and 201 responses return the object in the response body. Note that incoming objects and the objects returned in response may slightly vary in structure.

Error responses

• 400 BAD REQUEST
• 401 UNAUTHORIZED
• 404 NOT FOUND
• 405 METHOD NOT ALLOWED
• 500 INTERNAL SERVER ERROR and other 5XX errors

The errors come with a description explaining the issue.

For most high-level GET requests, Inperium enables you to filter data before retrieving it. You can create flexible and complex queries while searching for records you are interested in. The parameters you can filter by are listed in the parameters section for each endpoint call.

Basic filtering

For queries such as “List US-based companies” or “Retrieve all outbound calls”, you can leverage simple filtering. Add a filtering parameter to your API call and provide the value you are looking for: /endpoint?{parametername}={value}. The Inperium API will return records that are exact matches.

For example:

• https://api.inperium.com/v1/sell/companies?country=US
• https://api.inperium.com/v1/talk/calls?direction=outbound

To learn about the filtering parameters, check out descriptions for each endpoint and operation individually.

Filtering with match type operators

Available in Hub API, Message Center API, OBS API, Talk API, Talk Call Queue API, and Talk Number Porting API.

You can leverage operators such as ‘like’ or ‘equals’ and look for a wider range of records. Add {parametername}={operator}::{value} to your query.

For example,https://api.inperium.com/v1/talk/contacts?fullName=like::L returns all contacts whose names contain the letter L.

Supported operators

Advanced filtering with grouping

Available for specific endpoints in Sell API, Talk API, and Hub API

Advanced filtering is a versatile tool for data management. You can create multi-tier complex queries combining AND and OR clauses, organizing filtering parameters into groups, introducing nesting, searching for fuzzy results, etc. The endpoint calls that support advanced filtering have a special filter parameter and explicitly mention the possibility of advanced filtering.

To introduce an advanced query, add filter={operator}({parameter},{value}). Each {value} can be replaced with a subgroup.

For example, you can search for companies that either demonstrated annual revenue of more than $500,000, or have more than 1,000 employees and reside in the U.S. Seems complex? But let’s break it down into logical groups.

• [Annual revenue > $500,000] — Condition 1

OR

• [Employee count > 1,000] AND [Country is USA] — Condition 2 that includes two sub-conditions with AND relationship

On a high level, the filter string looks like: filter=OR(Condition1,Condition2). The condition 1 is: gt(annualRevenue,500000) The condition 2 is a conjunction of two subconditions joined by AND: AND(gt(employeeCount,1000),eq(country,US))

As a result, the final API call will look as follows:

GET https://api.inperium.com/v1/sell/companies?filter=OR(gt(annualRevenue,500000),AND(gt(employeeCount,1000),eq(country,US)))

Supported operators

Paging

To avoid time-consuming queries, Inperium returns data page after page while you can control the number of objects per page and the offset. For example, you’d like to get your companies and run the GET /companies query. Inperium will return the first 50 records and notify you about the remaining companies in the paging section. To query the next 50 records, add the pageNumber=2 parameter to your query. Alternatively, you can update the pageSize parameter.

Sorting

With most data fetching queries, you can sort the results by a certain parameter, for example by name or price, either in ascending (+) or descending (-) order. By default, sorting isn’t applied. To configure sorting, add the sort parameter to your query. For example, sort the companies by the country they originate in, in descending order: sort=-country.

Understanding response

The paging response section is available with almost all bulk listing queries such as GET /companies, GET /contacts, or GET /quotes. Here, you’ll find information about paging and applied sorting.

• pageNumber: the current page number. If no sorting is applied, the records are divided into pages based on their position in the database, starting from the bottom.
• pageSize: the number of records returned per page. By default, 20.
• totalNumberOfRecords: how many records are available in total.
• totalNumberOfPages: how many pages are populated all together.
• hasNextPage: the true value notifies you that there are more pages containing records. The false value means this is the last page.
• hasPreviousPage: the true value notifies you that there are pages before the current one. The false value means this is the first page.
• sortingCriteria: the null value marks that no sorting is applied. + with a parameter name means ascending sorting (e.g., +price), - with a parameter name means descending sorting (e.g., -country).
• hasMore: the true value notifies you that there are more records besides those retrieved. The false value means this is no more data left.

We’ve enforced rate limiting for API calls to ensure all customers have no-latency access to Inperium resources. If API key exceeds the call limit, you won’t have access to Inperium API for a while.

We encourage you to create custom integrations with Inperium and enrich your corporate workflows.

In our turn, we are about to launch the Inperium Marketplace, a place with useful apps and ready-to-use integrations that will help you seamlessly connect Inperium products with your favorite tools.