Upload a Matched Audience

IQM’s REST API enables you to interact with most of our platform's applications.

Get started uploading a matched audience with the following endpoints:

POST /api/v3/ua/login
POST /api/v3/audience/static/matched/column-list
POST /api/v2/audience/matched/add
GET /api/v2/audience/matched/{matched_audience_Id}

About IQM Matched Audience

The IQM APIs provide access to upload the audience for matching in XLSX or CSV format. The APIs can be used to connect to the desired application.

Once uploaded and processed, the matched audience can be used for advertising Campaign targeting.

Before You Begin

To upload Matched Audience, the following are required:

1. An Account On the IQM platform
   • See Before You Begin section to create an account and request a Client ID and Client Secret
2. CSV or XLSX File for Matching

info

File requirements for audience matching:

• CSV or XLSX file for audience matching with maximum 1GB or 5M records
• Without Voter ID / Email / Phone / Address in the file
  • One of the following system field combinations is required for matching
    • First Name, Last Name, Zip, State
    • Last Name, Street Address, Zip, State
    • Street Address, Zip, state
  • Other fields are optional and can be added along with the above fields
• With Voter ID / Email / Phone / Address in the file
  • Only one of these fields is required - Voter ID or Email or Phone, or Address. The preferred format for full address is Street, City, Zip, and State
  • Other fields are optional and can be added along with one of the above fields

Upload Matched Audience Using the IQM API

This quickstart will cover how to create a matched audience.

The minimum requirements to perform this task are: logging in with authentication credentials, selecting columns for matching, and uploading an audience. Once these steps are accomplished, more can be learned about IQM's API through the Guidelines pages.

1. Log In
   • Optional if you have already logged in and have a token
2. Request Column List
   • Optional if you already know desired/supported columns
3. Upload Matched Audience
   • Upload the audience with parameters from the previous steps
4. Check Audience Status
   • Matched audience requires processing and approval before it can be used for targeting

Step 1: Log In

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-HOST string required	Workspace URL

Request Schema
grantType string required	OAuth Grant Types
email string required	User account email
password string required	User account password

JSON

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 Response Samples

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

TypeScript

See TypeScript Prerequisites page 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": {
          email: `string`,
          password: `string`,
        }
      }
    }
  };

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

Step 2: Request Column List

GET /api/v3/audience/static/matched/column-list

To upload a matched audience, a list of mapping between supported fields and columns in a CSV/XLSX file must be provided. Use the column list endpoint to request a full list of supported columns for mapping.

For further information see the complete Matched Audience Fields API Documentation.

Headers
Authentication string required	Authentication Bearer Token See Authentication Guide
X-IAA-OW-ID string required	Organization Workspace ID Header

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "label": "Voter ID",
      "key": "Voters_ID",
      "order": 1,
      "isSingleColumn": true
    },
    {
      "id": 26,
      "label": "NPI ID",
      "key": "NPI_ID",
      "order": 2,
      "isSingleColumn": true
    },
    {
      "id": 2,
      "label": "Email",
      "key": "Email",
      "order": 3,
      "isSingleColumn": true
    },
    {
      "id": 3,
      "label": "Phone",
      "key": "Phone",
      "order": 4,
      "isSingleColumn": true
    },
    {
      "id": 4,
      "label": "Full Address",
      "key": "Residence_FullAddress",
      "order": 5,
      "isSingleColumn": true
    },
    {
      "id": 5,
      "label": "First Name",
      "key": "Voters_FirstName",
      "order": 6,
      "isSingleColumn": false
    },
    {
      "id": 6,
      "label": "Last Name",
      "key": "Voters_LastName",
      "order": 7,
      "isSingleColumn": false
    },
    {
      "id": 7,
      "label": "Zip",
      "key": "Residence_Addresses_Zip",
      "order": 8,
      "isSingleColumn": false
    },
    {
      "id": 8,
      "label": "State",
      "key": "Residence_Addresses_State",
      "order": 9,
      "isSingleColumn": false
    },
    {
      "id": 9,
      "label": "Street Address",
      "key": "Residence_Addresses_AddressLine",
      "order": 10,
      "isSingleColumn": false
    },
    {
      "id": 10,
      "label": "Full Name",
      "key": "Voters_FullName",
      "order": 11,
      "isSingleColumn": false
    },
    {
      "id": 11,
      "label": "City",
      "key": "Residence_Addresses_City",
      "order": 12,
      "isSingleColumn": false
    },
    {
      "id": 12,
      "label": "ZipPlus4",
      "key": "Residence_Addresses_ZipPlus4",
      "order": 13,
      "isSingleColumn": false
    },
    {
      "id": 13,
      "label": "Age",
      "key": "Voters_Age",
      "order": 14,
      "isSingleColumn": false
    },
    {
      "id": 14,
      "label": "Gender",
      "key": "Voters_Gender",
      "order": 15,
      "isSingleColumn": false
    },
    {
      "id": 15,
      "label": "Ethnicity",
      "key": "Ethnic_Description",
      "order": 16,
      "isSingleColumn": false
    },
    {
      "id": 16,
      "label": "Latitude",
      "key": "Residence_Addresses_Latitude",
      "order": 17,
      "isSingleColumn": false
    },
    {
      "id": 17,
      "label": "Longitude",
      "key": "Residence_Addresses_Longitude",
      "order": 18,
      "isSingleColumn": false
    }
  ]
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          label: string;
          key: string;
          order: number;
          isSingleColumn: boolean;
        }[];
      }
    };
  };
};

