User Management API

Overview

With the User Management API you can perform registration operations such as signing up, logging in, and other profile configurations.

This page will go over the common endpoints associated with user management.

Learn more about User Profiles with our Help Center articles.

Authentication

Use the following header parameters for all requests:

Headers
`Authentication` string required	Authentication bearer token See Authentication Guide
`X-IAA-OW-ID` integer required	Organization Workspace ID Header

Send User Invitation

POST /api/v3/ua/user/invite

Any Customer or Organization can send invitations to one or more users by providing their names and emails.

Request Schema
`email` string	User's email
`name` string	User's name

Response Properties

`success` boolean	Indicates invite was succesfully sent: `true`
`data` string	Success message

JSON
TypeScript

Request Sample
{
  "email": "shraddha.p@iqm.com",
  "name": "Shradda Patel"
}

Response 200
{
  "success": true,
  "data": "1 invitations sent successfully."
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: string;
      };
    };
  };
};

function SendUserInvitations(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/user/invite',
    requestBody: {
      content: {
        "application/json": [
          {
            email: `string`,
            name: `string`,
          }
        ]
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Validate User Invite

POST /api/v3/ua/invite/validate

The invited user will receive an email with a link and a hash which can be validated.

Request Schema
`inviteHash` string	Unique invite hash sent to invited user

Response Properties

isExpired
boolean Indicates invite hash is expired: true

JSON
TypeScript

Request Sample
{
    "inviteHash": "8HQfsQcychjhvCmuuiFvVCIgqq9cJG/gh6HgmPZXxGE4od7a7tsMmh/O9+ia2Lw0FOelX3h8jTKJXR+0hUAkGXYA0cIITS13BxyrWoeBmRTnWTKxHtS+Ff41POwt/yDMY2iHXUsG86ehmWeeIi3HNMikhH5yY6BvNFnEfxq3zIdiouD3Fp/loPO9qazxU1qxZvNOOv8FZEZTzORVnJ8+ADjyZ/Zjs1dNhSFE"
}

Response 200
{
  "success": true,
  "data": {
    "isExpired": true
  }
}

More Responses

Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Provided invitation has is incorrect.",
      "field": "inviteHash"
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          isExpired: boolean;
        };
      };
    };
  };
  422: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
          field: string;
        }[];
      };
    };
  };
};

function ValidateInvite(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/invite/validate',
    requestBody: {
      content: {
        "application/json": {
          inviteHash: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

POST /api/v3/ua/sign-up

A user/Customer can sign up and create a password to access the API.

Request Schema
`email` string	User's email
`password` string	User's password

Response Properties

`success` boolean	Indicates user was succesfully signed up: `true`
`access_token` string	Access token
`refresh_token` string	Refresh token
`scope` string	User access rights
`token_type` string	Token type
`expires_in` integer	Time until token expires

JSON
TypeScript

Request Sample
{
    "email": "kartik.g@iqm.com",
    "password": "123456"
}

Response 200
{
  "success": true,
  "data": {
    "access_token": "d90fa7de-534c-4652-ad8f-c4f6f70461ac",
    "refresh_token": "2e379c6f-959d-498f-8319-ff13ebef6bfe",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999
  }
}

More Responses

Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "User is not allowed to create a password.",
      "reason": "User is not invited or invitation is processed or invitation is expired."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          access_token: string;
          refresh_token: string;
          scope: string;
          token_type: string;

          expires_in: number;
        };
      };
    };
  };
  403: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
          reason: string;
        }[];
      };
    };
  };
};

