iPlum usage logs API documentation

Introduction

iPlum API is built using REST (Representational State Transfer Application Program Interface). API calls can be made using all popular programming languages. The API follows secure HTTP rules, enabling a wide range of HTTP clients to interact with the iPlum API.

‍

Getting Started

Access to iPlum API requires that the account has the API feature enabled.

  1. Log in with your administrator credentials at https://my.iplum.com
  2. Go to Left Menu → API & Call Backs
  3. Toggle the API switch to enable it.

‍

API Endpoint

https://api.iplum.com/

‍

HTTPS Method

All iPlum APIs are accessed over HTTPS and use POST requests for every action.

POST used for

1. Get data.

2. Creating resources.

3. Performing resource actions.
‍

Request Headers

Every request must include the following mandatory headers:

  • X-iPlumAuth-AccessKey — The access key generated by the API.
  • X-iPlumAuth-Username — The iPlum Login ID of the administrator.
  • X-iPlumAuth-EpochDateTime — Date and time in Epoch format.
  • X-iPlumAuth-Version — The desired version of the request.
  • Authorization — iPlumAuth <signature>
  • Content-Type — application/json

‍

Authorization

To generate the iPlum API authorization header, use the HMAC-SHA256 signing algorithm.

‍

Steps to Generate HMAC Signature

1. Generate access keys:

      • Log into the iPlum website at https://my.iplum.com

      • Click on the "API & Call Backs" link on the left menu bar.

      • Toggle the API switch if not enabled.

      • Download and save your API access and secret keys.

‍

2. Create a request for the iPlum API:

      • Create a HTTP request Object:

       HttpRequestMessage request = new HttpRequestMessage();

      • Create a HTTP header with the API access key

       request.Headers.Add(“X-iPlumAuth-AccessKey”, “ABCD123ACCESSKEY”);

      • Create a HTTP header with the iPlum administrator login ID:

      request.Headers.Add(“X-iPlumAuth-Username”, “test@testuser.com”);

      • Create a HTTP header with the version:

      request.Headers.Add(“X-iPlumAuth-Version”, “v1”);

      • Create a HTTP header with the epoch date time:

     request.Headers.Add(“X-iPlumAuth-EpochDateTime”, “1490752181”);

‍

3. Create a string which is a concatenation of the headers built above along with the following:

      • http method requested (in lower case). E.g., “post”

      • the URL of the requested resource (in lower case). E.g., “/usage/getusage”

      • iPlum administrator login ID (in lower case).

      • Version (in lower case). E.g., “v1”.

‍

Use this concatenated string as 'representation'.

‍

       string representation = String.Join(“\n”, httpMethod.ToLower(),

       requestMessage.Headers.GetValues(“X-iPlumAuth-AccessKey”).FirstOrDefault(),

       requestMessage.Headers.GetValues(“X-iPlumAuth-Username”).FirstOrDefault(),

       requestMessage.Headers.GetValues(“X-iPlumAuth-Version”).FirstOrDefault().ToLower(),

       requestMessage.Headers.GetValues(“X-iPlumAuth-EpochDateTime”).FirstOrDefault().ToLower(),

       uri.ToLower());

‍

4. Generate a HMAC signature using both secret key and representation.

‍

5. Base-64 encode the generated HMAC signature and add it in the Authorization header.

        requestMessage.Headers.Add(“Authorization” , “iPlumAuth” + “ “ + signature);

‍

6. The final iPlum API request header should look like below:

‍

‍

‍

‍

‍

7. Send content within the body section of the request.

‍

RESPONSE

All iPlum API requests and responses use JSON format.

‍

‍

Response Codes

  • 200 — Success. The request was completed successfully.
  • 400 — Bad Request. Malformed or missing parameter.
  • 401 — Unauthorized. Invalid authentication credentials.
  • 403 — Forbidden. Insufficient permission to access the resource.
  • 404 — URL Not Found. The URL is incorrect or the resource has moved.
  • 405 — Method Not Allowed. The resource does not support the HTTP method used.
  • 406 — Not Acceptable. Response type not supported by the client.
  • 429 — Too Many Requests. Rate limit exceeded.
  • 500 — Server Error. Contact us if this persists.

‍

Usage (Call, Text, Fax Logs)

A user can use iPlum for calls, text, and/or fax. This usage history can be retrieved using the iPlum API.

‍

Get Usage Records

Fetches calls, text, and/or fax usage logs.

URL: POST /usage/getusage


Request Parameters

  • Lang — ISO 639-1 language code. Data Type: String. Default Value: en
  • Usage — List of all usage types. Multiple values can be provided using a comma separated list. Accepted values: iPlumtext, externalcall, externaltext, fax. Description: iPlumtext: iPlum secure text, externalcall: External call, externaltext: External text, fax: Fax
  • ‍StartDate — Start date filter for usage records. Data Type:  String. Default Value: Empty
  • ‍EndDate — End date filter for usage records. NOTE: The end date should not be greater than 5 days from the start date. Data Type:   String. Default Value: Empty. Accepted format: Date Time in UTC format.


