Guides

Quickstart - Platform API Management

Create a business, add a subscription, add a staff

Welcome to the Quickstart guide for integrating with inTandem's business management platform. This page is your comprehensive resource for connecting your services with our platform. This guide teaches you the essential steps to authenticate, create business and admin user accounts, manage subscriptions, and add staff.

Aimed at partners looking to streamline client account management.

This guide also includes practical Node.js code samples to jumpstart your integration process.

download complete code>>.

Step 1: Get a Directory Token

Get your directory token

In the inTandem platform, partners manage their clients' business accounts across various environments known as Directories, such as Production, Sandbox, and Demo. Each Directory encapsulates a specific environment with inherited configurations like branding and partner domains. Each Directory has a unique authorization token required for API requests, enabling partners to create, manage, and access businesses registered under them.

This token, essential for utilizing the inTandem Development Hub's functionalities, ensures secure and tailored access to resources specific to each Directory.

To receive your unique token, please get in touch with us at [email protected] or contact your account manager in our partners team

learn more>>

Code Sample

const https = require('https');

function prepareRequestOptions(path, authToken, method = 'POST') {
  const hostname = 'api.vcita.biz'; 
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${authToken}`,
  };
  return {
    hostname,
    port: 443,
    path,
    method,
    headers,
  };
}
const path = '/platform/v1/businesses';
const authToken = 'your_directory_token_here';

// Prepare request options using the utility function
const options = prepareRequestOptions(path, authToken);

Step 2: Create a Business Account

Create an Admin User Object

First, you'll define the admin user object. This object includes the personal details necessary to create an admin account.

const admin={  
    "country_name": "United States",  
    "display_name": "DName",  
    "email": "[[email protected]](mailto:[email protected])",  
    "first_name": "FName",  
    "language": "en",  
    "last_name": "LName",  
    "phone": "+154863488",  
    "user_id": "11111"  
  };

Create a Business Object

Next, define the business object and meta info. This contains information about the business you're registering.

const business={  
    "business_category": "aeroclub",  
    "business_maturity_in_years": "0.5",  
    "country_name": "United States",  
    "id": "1a123b456c789",  
    "landing_page": "Homepage",  
    "name": "Business name",  
    "short_description": "My business description"  
  };
const businessMeta={  
    "auth_token": "a1a1a1a1a1",  
    "external_reference_id": "1213444", 
    "in_setup": "true",  
    "intents": [  
      "accept_payments_tile",  
      "documents_and_forms"  
    ],  
    "is_template": "false"
  };

Create a Business Account Using the API

Finally, you'll request the API to create the business account. 


// Define your payload here  
const data = JSON.stringify({  
  "admin_account": admin,  
  "business": business,
  "meta": businessMeta
});

function createBusiness(options, data, callback) {
  // Stringify the data for the HTTP request body
  const stringifiedData = JSON.stringify(data);

  // Ensure Content-Length is set correctly for the stringified data
  options.headers['Content-Length'] = Buffer.byteLength(stringifiedData);

  // Create the HTTPS request
  const req = https.request(options, (res) => {
    let rawData = '';

    // Accumulate data chunks received from the response
    res.on('data', (chunk) => {
      rawData += chunk;
    });

    // Handle the end of the response
    res.on('end', () => {
      try {
        // Parse the raw data collected from the response
        const parsedData = JSON.parse(rawData);
        // Extract the business ID from the parsed response data
        const buid = parsedData.data.business.id;
        // Invoke the callback with null error and the business ID
        callback(null, buid);
      } catch (error) {
        // If parsing fails, invoke the callback with the error
        callback(error, null);
      }
    });
  });

  // Handle request errors (e.g., network issues)
  req.on('error', (error) => {
    // Invoke the callback with the encountered error
    callback(error, null);
  });

  // Write the stringified data to the request body
  req.write(stringifiedData);
  // End the request, sending it off
  req.end();
}

// Create the business
createBusiness(options, data, (error, buid) => {
  if (error) {
    console.error("Error creating business account:", error);
    return;
  }

  console.log("Successfully created business account. Business ID:", buid);
  // You can use the business ID for further operations here
});

Your return response should look like this:

{
  "data": {
    "admin_account": {
      "country_name": "United States",
      "display_name": "DName",
      "email": "[email protected]",
      "first_name": "FName",
      "language": "en",
      "last_name": "LName",
      "phone": "+154863488",
      "user_id": "11111"
    },
    "business": {
      "business_category": "aeroclub",
      "business_maturity_in_years": "0.5",
      "country_name": "United States",
      "id": "1a123b456c789",
      "landing_page": "Homepage",
      "name": "Business name",
      "short_description": "My business description"
    },
    "integrations": {},
    "meta": {
      "auth_token": "a1a1a1a1a1",
      "external_id": "1213444",
      "external_reference_id": "1213444",
      "identities": [
        "aaa123",
        "bbb345",
        "1a3c4f4h"
      ],
      "in_setup": "false",
      "intents": [
        "accept_payments_tile",
        "documents_and_forms"
      ],
      "is_template": "true",
      "marketing_channel": "Client Channel",
      "note": "Client Note",
      "plan": {
        "expires_on": "2022-06-14T09:31:21.000",
        "external_subscription_params": "***",
        "plan_name": "Essential"
      },
      "tags": "Client tag1, Client tag2"
    }
  },
  "status": "OK"
}

📘

Note:

Replace the payload data with your specific business and admin account details as necessary.

This script uses Node.js's https module to send a POST request to the API, creating a new business account with the provided details.

Step 3: Create a Subscription

Get the business_UID from the returned object

Extract the business_uid from the return response as demonstrated above.

Choose a subscription plan

During setup, the professional services team will create purchasable codes you can use based on the commercial agreements. Each purchasable_price_uid reflects a specific set of licenses, including the price, bundled app, charging frequency (Monthly/Annual), etc. Specifying the purchasable_price_uid is enough for inTandem to open the license for the business account with all the derived functionality for the users.

read more>>

Create a subscription using the API

Use the /business/v1/subscriptionmng/subscriptions endpoint to create a subscription

Code Sample

// Create the business account
createBusiness(options, data, (error, buid) => {
  if (error) {
    console.error("Error creating business account:", error);
    return;
  }

  console.log("Successfully created business account. Business UID:", buid);

  // You can use the business ID for further operations here
   const businessUid=buid;
   const purchasablePriceUid='a_purchasable_price_uid'
   createBusinessSubscription(businessUid,purchasablePriceUid,authToken,(error, subuid)=> {
      if (error) {
        console.error("Error creating subscription:", error);
        return;
  		}

  		console.log("Successfully created subscription. Subscription UID:", subuid);
   });
});

function createBusinessSubscription(businessUid, purchasablePriceUid, authToken, callback) {
  // Define the request body data
  const data = JSON.stringify({
    "business_uid": businessUid,
    "subscription": {
      "purchasable_price_uid": purchasablePriceUid
    }
  });

  // Prepare the request options using the utility function
  const options = prepareRequestOptions('/business/subscriptionsmng/v1/subscriptions', authToken, 'POST');
  // Ensure the 'Content-Length' header is correctly set
  options.headers['Content-Length'] = Buffer.byteLength(data);

  // Create and send the HTTPS request
  const req = https.request(options, (res) => {
    let rawData = '';

    // Collect response data
    res.on('data', (chunk) => rawData += chunk);

    // Process the response once fully received
    res.on('end', () => {
      try {
        const parsedData = JSON.parse(rawData);
        callback(null, parsedData); // Invoke callback with the parsed response data
      } catch (error) {
        callback(error, null); // Handle parsing errors
      }
    });
  });

  req.on('error', (error) => callback(error, null)); // Handle request errors

  // Write the request body and close the request
  req.write(data);
  req.end();
}

Step 4: Get a Business Token

Use your directory token to get a business token

const authToken = 'your_directory_token_here';
function getBusinessToken(authToken, callback) {
  // Use the utility function to prepare request options
  const options = prepareRequestOptions('/platform/v1/tokens', authToken, 'GET');

  // Make the HTTPS request with the dynamically prepared options
  const req = https.request(options, (res) => {
    let rawData = '';

    res.on('data', (chunk) => {
      rawData += chunk;
    });

    res.on('end', () => {
      try {
        const parsedData = JSON.parse(rawData);
        if (parsedData.status === 'OK' && parsedData.data.tokens.length > 0) {
          const token = parsedData.data.tokens[0].token; // Assuming you want the first token
          callback(null, token);
        } else {
          callback(new Error('No tokens found or bad response'), null);
        }
      } catch (e) {
        callback(e, null);
      }
    });
  });

  req.on('error', (e) => {
    callback(e, null);
  });
}
getBusinessToken(authToken, (error, token) => {
  if (error) {
    console.error('Failed to get business token:', error);
    return;
  }
  console.log('Retrieved Business Token:', token);
  const businessToken=token
});

read more>>

Step 5: Add staff to the business

Add your business token to the header

const businessToken=token
let path='platform/v1/businesses/'+businessUid +'/staffs';
const options = prepareRequestOptions(path, businessToken, 'POST');

Create a staff object

const staffArray = JSON.stringify([
      {
        "active": "true",
        "deleted": "false",
        "display_name": "My Display Name",
        "email": "[email protected]",
        "first_name": "First Name",
        "id": "somerandomuniqueid",
        "invite_sent": "2015-10-23 13:02:09",
        "last_name": "Last Name",
        "mobile_number": "0500000001",
        "photo": "https://c15101458.ssl.cf2.rackcdn.com/avatar/image/46/cay8ek2xzufnr39cbrc0nebw1tmy4v2z.png",
        "professional_title": "My Professional Title",
        "role": "user"
      }
    ]);

Create a staff using the API


function createStaff(options, callback) {
  // Use the utility function to prepare request options

  // Make the HTTPS request with the dynamically prepared options
  const req = https.request(options, (res) => {
    let rawData = '';

    res.on('data', (chunk) => {
      rawData += chunk;
    });

    res.on('end', () => {
      try {
        const parsedData = JSON.parse(rawData);
        if (parsedData.status === 'OK' && parsedData.data.tokens.length > 0) {
          const staff = parsedData.data.staff[0]; // Assuming you want the first token
          callback(null, staff);
        } else {
          callback(new Error('No tokens found or bad response'), null);
        }
      } catch (e) {
        callback(e, null);
      }
    });
  });

  req.on('error', (e) => {
    callback(e, null);
  });
}

createStaff(options,(error, staff) => {
  if (error) {
    console.error('Failed to create staff:', error);
    return;
  }
  console.log('Staff Created:', staff);
});


Updated 8 months ago