function UserSign-up/PasswordCreation(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/sign-up',
    requestBody: {
      content: {
        "application/json": {
          email: `string`,
          password: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

POST /api/v3/ua/login

Once the user/Customer logs in, the API will send an OAuth compliant response with OW ID which can be used for further API communications.

Request Schema
`grantType` string	OAuth Grant Types
`email` string	User's email
`password` string	User's password

Response Properties

`success` boolean	Indicates user succesfully logged in: `true`
`access_token` string	Access token
`refresh_token` string	Refresh token
`scope` string	User access rights
`token_type` string	Token type
`expires_in` integer	Time until token expires
`owId` integer	Organization Workspace ID

JSON
TypeScript

Request Sample
{
  "grantType": "password",
  "email": "pratik.t+ihp@iqm.com",
  "password": "123456"
}

Response 200
{
  "success": true,
  "data": {
    "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
    "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999,
    "owId": 200001
  }
}

More Responses

Response 400
{
  "success": false,
  "data": {
    "status": "On Hold",
    "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
    "supportEmail": "support@iqm.com"
  },
  "errorObjects": [
    {
      "error": "User is not allowed to access provided customer",
      "reason": "User is not associated with any active organization."
    }
  ]
}

Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "User doesn't exist or user is not allowed to provided workspace."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          access_token: string;
          refresh_token: string;
          scope: string;
          token_type: string;

          expires_in: number;

          owId: number;
        };
      };
    };
  };
  400: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          status: string;
          reason: string;
          supportEmail: string;
        };
        errorObjects: {
          error: string;
          reason: string;
        }[];
      };
    };
  };
  403: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function Login(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/login',
    requestBody: {
      content: {
        "application/json": {
          grantType: `string`,
          email: `string`,
          password: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Refresh Token

POST api/v3/ua/oauth/token

Exchange a refresh token for a new access token.

Request Parameters
`grantType` string	OAuth Grant Types
`refresh_token` string	Refresh token

Request Sample
{
  "grant_type": "refresh_token",
  "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64"
}

Response 200
{
  "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
  "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
  "scope": "read write",
  "token_type": "bearer",
  "expires_in": 35999
}

User Logout

POST /api/v3/ua/logout

Log a user out from the API.

Response Properties

`success` boolean	Indicates user succesfully logged out: `true`
`data` string	Success message

JSON
TypeScript

Response 200
{
  "success": true,
  "data": "User logged out successfully."
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string;
      };
    };
  };
};

function Logout(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/logout',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Change Password

POST /api/v3/ua/user/update-password

Update a user's password.

Request Schema
`email` string	User's email
`password` string	User's password

Response Properties

`success` boolean	Indicates user's password was succesfully updated: `true`
`data` string	Success message

JSON
TypeScript

Request Sample
{
  "email": "kartik.g@iqm.com",
  "password": "123456"
}

Response 200
{
  "success": true,
  "data": "Password changed successfully."
}

More Responses

Response 403
{
  "success": true,
  "data": {
    "invalidReason": "Reset password link either not valid or it is already processed.",
    "isValid": false
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: string;
      };
    };
  };
  403: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          invalidReason: string;
          isValid: boolean;
        };
      };
    };
  };
};

