Overview

This guide gives step by step instructions on how you can integrate miniOrange Group APIs with your system.

Table Of Contents

  • Step 1: Create Authentication Header
  • Step 2: API Details

Pre-requisites

  • 1 You need to create a free trial account with miniOrange.
  • Login to our console and Click on the Settings provided on the right top corner of the console and Copy your Api Key and add it in request headers.

Step 1: Create Authentication Header

To be able to call our challenge and validate Rest APIs, you will need to set the authorization headers required to make sure that the request being made is by a valid user. You can check the sample JAVA and PHP code below to get an idea on how you can create the authorization headers.

The following values need to be set in the Header of the HTTP Request being made.

Attribute Description
Customer-Key Your customer key.
Api-Key Your Api Key
Timestamp The time in milliseconds when the request is being made
Authorization Sha 512 Hash Value consisting of the customer key , current timestamp and api key.

You can get your Customer-Key and Api Key by following these steps:

  • Log in to your Admin Dashboard.
  • Go to System Settings from the top right corner. You will find all of your information under the Account Details section.

Sample Code

  • Java
  • PHP
        /* You can get customer Key and customer Api Key from your admin dashboard */
        String customerKey = "<YOUR_CUSTOMER_KEY>";
        String apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
        /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
        String stringToHash = customerKey + currentTimeInMillis + apiKey;
        String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
        HttpPost postRequest = new HttpPost("<URL for calling API>");
        /* Setting the Authorization Header values */
        postRequest.setHeader("Customer-Key", customerKey);
        postRequest.setHeader("Timestamp", currentTimeInMillis);
        postRequest.setHeader("Authorization", hashValue)
        /* You can get customer Key and customer Api Key from your admin dashboard*/
        $customerKey = "<YOUR_CUSTOMER_KEY>";
        $apiKey = "<YOUR_API_KEY>";
        /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
        $currentTimeInMillis = round(microtime(true) * 1000);
        /* Creating the Hash using SHA-512 algorithm */
        $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey;
        $hashValue = hash("sha512", $stringToHash);
        /* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the httpheader */
        $customerKeyHeader = "Customer-Key: " . $customerKey;
        $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' );
        $authorizationHeader = "Authorization: " . $hashValue;

Step 2: API Details

Get All Groups

EndPoint: https://<base-url>/api/admin/groups/getall

This endpoint is used by admins to fetch all groups under him. All groups configured by the Administrator will be fetched in batches and a maximum of 500 group details can be fetched in 1 call. You will have to call this endPoint multiple times till you have fetched all of the groups.

The following JSON date which needs to be passed in the request:

        /* JSON Object format which will be sent for fetching all groups*/
        {
          "customerKey": "<ADMIN_KEY>",
          "requestCustomerId": "<ADMIN_KEY>"
          "batchSize": <BATCH_SIZE>,
          "batchNo": <BATCH_NO>
        }
Attribute Description
customerKey* / requestCustomerId Your customer key.
batchSize This denotes the maximum number of members that needs to be sent back in the response
groupName* Name of the group whose members need to be fetched
batchNo The batch number to fetch members in batches. You can increment this by 1 each time you are fetching 500 members. If the response from the server has batch number as -1 then that means there are no more members to be fetched.

In response you will sent a list of members associated with the group and their details as JSON data. Here’s an example :

        {
            "customerId": "<ADMIN_KEY>",
            "status": "SUCCESS",
            "message": "Groups retrieved successfully.",
            "groupDetails": [{
            "primaryEmail": "<EMAIL>",
            "groupName": "<GROUP_NAME>",
            "username": "<USERNAME>"
               }],
            "fetchedCount": 1,
            "nextBatch": -1
        }
  • customerId: ID of the Admin
  • status: SUCCESS or FAILED indicating if the operation was successful.
  • message: Message from the Server
  • groupDetails: List of all Members. A member can have the following information:
    • primaryEmail:Email of the member
    • username: Username of the member
    • groupName: Name of the Group

Update Groups

EndPoint: https://<base-url>/api/admin/groups/update

This endpoint is used by admins to update group details and attributes

The following JSON date which needs to be passed in the request:


        /* JSON Object format which will be sent for updating multiple groups*/
        {
          "customerKey": "<ADMIN_KEY>",
          "requestCustomerId": "<ADMIN_KEY>",
          "groups": [{
              "groupName": "<GROUP_NAME>",
            "customerId": "<ADMIN_KEY>",
            "isDefault": "<TRUE_OR_FALSE>",
            "groupAttribute1": "<GROUP_ATTR>",
            .
            .
            "groupAttribute50": "GROUP_ATTR"
           }]
        }

Attribute and description.

  • customerKey* / request: CustomerId Your customer key.
  • groups* : List of all the Groups and their details to be updated. You can update the following attributes:
    • groupName* : Name of the Group
    • customerId* : Admin CustomerId
    • isDefault* : True or False
    • GroupAttribute1 - GroupAttribute50 : String values denoting group attributes. You can have a maximum of 50 Group Attributes.

In response you will be sent a JSON response. Here’s an example :

          {
           "customerId": "<ADMIN_KEY>",
           "status": "SUCCESS",
           "message": "Groups updated successfully.”
          }

Update Member of a Group

EndPoint: https://<base-url>/api/admin/groups/update

This endpoint is used by admins to add or remove users from groups.

The following JSON date which needs to be passed in the request:

        /* JSON Object format which will be sent for assigning users and groups */
        {
          "customerKey": "<ADMIN_KEY>",
          "requestCustomerId": "<ADMIN_KEY>",
          "groupName": "<NAME_OF_THE_GROUP>",
          "users": [{
              "groupName": "<GROUP_NAME>",
            "userAction": "<ADD_OR_REMOVE>",
            "primaryEmail": "<EMAIL>",
            "customAttribute1": "<EMAIL>"
           }]
        }

Attribute and Description.

  • customerKey* / request : CustomerId Your customer key.

  • users* : List of all the Groups and their details to be updated. You can update the following attributes:

      - groupName* :  Name of the Group
      - userAction* : Add or Remove
      - primaryEmail* : Email of the user to add to group
      - customAttribute1* : Email of the user to add to group

In response you will be sent. Here’s an example :

        {
         "customerId": "<ADMIN_KEY>",
         "status": "SUCCESS",
         "message": "Groups updated successfully.”
        }