Request Header Example

Content-Type: application/json
X-iPlumAuth-AccessKey: ABCD1234ACCESSKEY
X-iPlumAuth-Username: test@testuser.com
X-iPlumAuth-Version: v1
X-iPlumAuth-EpochDateTime: 1696387075
Authorization: iPlumAuth Hn6YFjVUpQCLgH8AWss8Nyp5M6eQiOKnaMZkExTJL/4=


Request Body Example

{"Lang":"en", "Usage":"iplumcall,externaltext", "StartDate":"2023-03-20 02:23:06.000", "EndDate":"2023-03-24 02:23:06.000"}


Response Fields

  • source — Source of usage record. Data Type: String. Value: iPlum
  • clientReferenceId — Custom value set on the account. Data Type: String
  • recordId — Unique usage record ID. Data Type: String
  • usage — Usage category. Data Type: String. Possible Values: call, text, fax
  • type — Usage type. Data Type: String. Possible Values: iplum, external
  • from — From number. Data Type:   String
  • to — To number. Data Type:   String
  • startTimeUTC — Start date and time of usage (UTC). Data Type:   String
  • endTimeUTC — End date and time of usage (UTC). Data Type:   String
  • duration — Duration in minutes. For text, value will be 1. Data Type:   String
  • direction — Direction of usage. Data Type: String. Possible Values: in, out
  • iPlumCredits — iPlum credits used. Data Type: integer
  • userId — iPlum user to which the usage belongs. Data Type:   String

‍

Response Example

[{"source":"iPlum", "clientReferenceId":"1234", "usage":"call", "recordId":"0UmFAs73cwKbyqUtmz7ltLI.nGlAD.0Dgjdhpm", "from":"+14081231234", "to":"test@iplum.com", "startTimeUTC":"2023-03-24T00:00:00Z", "endTimeUTC":"2023-03-24T00:00:00Z", "duration":"2", "direction":"in", "type":"external", "iPlumCredits":2, "userId":"test@test.com"}]

‍

Error Response

In case of errors (HTTP Status code 400 / 500), iPlum API shall send the error details in the response.

Model

errorCode: Error code. Data  Type:   String

errorDescription: Error  description in the language specified in the request. Data  Type:   String

‍

Error Codes

  • ERR_INVALID_DATE — The date range specified in the request is not valid. The end date should not be later than 5 days from the start date.
  • ERR_INVALID_REQUEST — Request has invalid parameters.

‍

‍

Get Usage Content

Fetches the content of a sent/received text or fax.

Endpoint: POST /usage/getcontent

‍

Request Parameters

  • Lang — ISO 639-1 language code. Data Type:   String. Default: en
  • RecordID — Usage record ID. Data Type:   String

‍

Request Header Example

Content-Type: application/json
X-iPlumAuth-AccessKey: ABCD1234ACCESSKEY
X-iPlumAuth-Username: test@testuser.com
X-iPlumAuth-Version: v1
X-iPlumAuth-EpochDateTime: 1696387155
Authorization: iPlumAuth FvWXGLoxw0zy9tu381IyebstzBVCw8YJtVm+VGmtQIo=

‍

Request Body Example

{"Lang":"en", "RecordID":"0UmFAs73cwKbyqUtmz7ltLI.nGlAD.0Dgjdhpm"}

‍

Response

Returns a string — either plain text content or a URL for a photo/audio/video/fax attachment.

Text example: Hello

Media URL example: http://media.iplum.com/af542549-527a-47c8-a183-b853455501c0.jpg

‍

Error Codes

  • ERR_INVALID_REQUEST — Request has invalid parameters.

‍

Call Recordings (Recording Files)

Users can record incoming and/or outgoing calls. Requires a valid call recording plan.

‍

Get Recording Records

Fetches call recording logs.

Endpoint: POST /callrecordings/getrecordings

‍

Request Parameters

  • Lang — ISO 639-1 language code. Data Type: String. Default: en
  • StartDate — Start date filter. Data Type: String. Default Value: Empty. Format: UTC DateTime.
  • EndDate — End date filter. Data Type: String. Default Value: Empty. Format: UTC DateTime. Must not be more than 5 days from StartDate.

‍

Request Header Example

Content-Type: application/json
X-iPlumAuth-AccessKey: ABCD1234ACCESSKEY
X-iPlumAuth-Username: test@testuser.com
X-iPlumAuth-Version: v1
X-iPlumAuth-EpochDateTime: 1696387193
Authorization: iPlumAuth w5VKuiMqd38g53ksT8xBuoShgu0Xj1NfXx8WHoDCG3A=

‍

Request Body Example

{"Lang":"en", "StartDate":"2023-03-20 02:23:06.000", "EndDate":"2023-03-24 02:23:06.000"}

‍