function UpdatePassword(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/user/update-password',
    requestBody: {
      content: {
        "application/json": {
          email: `string`,
          password: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Reset Password Email

POST /api/v3/ua/user/reset-password

Send a link to reset a user's password to a specified email.

Request Schema
`email` string	User's email

Response Properties

`success` boolean	Indicates reset link was succesfully sent: `true`
`data` string	Success message

JSON
TypeScript

Request Sample
{
  "email": "kartik@iqm.com"
}

Response 200

{
  "success": true,
  "data": "Email with reset password link sent successfully."
}

More Responses

Response 404
{
  "success": false,
  "errorObjects": [
    {
      "error": "The email is not available in the system."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: string;
      };
    };
  };
  404: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function ResetPasswordEmail(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/user/reset-password',
    requestBody: {
      content: {
        "application/json": {
          email: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Update User Profile

PATCH /api/v3/ua/user/update-profile

Update a user's profile display name and avatar.

Request Schema
`displayName` string	User Name
`userAvatar` string	If `removeUserProfile` set to `true`, can remain null, otherwise: Image file uploaded for profile
`removeUserProfile` boolean	default: `false` To remove profile image `true`

Response Properties

`success` boolean	Indicates user's profile was succesfully updated: `true`
`userAvater` string	User avatar
`message` string	Success message

JSON
TypeScript

Response 200
{
    "success": true,
    "data": {
        "userAvatar": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/user-profile/444.jpg",
        "message": "Profile updated successfully."
    }
}

More Responses

Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "Profile image should not be more than 3 MB"
        }
    ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          userAvatar: string;
          message: string;
        };
      };
    };
  };

  422: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function UpdateUserProfile(): Promise < Responses > {
  const options = {
    method: 'PATCH',
    url: 'https://app.iqm.com/api/v3/ua/user/update-profile',
    requestBody?: {
      content: {
        "application/x-www-form-urlencoded": {
          displayName: `string`,
          userAvatar: `string`,
          removeUserProfile: `boolean`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get User Profile Details

GET /api/v3/ua/profile

Get user profile details and parent organization hierarchy.

Resource Properties

uowId
integer User Organization Workspace ID

status
string User's status

invoiceId
integer User's invoice ID

firstName
string User's first name

lastName
string User's last name

displayName
string User's display name

userAvatar
string Image file uploaded for profile

email
string User's email

organizationName
string Organization associated with user

organizationLogo
string Organization associated with user

isOwnerUser
boolean Indicates user is owner: true

isPlatformOwnerOrg
boolean Indicates user is platform owner (super user): true

isWorkspaceOwnerOrg
boolean Indicates user is owner (Workspace user): true

isCampaignAppOwner
boolean Indicates user is owner of Campaign App (super user): true

isBetaUser
boolean Indicates user is beta user: true

allowExtendedReportDuration
integer

parentOrganization
object Parent Organization details

parentOrganization object properties

`owId` integer	Organization Workspace ID
`organizationName` string	Organization associated with user
`workspaceDomain` string	Workspace domain
`isAccess` boolean	Indicates logged-in user has Customer management access of given Customer Organization: `true`
`parentOrganization` object	Parent Organization details

organizationTimezone
integer Organization timezone

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "owId": 200002,
    "status": 1,
    "invoiceId": 283,
    "firstName": "your first name",
    "lastName": "1",
    "displayName": "display Name",
    "userAvatar": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/user-profile/1/1651537740179.jpg",
    "email": "yourEmail@yahoo.com",
    "organizationName": "AdAgency 1",
    "organizationLogo": "https://d3jme5si7t6llb.cloudfront.net/logo/iqm.png",
    "isOwnerUser": false,
    "isPlatformOwnerOrg": false,
    "isWorkspaceOwnerOrg": true,
    "isCampaignAppOwner": false,
    "isBetaUser": true,
    "allowExtendedReportDuration": 1,
    "parentOrganization": {
      "owId": 200001,
      "organizationName": "AdAgency 2",
      "workspaceDomain": "yourDomain.com",
      "isAccess": true
    },
    "organizationTimezone": 29
  }
}

See TypeScript Prerequisites for usage.

Get List of Users

GET /api/v3/ua/users/list

Get a list of users and details for a given workspace ID.

Query Parameters

`status` string	Status of user
`searchField` string	Search results by keyword
`limit` integer	Maximum number of entries returned, default: `10`
`pageNo` integer	Page number for the data, default: `1`
`sortBy` string	Sorts by ascending (`+`) or descending (`-`), default: `+displayName`

Resource Properties

`userId` integer	Unique user ID
`firstName` string	User's first name
`lastName` string	User's last name
`email` string	User's email
`displayName` string	User's display name
`status` string	User's status
`statusId` integer	Status ID
`userAvatar` string	Image file uploaded for profile
`createdAt` integer	Unix timestamp in Milliseconds when account was created
`uowId` integer	User Organization Workspace ID
`customersCount` integer	Count of Customers assigned to user
`organizationName` string	Organization associated with user
`invitedOn` integer	Unix timestamp in Milliseconds when user was invited to create account
`isOrganizationOwnerUser` boolean	User is owner of Organization (`true`) or not (`false`)
`isModificationAllowed` boolean	User is allowed to modify (`true`) or not (`false`)
`invitedByUserName` string	Name of user that invited user
`invitedByUserEmail` string	Email of user that invited user
`isAssignActionAllowed` boolean	User is allowed to assign (`true`) or not (`false`)

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "userId": 7130,
        "firstName": "sample adv user -2",
        "lastName": "2",
        "email": "sample-user@iqm.com",
        "displayName": "sample adv user - 2",
        "status": "active",
        "statusId": 1,
        "userAvatar": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/K2.png",
        "createdAt": 1705452608000,
        "uowId": 119592,
        "customersCount": 0,
        "organizationName": "Adv Acc 1",
        "invitedOn": 1705452608000,
        "isOrganizationOwnerUser": false,
        "isModificationAllowed": true,
        "invitedByUserName": "User 2",
        "invitedByUserEmail": "user2@iqm.com",
        "isAssignActionAllowed": true
      },
      {
        "userId": 7131,
        "firstName": "sample-adv-user-3",
        "email": "sample-user1@iqm.com",
        "displayName": "sample-adv-user-3",
        "status": "invited",
        "statusId": 3,
        "userAvatar": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/KH.png",
        "createdAt": 1705466349000,
        "uowId": 119595,
        "customersCount": 0,
        "organizationName": " Adv Acc",
        "invitedOn": 1705466349000,
        "isOrganizationOwnerUser": false,
        "isModificationAllowed": true,
        "invitedByUserName": "User 1",
        "invitedByUserEmail": "user1@iqm.com",
        "isAssignActionAllowed": true
      },
    ],
    "totalRecords": 6,
    "filteredRecords": 2
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            userId: number;
            firstName: string;
            lastName: string;
            email: string;
            displayName: string;
            status: string;
            statusId: string;
            userAvatar: string;
            createdAt: number;
            uowId: number;
            customersCount: number;
            organizationName: string;
            invitedOn: number;
            isOrganizationOwnerUser: boolean;
            isModificationAllowed: boolean;
            invitedByUserName: string;
            invitedByUserEmail: string;
            isAssignActionAllowed: boolean;
          }[];
          totalRecords: number;
          filteredRecords: number;
        }
      }
    };
  };
};

