Skip to content

Using the ISPCRM API

Overview

Welcome to the ISPCRM API documentation. This API allows developers to interface with the ISPCRM system, facilitating automated interactions with customer records, account management, and other CRM-related functionalities. Our API is designed to offer a robust solution for managing telecommunications services through a reliable, programmable interface.

Versioning

Managing versions of an API can be challenging, and various strategies exist to handle it effectively. For our ISPCRM API, we have chosen to embed the version number directly in the URL path. This approach makes it clear which version of the API is being accessed at any point.

We’re starting with version 1 (v1) as it indicates that the API is in its initial development phase. This versioning strategy helps us to iterate and make improvements while maintaining compatibility and clear communication with developers about the API’s lifecycle stage.

Base URL

All API requests should be made to the following base URL:

https://yourispcrmdomain/api/v1

This is the root URL for all API resources.

Authentication

For security purposes, the ISPCRM API requires Bearer Token authentication for all API requests. This means each request must include a valid API key, presented as a Bearer Token in the request header.

Obtaining a Bearer Token

To get a Bearer Token, you need to create it from the ISPCRM web interface. Follow these steps:

  1. Navigate to the /Admin/getToken page within the ISPCRM web interface.
  2. Click on ‘Create API access token’.
  3. Enter a description for the token (this step is optional).
  4. Click on ‘Create API Token’.
  5. Choose the user for whom you want to generate the token. The system will then create a token which you can use for making API requests.

Remember to store your API token securely and use it appropriately in your API requests as shown below:

Authorization: Bearer <your_token_here>

This approach ensures that access to the API is controlled and secure, protecting both the data and the integrity of your ISPCRM system.

Error Handling

The ISPCRM API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • 200 OK - The request was successful, and the response body contains the requested data.
  • 400 Bad Request - The request was invalid. This can be due to missing parameters or invalid data.
  • 401 Unauthorized - The provided Bearer Token is invalid or expired.
  • 403 Forbidden - The request is forbidden. Typically due to insufficient permissions.
  • 404 Not Found - The requested resource was not found.
  • 500 Internal Server Error - An error occurred in our servers. Try the request again.

Sample Error Message

{
  "status": "error",
  "message": "Unauthorized access - invalid token provided."
}

Sample Error Message

{
    "success":"true",
    "data":{"username":"jonewe","customer_id":"IZ1459296","status":"active","expiration":"2025-03-31 00:00:00","created_at":"2023-12-13 13:38:27","activated_at":"2023-12-13 00:00:00","mac":null,"profile_id":10,"profile_name":"100 Mbps","radius_id":20}
}

Endpoints

This documentation provides detailed descriptions and examples of the API endpoints. However, our API is designed to be navigable without prior knowledge of specific API routes. This is possible through the use of Hypermedia as the Engine of Application State (HATEOAS) principles, where each API response includes hyperlinks to other API endpoints, making the API discoverable.

Starting Your API Journey

You can begin exploring the API by initiating a request to the base URL:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://ispcrmdomain/api/v1

Example Output

The response will provide you with URLs to further resources. For instance:

{
  "list_users": "https://ispcrmdomain/api/v1/users"
}

This output shows the URL to access user information, allowing you to navigate through the API by following these links dynamically.

Input Methods

Interacting with the API involves sending data in several ways, depending on the action you want to perform. You may use one or more of the following methods to provide input:

1. Via API Route

You can pass parameters directly within the API route. This method is commonly used for retrieving specific resources. For example, to get details about a user by their ID, you would use:

/api/v0/Users/:id

Here, :id should be replaced with the actual user ID.

2. Via Query String

Parameters can also be passed via the query string to filter or customize the response. For instance, to list users but only those who are currently active, you would use:

/api/v0/users?status=active

This approach is useful for filtering lists or collections based on specific criteria.

3. Via JSON in the Request Body

When you need to add or update information, you’ll often send data as JSON in the body of the request. This is typical for POST requests where new resources are being created. For example, to add a new user, you might use a command like:

curl -X POST -d '{"ID":"jonmt", "version":"v1", "ID":"zt7633df"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://ispcrmdomain/api/v1/users

In this command: - -X POST specifies the HTTP method. - -d followed by JSON data specifies the payload. - -H adds an HTTP header for authentication.

Note: Ensure that your JSON data structure is correct and avoid duplicate keys in your JSON objects.

Output

The ISPCRM API primarily provides responses in one format:

JSON

Most interactions with the API will return data in JSON format. This format is used for nearly all API responses due to its ease of use and compatibility with web technologies. Here’s an example of a typical API call that returns JSON:

curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://ispcrmdomain/api/v1

Example JSON Response

{
  "users": [
    {
      "id": "1",
      "name": "John Doe",
      "status": "active"
    }
  ]
}

This JSON output illustrates how data is structured in a clear, readable format, making it straightforward for developers to parse and utilize in their applications.

Endpoint Categories