Skip to main content

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 or Client ID and Secret
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header

User Details​

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)
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
  }
}

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
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
  }
}

User Config Details​

GET /api/v3/ua/user/config

Get user configuration details for the current user.

Resource Properties
marginAccess
boolean		Indicates if the user has access to margin trading: true
Response 200
{
  "success": true,
  "data": {
    "marginAccess": true
  }
}

User Management​

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
Request Sample
{
  "email": "shraddha.p@iqm.com",
  "name": "Shradda Patel"
}
Response 200
{
  "success": true,
  "data": "1 invitations sent successfully."
}

User Sign-Up​

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
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."
    }
  ]
}

Login​

POST /api/v3/ua/login

Log in to the IQM platform with your email and password, and grant type set to password.

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
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."
    }
  ]
}

OAuth Token​

POST api/v3/ua/oauth/token

This endpoint functions as the main authenticator for external connections.

This API accepts a URL encoded form with different grant types. This endpoint can be used to log in via user password, authorization code or client credentials, or it can be used to refresh an access token.

The API will send an OAuth Compliant Response, as seen in the example Response 200 on the right side column.

Authentication
Authentication
string required		Client ID and Client Secret
Content-Type
string required		application/x-www-form-urlencoded
Request Parameters
grantType
string		OAuth Grant Types:
authorization_code: log in with redirect URL and client ID and secret
password: log in with username and password
refresh_token: obtain a new access token
refresh_token
string		Refresh token to obtain new access token
email
string		User's email
password
string		User's password
client_id
string		Client ID
client_secret
string		Client secret
Request Sample (refresh token)
curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <Client ID/Client Secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=eac4c1f6-781e-4b04-baff-9c2e415d1f64'
Request Sample (password)
curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <Client ID/Client Secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=user@iqm.com' \
--data-urlencode 'password=<your password>'
Request Sample (auth code)
curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <Client ID/Client Secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>' \
--data-urlencode 'redirect_uri=http://iqm-authenticator.stage.iqm/showAuthCode'
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
Response 200
{
  "success": true,
  "data": "User logged out successfully."
}

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
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
  }
}

Reset User Password​

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

Reset your password directly with this endpoint.

Request Schema
oldPassword
string		User's old password
newPassword
string		User's new password
Response Properties
success
boolean		Indicates reset link was succesfully sent: true
data
string		Success message
Request Sample
{
  "oldPassword": "123456",
  "newPassword": "123456789"
}
Response 200
{
  "success": true,
  "data": "Password reset successfully."
}

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
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."
    }
  ]
}

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
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"
        }
    ]
}

Update User Status​

PUT /api/v3/ua/user/update-status

Update a user's status.

Request Schema
uowIdinteger
statusinteger
statusReasonstring
Response Properties
success
boolean		Indicates if the status was updated successfully
message
string		Success message
Request Sample
{
  "uowId": 166,
  "status": 4,
  "statusReason": "Payment overdue for last 3 months"
}