function getMatchedAudienceColumnList(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/audience/static/matched/column-list',
  };

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

Step 3: Upload Matched Audience

POST /api/v2/audience/matched/add

To upload matched audiences, provide file columns for matching and all the necessary parameters.

Please refer to MDN Documentation on form data format.

For further information see the complete Matched Audience Upload API Documentation.

Headers
Authentication string required	Authentication Bearer Token See Authentication Guide
X-IAA-OW-ID string required	Organization Workspace ID Header

Payload (Form Data)
columns * string (FormData)	Matched audience file columns mapped with system fields. This supports a few columns mapping as follows: FirstName, LastName, State, Zip Sample value: { "FirstName": "Voters_FirstName", "LastName": "Voters_LastName", "mState": "Residence_Addresses_State", "mZip5": "Residence_Addresses_Zip" } LastName, StreetAddress, State, Zip Sample value: { "LastName": "Voters_LastName", "StreetAddress": "Residence_Addresses_AddressLine", "mState": "Residence_Addresses_State", "mZip5": "Residence_Addresses_Zip" } StreetAddress, State, Zip Sample value: { "StreetAddress": "Residence_Addresses_AddressLine", "mState": "Residence_Addresses_State", "mZip5": "Residence_Addresses_Zip" } NPI_ID Sample value: { "NPI_ID_VALUE": "NPI_ID" } VoterId Sample value: { "LALVOTERID": "Voters_ID" } Phone Sample value: { "Phone": "Phone" } Email Sample value: { "Email": "Email" } FullAddress Sample value: { "FullAddress": "Residence_FullAddress" }
columnSettings string (FormData)	Matched audience columns setting as per the selected columns for matching. Column setting should be as per the selected column as follows: FirstName, LastName, State, Zip [not required] LastName, StreetAddress, State, Zip [not required] StreetAddress, State, Zip [not required] LastName, StreetAddress, State, Zip [not required] VoterId Value must be a supported voter's data partners ID (see API documentation) Sample value: { "Voters_ID": "voterbase_id" } NPI_Id Value must be a supported healthcare data partners ID (see API documentation) Sample value: { "NPI_ID": "healthcare_id" } Phone Value must be a supported data format's ID (see API documentation) Sample value: { "Phone": "SHA1" } Email Value must be a supported data format's ID (see API doucmentation) SampleValue: { "Email": "SHA256" } FullAddress [not required]
audienceName string (FormData) required	Name of matched audience
metadata string (FormData) required	Matched audience sample data with system fields
fileTotalCount integer (FormData) required	Total number of records in the uploaded audience file
isSingleColumnEnabled boolean (FormData) required	Flag to indicate if the mapping is single column enabled, if the voterId/phone/email/full-address the primary column mapping then this should be true, and false otherwise. Default value: false

FormData

Request Sample (FormData)

------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="file"; filename="matched-audience-example.csv"
Content-Type: text/csv

------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="columns"

{"first-name":"Voters_FirstName","last-name":"Voters_LastName","zip":"Residence_Addresses_Zip","state":"Residence_Addresses_State","street-address":"Residence_Addresses_AddressLine"}
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="metadata"

{"columns":["registered-voter-id","l2-voter-id","targetsmart-voter-id","first-name","last-name","street-address","city","zip","zipplus4","state","full-address","phone","email","phone-sha256","email-sha256","npi-id"],"fileName":"matched-audience-example.csv","fileSize":1777,"columnValues":{"registered-voter-id":["23457","456789","34567"],"l2-voter-id":["LALNY987654","LALNY76543","LALNY54321"],"targetsmart-voter-id":["NY-000020745","NY-000032452","NY-000069778"],"first-name":["Bilbo","Frodo","Samwise"],"last-name":["Baggins","Baggins","Gamgee"],"street-address":["11 The Shire Middle Earth","22 The Shire Middle Earth","33 The Shire Middle Earth"],"city":["New York","New York","New York"],"zip":["10001","10010","10011"],"zipplus4":["1122","2233","3344"],"state":["NY","New York","NY"],"full-address":["11 The Shire Middle Earth, New York, 10001, NY","22 The Shire Middle Earth, New York, 10010, NY","33 The Shire Middle Earth, New York, 10011, NY"],"phone":["3456789012","5678901234","7890123456"],"email":["Bilbo.Baggins@lotr.com","Frodo.Baggins@lotr.com","Samwise.Gamgee@lotr.com"],"phone-sha256":["26cc49f1a2133f3784b937017f9cc86e05b5413c7f91b0b6bd6375631b68371e","2f510ce904687db4b2706fdaf33f1d0e678be13cc5fe300cf695a546befa5fc8","453fc17260d034186d92d1e58cc557fea9cafc1bf886154b472057feed950605"],"email-sha256":["43f5f8fabe82fc8dce2452267f5550bb036d0ddf33368682a9cd5da8286d63a0","ceb005d969f16f9a6a487849d27bf854fac1f0733aa61995bcbb5cb928dfc410","986c1ae0d3cef60591d3b29aa54afb5d9654406d7cfa4fcbb65c3ad45ad1ce5c"],"npi-id":["1144317652","1467478172","1275506503"]},"rows":5}
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="audienceName"

