Getting Started With SaaS Insights API

Authentication

You’ll need to authenticate your requests to access any of the endpoints in SaaS Insights’s API. In this guide, we’ll look at how authentication works.

Bearer token

You will need your to generate you token — you will find it in SaaS Insights settings under API settings. Here’s how to add the token to the request header using cURL:

Example request with bearer token

curl https://saasinsights.com/api/public/metadata \
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -H "Authorization: Bearer {token}"

Always keep your token safe and rotate it if you suspect it has been compromised.

Pagination

We will look at how to work with paginated responses when querying SaaS Insights. By default, all responses limit results to 15. However, you can go as high as 100 by adding a per_page parameter to your requests.

In paginated responses, objects are nested in a data attribute and have pagination is nested in a meta attribute. That will indicate if there are more results, total pages and the current page.

Example

• per_page – Limit the number of items returned. Default 15, max 100.
• page – Page of results to be returned.

Manual pagination using cURL

curl -G https://saasinsights.com/api/public/metadata \
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -H "Authorization: Bearer {token}" \
  -d per_page=50 \
  -d page=1

Paginated response

{
    "data": [
        {
            "id": "aeda9be5-c9e1-40ec-8c76-be098262b7f6",
            // ...
        },
        {
            "id": "0dd0694a-3dd0-471b-81ec-286ef7ecb30c",
            // ...
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://saasinsights.com/api/public/metadata",
        "per_page": 15,
        "to": 2,
        "total": 2
    }
}

Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Let’s look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong.

Status codes

Here is a list of the different categories of status codes returned by the API. Use these to understand if a request was successful.

• 2xx – A 2xx status code indicates a successful response.
• 401 – You are not authorized to view/do this.
• 429 – Validation error.
• 5xx – A 5xx status code indicates a server error — if you see this, we’ll get a notification that something is broken.
  

Validation error

Whenever a request is unsuccessful, the SaaS Insights API will return an error response with an error error array and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is an example of a validation error.

• message – Summary of the error.
• errors – Fields that have not passed the validation checks required for the endpoint.

Validation Error response

{
    "message": "The amount field is required. (and 1 more error)",
    "errors": {
        "amount": [
            "The amount field is required."
        ],
        "name": [
            "The name field is required."
        ]
    }
}

Error response

{
   "message": "Unable to view Customer."
}

Rate limits – Error code 429

60 requests per minute.

Rate limit headers will be returned on each request. E.g.

X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14