```json title="Response 200"
{
    "success": true,
    "data": "User status updated successfully."
}

User Application Access​

Allowed Applications List​

GET /api/v3/ua/user/allowed-applications

Get a list of all applications a user can be granted access to.

Response Properties
appId
integer		Bundle ID for app request
appName
string		App name
appIcon
string		App icon URL
appUrl
string		App URL
Response 200
{
    "success": true,
    "data": [
        {
            "appId": 2,
            "appName": "Dashboard",
            "appIcon": "logo/dashboard.png",
            "appUrl": "/dashboard"
        },
        {
            "appId": 7,
            "appName": "Campaigns",
            "appIcon": "logo/campaigns.png",
            "appUrl": "/campaigns"
        },
        {
            "appId": 9,
            "appName": "Creatives",
            "appIcon": "logo/creatives.png",
            "appUrl": "/creatives"
        },
        {
            "appId": 8,
            "appName": "Audiences",
            "appIcon": "logo/audiences.png",
            "appUrl": "/audiences"
        },
        {
            "appId": 10,
            "appName": "Inventory",
            "appIcon": "logo/inventory.png",
            "appUrl": "/inventory"
        },
        {
            "appId": 4,
            "appName": "Bid Model",
            "appIcon": "logo/bid-model.png",
            "appUrl": "/bidmodel"
        },
        {
            "appId": 3,
            "appName": "Reports",
            "appIcon": "logo/reports.png",
            "appUrl": "/reports"
        },
        {
            "appId": 5,
            "appName": "Organization",
            "appIcon": "logo/organization.png",
            "appUrl": "/organization"
        },
        {
            "appId": 6,
            "appName": "My Profile",
            "appIcon": "logo/my-profile.png",
            "appUrl": "/accounts"
        },
        {
            "appId": 17,
            "appName": "Insights",
            "appIcon": "logo/insights.png",
            "appUrl": "/insights"
        },
        {
            "appId": 19,
            "appName": "Planner",
            "appIcon": "logo/planner.png",
            "appUrl": "/planner"
        }
    ]
}

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
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."
    }
  ]
}

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
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."
    }
  ]
}

Revoke App Access for User​

DELETE /api/v3/ua/user/application/revoke

Revoke a user's access to specified apps.

Request Schema
owId
integer		User's Organization Workspace ID
appIds
string		Application ID
Request Sample
{
  "owId": 431,
  "appIds": "1"
}
Response 200
{
  "success": true,
  "data": "Application access revoked successfully."
}

Validations​

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
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"
    }
  ]
}

Validate Password Reset Hash​

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

Validate the password reset hash sent to a user's email.

Request Schema
resetHash
string		Unique reset hash sent to user
Response Properties
resetEmail
string		User's email
isValid
boolean		Indicates reset hash is valid: true
invalidReason
string		Reason why reset hash is invalid
Request Sample
{
  "resetHash": "8HQfsQcychjhvCmuuiFvVCIgqq9cJG/gh6HgmPZXxGE4od7a7tsMmh/O9+ia2Lw0FOelX3h8jTKJXR+0hUAkGXYA0cIITS13BxyrWoeBmRTnWTKxHtS+Ff41POwt/yDMY2iHXUsG86ehmWeeIi3HNMikhH5yY6BvNFnEfxq3zIdiouD3Fp/loPO9qazxU1qxZvNOOv8FZEZTzORVnJ8+ADjyZ/Zjs1dNhSFE"
}
Response 200
{
  "success": true,
  "data": {
    "resetEmail": "<user@example.com>",
    "isValid": true
  }
}

Validate User Email​

POST /api/v3/ua/user/email/validate

Check if a user's email is already registered.

Request Schema
email
string		User's email
workspaceDomain
string		Workspace domain associated with user
Response Properties
isValid
boolean		Indicates email is already registered: true
owId
integer		Organization Workspace ID associated with user
isWorkspaceAllowed
boolean		Indicates if user is allowed in the organization workspace: true
Request Sample
{
  "email": "<user@example.com>",
  "workspaceDomain": "<workspace.example.com>"
}
Response 200
{
  "success": true,
  "data": {
    "isValid": true,
    "owId": 123,
    "isWorkspaceAllowed": true
  }
}

Validate Workspace Domain​

POST /api/v3/ua/user/workspace/validate

Validate the workspace domain associated with a user.

Request Schema
email
string		User's email
workspaceDomain
string		Workspace domain to validate
Response Properties
success
boolean		Indicates workspace domain is valid: true
Request Sample
{
  "email": "user@ihp.com",
  "workspaceDomain": "app.stage.inhousebuying.com"
}
Response 200
{
  "success": true
}

Validate User Email for Signup​

POST /api/v3/ua/user-email/validate

Check if a user's email is already registered for signup.

Request Schema
email
string		User's email
Response Properties
userName
string		User name
isNewUser
boolean		Indicates user is new to platform: true
isOrganizationOwnerUser
boolean		Indicates user is organization owner: true
Request Sample
{
  "email": "<user@example.com>"
}
Response 200
{
  "success": true,
  "data": {
    "userName": "userName",
    "isNewUser": false,
    "isOrganizationOwnerUser": false
  }
}

Validate User Password​

POST /api/v3/ua/user/current-password/validate

Validate the user's password.

Request Schema
password
string		User's password
Response Properties
isValid
boolean		Indicates password is valid: true
Request Sample
{
  "password": "userPassword"
}
Response 200
{
  "success": true,
  "data": {
    "isValid": false
  }
}