Response Fields

  • source — Source of the recording record. Data Type: String. Value: iPlum
  • clientReferenceId — Custom value set on the account. Data Type: String.
  • recordId — Unique record ID. Data Type: String.
  • phonenumber — Phone number of the called/calling party. Data Type: String.
  • dateTimeUTC — Date and time of recording (UTC). Data Type: String.
  • duration — Duration of the recording in minutes. Data Type: String.
  • length — File size in KB or MB. Data Type: String.
  • direction — Direction of the call. Values: in, out. Data Type: String.
  • userId — iPlum user to which the recording belongs. Data Type: String.

‍

Response Example

[{"source":"iPlum", "clientReferenceId":"1234", "recordId":"ae0b4e3e-76c0-46d2-8bab-18c8764081dbgjdi2j", "phonenumber":"+14081231234", "dateTimeUTC":"2023-03-22T00:24:00Z", "duration":"3", "direction":"in", "length":"434.2 KB", "userId":"test@test.com"}]

‍

Error Codes

  • ERR_INVALID_DATE — The end date must not be later than 5 days from the start date.
  • ERR_INVALID_REQUEST — Request has invalid parameters.

‍

Get Recording File

Fetches the recording file for a given record.

Endpoint: POST /callrecordings/getrecordingfile

‍

Request Parameters

  • Lang — ISO 639-1 language code. Data Type: String. Default: en
  • RecordID — Call recording record ID. Data Type: String.

‍

Request Header Example

Content-Type: application/json
X-iPlumAuth-AccessKey: ABCD1234ACCESSKEY
X-iPlumAuth-Username: test@testuser.com
X-iPlumAuth-Version: v1
X-iPlumAuth-EpochDateTime: 1696387235
Authorization: iPlumAuth XMFT4svyRWjm/wwK+FfQjEo24jJpMpt99Uv7fs2PN10=

‍

Request Body Example

{"Lang":"en", "RecordID":"ae0b4e3e-76c0-46d2-8bab-18c8764081dbgjdi2j"}

‍

Response

Returns a URL string for the .mp3 recording file.

Example: http://media.iplum.com/ae0b4e3e-76c0-46d2-8bab-18c8764081db.mp3

‍

Error Codes

  • ERR_INVALID_REQUEST — Request has invalid parameters.

‍

‍

Callbacks

Real-time, event-driven notifications sent to a URI configured during API account setup.

‍

Usage Callbacks (Call, Text, Fax Logs)

Subscribe to notifications for call, text, and/or fax events. A usage record is pushed to your configured URI when an event occurs.

‍

Callback Response Fields

  • source — Value: iPlum. Data Type: String.
  • clientReferenceId — Custom value set on the account. Data Type: String.
  • recordId — Unique usage record ID. Data Type: String.
  • usage — Values: call, text, fax. Data Type: String.
  • type — Values: iplum, external. Data Type: String.
  • from — From number. Data Type: String.
  • to — To number. Data Type: String.
  • startTimeUTC — Start time (UTC). Data Type: String.
  • endTimeUTC — End time (UTC). Data Type: String.
  • duration — Duration in minutes. For text, value is 1. Data Type: String.
  • direction — Values: in, out. Data Type: String.
  • content — Text content (if enabled and user has a valid plan). Data Type: String.
  • iPlumCredits — Credits used. Data Type: Integer.
  • userId — iPlum user to which the usage belongs. Data Type: String.

‍

Callback Example

{"source":"iPlum", "clientReferenceId":"1234", "usage":"text", "recordId":"0UmFAs73cwKbyqUtmz7ltLI.nGlAD.0Dgjdhpm", "from":"+14081231234", "to":"test@iplum.com", "startTimeUTC":"2023-03-24T00:00:00Z", "endTimeUTC":"2023-03-24T00:00:00Z", "duration":"1", "direction":"in", "type":"external", "content":"Hello", "iPlumCredits":1, "userId":"test@test.com"}

‍

Call Recording Callbacks (Recording Files)

Subscribe to notifications when a new call recording is available.

‍

Callback Response Fields

  • source — Value: iPlum. Data Type: String.
  • clientReferenceId — Custom value set on the account. Data Type: String.
  • recordId — Unique record ID. Data Type: String.
  • phonenumber — Phone number of the called/calling party. Data Type: String.
  • dateTimeUTC — Date and time of recording (UTC). Data Type: String.
  • duration — Duration in minutes. Data Type: String.
  • length — File size in KB or MB. Data Type: String.
  • direction — Values: in, out. Data Type: String.
  • content — Recording file URL (if enabled and user has a valid call recording plan). Data Type: String.
  • userId — iPlum user to which the recording belongs. Data Type: String.

‍

Callback Example

{"source":"iPlum", "clientReferenceId":"1234", "recordId":"ae0b4e3e-76c0-46d2-8bab-18c8764081dbgjdi2j", "phonenumber":"+14081231234", "dateTimeUTC":"2023-03-22T00:24:00Z", "duration":"3", "direction":"in", "length":"434.2 KB", "content":"http://media.iplum.com/ae0b4e3e-76c0-46d2-8bab-18c8764081db.mp3", "userId":"test@test.com"}

‍

Contact Us

For any questions, please submit a support ticket.

Thank you!
Your payment has been received and will be process!
Oops! Something went wrong while submitting the form.