Matched Audience Sample
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="isSingleColumnEnabled"

false
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ
Content-Disposition: form-data; name="fileTotalCount"

5
------WebKitFormBoundary2LAoPYE0pJvRQ6mQ--

Response 200

{
   "statusCode": 200,
   "responseObject": {
       "id": 15332,
       "message": "Audience created successfully"
   }
}

More Response Samples

Response 400

{
   "statusCode": 400,
   "responseObject": {
     "errorMsg": "Audience name can not be null.",
     "errorCode": 400
   }
}

Response 500

{
   "statusCode": 500,
   "responseObject": {
     "errorMsg": "Internal server error",
     "errorCode": 500
   }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          id: number;
          message: string;
        }
      }
    };
  };
  400: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          errorMsg: string;
          errorCode: number;
        }
      }
    };
  };
  500: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          errorMsg: string;
          errorCode: number;
        }
      }
    };
  };
};

function addMatchedAudience(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v2/audience/matched/add',
    params: {
      query: {
        columns: `string`,
        columnSettings?: `string`,
        audienceName: `string`,
        metadata: `string`,
        fileTotalCount: `number`,
        isSingleColumnEnabled: `boolean`
      }
    },
    requestBody?: {
      content: {
        "multipart/form-data": {
          file: `string`
        }
      }
    }
  };

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

Step 4: Check Audience Status

GET /api/v2/audience/matched/{id}

Before the audience can be used for Campaign targeting it has to be processed and approved. Once the status is Ready, the audience can be targeted. Use the id generated in the last step with this endpoint to get audience details.

For further information see the complete Matched Audience Details API Documentation.

Path Parameters
id string required	Matched audience ID

Headers
Authentication string	Authentication Bearer Token See Authentication Guide
X-IAA-OW-ID string	Organization Workspace ID Header

JSON

Response 200

{
   "statusCode": 200,
   "responseObject": {
     "id": 1,
     "audienceName": "Sample audience name",
     "existingColumnMatching": "{\"FirstName\":\"Voters_FirstName\",\"LastName\":\"Voters_LastName\",\"State\":\"Residence_Addresses_State\",\"Zip4\":\"Residence_Addresses_Zip\"}",
     "metadata": "{\"voterIDColumn\":[],\"columns\":[\"Voter File VANID\",\"LastName\",\"FirstName\",\"MiddleName\",\"Suffix\",\"Address\",\"City\",\"State\",\"Zip5\",\"Zip4\",\"Sex\",\"Age\",\"Preferred Phone\",\"CD\",\"SD\",\"HD \"],\"fileName\":\"NYSD3DigitalUniverse.csv\",\"fileSize\":7856375,\"rows\":0}",
     "rawS3URL": "",
     "status": "Pending",
     "matchRate": 57.88,
     "minEcpm": 0,
     "maxEcpm": 0,
     "s3FileName": "MatchedAudienceSample.csv",
     "included": 0,
     "excluded": 0,
     "createdDate": 1642843451,
     "modifiedDate": 1642843884,
     "organizationName": "Sample organization name",
     "userName": "Sample user name",
     "expectedSpent7": 0,
     "expectedSpent30": 0,
     "expectedSpent60": 0,
     "dataCost": 1.5,
     "owId": 1,
     "uowId": 1,
     "rawS3URLError": "File not available currently, please check later",
     "uniques": 52432,
     "approvedRejectedByUserName": "Sample user name",
     "approvedRejectedByUserEmail": "example@example.com",
     "isApprovalAccess": true,
     "isEditAccess": true
   }
 }

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          id: number;
          audienceName: string;
          existingColumnMatching: string;
          metadata: string;
          rawS3URL: string;
          status: string;
          matchRate: number;
          minEcpm: number;
          maxEcpm: number;
          s3FileName: string;
          included: number;
          excluded: number;
          createdDate: number;
          modifiedDate: number;
          organizationName: string;
          userName: string;
          expectedSpent7: number;
          expectedSpent30: number;
          expectedSpent60: number;
          dataCost: number;
          owId: number;
          uowId: number;
          rawS3URLError: string;
          uniques: number;
          approvedRejectedByUserName: string;
          approvedRejectedByUserEmail: string;
          isApprovalAccess: boolean;
          isEditAccess: boolean;
        };
      };
    };
  };
};

function getMatchedAudienceDetails(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v2/audience/matched/{id}',
    params: {
      path: {
        id: `number`,
      }
    }
  };

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