function getUsersList(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ua/users/list',
    params: {
      query?: {
        status?: `string`,
        pageNo?: `number`,
        limit?: `number`,
        sortBy?: `string`,
        searchField?: `string`,
      },
    },
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

User App Access List

GET /api/v3/ua/user/applications/list

See what applications a user has access to, use query parameters to filter results.

Query Parameters
`uowId` integer	User Organization Workspace ID
`searchField` string	Search results by keyword
`limit` integer	Maximum number of entries returned, default: `10`
`pageNo` integer	Page number for the data, default: `1`
`sortBy` string	Sorts by ascending (`+`) or descending (`-`), default: `+appName`

Response Properties

`success` boolean	Indicates app access was succesfully retrieved: `true`
`appId` integer	Bundle ID for app request
`appName` string	App name
`appOwner` string	App owner
`appType` string	App type

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "appId": 7,
        "appName": "Campaigns",
        "appOwner": "IQM Corporation",
        "appType": "Default App"
      },
      {
        "appId": 11,
        "appName": "Conversions",
        "appOwner": "IQM Corporation",
        "appType": "Default App"
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }  
}

More Responses

Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid sortBy value."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            appId: number;
            appName: string;
            appOwner: string;
            appType: string;
          }[];
          totalRecords: number;
          filteredRecords: number;
        };
      };
    };
  };
  422: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function GetUserApplicationaccesslist(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ua/user/applications/list',
    params: {
      query?: {
        uowId?: `number`,
        pageNo?: `number`,
        limit?: `number`,
        sortBy?: `string`,
        searchField?: `string`,
      },
    },
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Add App Access for User

POST /api/v3/ua/user/application/add

Grant a user access to specified apps.

Request Schema
`userID` integer	User's ID
`appIds` string	Application ID
`accessLevel` string	Level of access granted to user

Response Properties

`success` boolean	Indicates access was succesfully granted: `true`
`data` string	Success message

JSON
TypeScript

Request Sample
{
  "userId": 431,
  "appIds": "1",
  "accessLevel": "Full"
}

Response 200
{
  "success": true,
  "data": "Application access added successfully."
}

More Responses

Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "User doesn't exist or user is not part of the Organization."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: string;
      };
    };
  };
  403: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function AddAppaccessforUser(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/user/application/add',
    requestBody: {
      content: {
        "application/json": {
          userId: `number`,
          appIds: `string`,
          accessLevel: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Overview​

Authentication​

Send User Invitation​

Validate User Invite​

User Sign-Up​

Login​

Refresh Token​

User Logout​

Change Password​

Reset Password Email​

Update User Profile​

Get User Profile Details​

Get List of Users​

User App Access List​

Add App Access for User​

Overview

Authentication

Send User Invitation

Validate User Invite

User Sign-Up

Login

Refresh Token

User Logout

Change Password

Reset Password Email

Update User Profile

Get User Profile Details

Get List of Users

User App Access List

Add App Access for User