Audiences

cookbook upload a csv and match it to the voter file audiences /#post uploadcsv using the audience id returned in step 1, audiences /#get audience every 5 seconds or so until the uploadedaudiencecsv status value in the audience response is ready for column selection audiences /#post matchuploadedcsv to the voter file using that same audience id (which will be returned in step 3 as well), audiences /#get audience every 5 seconds or so until the audience's status is active import a list from bigquery and match it to the voter file if you haven't already enabled our bigquery integration, open the matchbook app and configure it in your organization's settings audiences /#post importbqtable from your dataset follow steps 2 4 from the instructions in the previous section ("upload a csv"), create a lookalike of a matched csv audience follow steps 1 4 in audiences /#upload a csv and match it to the voter file above to match your csv to the voter file using the audience id of your matched audience as the baseaudienceid parameter, audiences /#post createlookalikeaudience from your matched audience using the audience id returned by step 2, audiences /#get audience every 5 seconds or so until the audience's status is active export an audience to export an audience created via audiences /#upload a csv and match it to the voter file or audiences /#create a lookalike of a matched csv audience audiences /#post createcsvexport using the audience id for the audience you'd like to export audiences /#get audience to the audience until the export's status is no longer in progress if the export's status is now requires payment , audiences /#post purchasecsvexport by passing in the export id returned in step 1 once the export's status is active , you can use its downloadurl field to download your export csv if you need to download your export again in the future, you can always access it by audiences /#get audience and then finding your export in the csvexports field on the audience notes api setup to get set up to use our api, reach out to request an api token once you have your token, you'll need to include it in the authorization header of all requests authorization bearer \<token> the base url for our api is https //app indigo engineering/api/v1 customer id customerid is an arbitrary string that should identify each of your customers (this could be a hash or simply an integer id or whatever else you want) the goal here is to separate data by user so that it's easy to tell which records are associated with which of your users however, if you'd like to pass the same customerid for every request, that will work fine as well note that customerid is enforced at the api level and is required for several endpoints, including all the endpoints that create audiences for example, if an audience is created with a customer id of 1 and then /audience is called to retrieve that audience but a customer id of 2 is passed in, no audience will be returned — in other words, no audience with the requested id exists for customer 2 errors to indicate an error, the api will return a json response containing an error key whose value will be a human readable error message in most cases, there will also be an errortype key containing a machine readable error type error responses will typically have a 400 status code or similar (401, 429, 405, etc ) for example { "error" "you've already made this purchase ", "errortype" "purchasableentityalreadypurchased" } endpoints post /upload csv asynchronously upload a csv of people in order to match it to the voter file response is a stub audience request parameters customerid arbitrary string representing a unique customer id this will be associated with the created audience and will need to be passed whenever interacting with that audience url url of the csv example request { "customerid" "123", "url" "https //storage googleapis com/your public bucket/your csv csv" } example response { "id" "1", "status" "pending", "uploadedaudiencecsv" { "id" "12", "status" "ready for parsing" }, } post /import bq table asynchronously import a bigquery table in order to match it to the voter file response is a stub audience (the "uploaded audience csv" attached to the audience is a bit of a misnomer it's just matchbook's internal representation of your imported bigquery table ) request parameters customerid arbitrary string representing a unique customer id this will be associated with the created audience and will need to be passed whenever interacting with that audience tablename the name of the table in the import dataset that you specified when you configured your bigquery integration example request { "customerid" "123", "tablename" "my bq table" } example response { "id" "1", "status" "pending", "uploadedaudiencecsv" { "id" "6", "status" "ready for parsing" } } post /match uploaded csv asynchronously fill in the audience by matching an uploaded csv to our voter file using our schema and specify which fields are required or optional for our matching algorithm response is the newly created audience note that your audience's uploadedaudiencecsv status must be ready for column selection before calling this endpoint request parameters audienceid the audience id returned from /upload csv customerid arbitrary string representing a unique customer id must be the same as the customer id associated with the audience created in /upload csv audiencename name for audience must be unique by customerid columnselections a json dictionary in which each entry is of the form \[canonical field] { column name \[column name], is required \[true or false] } in each case, canonical field should be one of voterbase id , first name , last name , full name , city , state , zip , phone , dob (date of birth), address , or row id column name should be the corresponding column name as it appears in your source csv more details about column selections for api requests, the only constraint on required matching fields is that you must specify at least one field (this differs from the behavior of the matchbook web application, in which the set of required fields must include either a) first name , last name , and at least one other field, b) full name and at least one other field, or c) voterbase id ) if you include full name as a required or optional field, you can't also include first name or last name if you include address , you must make it an optional field (it can't be a required field because matching on address is too unreliable to be used as a strict requirement it can be helpful as an optional matching field, though ) if your source csv has an id column that uniquely identifies each row, you can specify it for tracking purposes using the row id canonical field if you don't specify an id column, we'll identify the records in your csv using row numbers you may want to use these ids to link your matched audience back to your original csv data note that i f you include row id , you must make it a required field also note that you can reuse the same column for both row id and one of the matching fields example request { &#x9;"audienceid" "1", &#x9;"customerid" "123", &#x9;"audiencename" "some unique audience name", &#x9;"columnselections" { &#x9; "address" { &#x9; "column name" "address", &#x9; "is required" false &#x9; }, &#x9; "first name" { &#x9; "column name" "first name", &#x9; "is required" true &#x9; }, &#x9; "last name" { &#x9; "column name" "last name", &#x9; "is required" true &#x9; }, &#x9; "state" { &#x9; "column name" "state", &#x9; "is required" true &#x9; }, &#x9; "zip" { &#x9; "column name" "zip", &#x9; "is required" false &#x9; } &#x9;} } e xample response { "id" "1", "createdat" "2025 01 15t20 13 05 026281+00 00", "customerid" "123", "name" "some unique audience name", "status" "pending", "metadata" null, "isarchived" false, "cancreatelookalikefrom" false, "errorinfouserfacing" null, "numlookalikesrequested" null, "lookalikeincludeoriginalaudience" null, "isfilteredfromlookalike" false, "audiencelookalikecreatedfrom" null, "csvexports" \[], "filters" null, "uploadedaudiencecsv" { "id" "1", "createdat" "2025 01 15t20 13 05 013135+00 00", "status" "active" }, "uploadedaudiencecsvmatchmetadata" null } get /audience retrieve an existing audience request parameters audienceid the audience id customerid (optional) the customer id associated with the audience if the audience has a customer id (i e was created via the api), this will be required to retrieve it if the audience does not have a customer id (i e was created via the app), this isn't required to retrieve it example request { id 1, customerid "123" } example response { "id" "1", "createdat" "2025 01 15t20 13 05 026281+00 00", "customerid" "123", "name" "some unique audience name", "status" "active", "metadata" { "size" 58015, "gender f" 28613, "gender m" 28394, "num phones" 23219, "party dem" 19474, "party ind" 24750, "party rep" 13791, "race aapi" 6404, "race none" 4749, "race black" 5995, "race white" 28536, "gender none" 1008, "race latino" 11811, "age group 55+" 12733, "age group 18 34" 29053, "age group 35 54" 15211, "age group alt 65+" 7171, "age group alt 18 24" 11803, "race native american" 520 }, "isarchived" false, "cancreatelookalikefrom" true, "errorinfouserfacing" null, "numlookalikesrequested" null, "lookalikeincludeoriginalaudience" null, "isfilteredfromlookalike" false, "audiencelookalikecreatedfrom" null, "csvexports" \[ { "id" "2948", "createdat" "2025 06 25t21 20 49 032192+00 00", "downloadurl" " ", "externalbqtablename" " ", "purchasecostbreakdown" { "phone" { "price per record" 6, "count already paid" 0, "count total available" 205, "count requiring payment" 205, "count uploaded and not purchased" 0, } }, "size" 250, "status" "active", "totalcostincents" 1230, } ], "filters" null, "uploadedaudiencecsv" { "id" "1", "createdat" "2025 01 15t20 13 05 013135+00 00", "status" "active" }, "uploadedaudiencecsvmatchmetadata" { "nummatches" 58333, "numuniquematches" 58015, "columnmatchresults" \[ { "column" "zip", "percentofmatches" 0 9867999245709975, "percentmissing" 0 0 }, { "column" "state", "percentofmatches" 1 0, "percentmissing" 0 0 }, { "column" "address", "percentofmatches" 0 9870913548077418, "percentmissing" 0 0 }, { "column" "last name", "percentofmatches" 1 0, "percentmissing" 0 0 }, { "column" "first name", "percentofmatches" 1 0, "percentmissing" 0 0 } ] } } post /create csv export s ynchronously create a csv export response is the export record, with information about the associated audience record nested under the audience key if the export has a cost associated with it, the returned export record will have a status of requires payment and it will include a totalcost field (in cents) to access the export, you'll first need to purchase it using audiences /#post purchasecsvexport if the export has no cost (either because you're not exporting any new paid information or because your organization is exempt from export fees), its status will be active and you'll be able to download it immediately using the signed url in the downloadurl field you can always retrieve a full list of exports for a given audience using audiences /#get audience request parameters audienceid the audience id optionalfieldtypes (required) a list of paid contact info field types to be included in the export in addition to the standard fields that are provided free of charge the current options are phone , address , vote history , issue scores , media scores , support scores , turnout scores , and lookalike scores the response shows the cost (in cents) of the proposed export and includes a breakdown of how that cost was computed customerid (optional) the customer id associated with the audience if the audience has a customer id (i e was created via the api), this is required if the audience does not have a customer id (i e was created via the app), this isn't required shouldexporttobq (optional) boolean if true, we'll export the audience to your bigquery project however, in order for this to work, you'll first need to configure the matchbook<>bigquery integration in matchbook custombqtablename (optional) if provided, we'll export the audience to this table in your bigquery dataset example request { &#x9;"audienceid" 1, &#x9;"customerid" "123", &#x9;"optionalfieldtypes" \[ &#x9; "phone", &#x9;] } example response { "id" "1", "purchasecostbreakdown" { "phone" { "price per record" 6, "count total available" 23219, "count already paid" 0, "count requiring payment" 23219 }, }, "size" 58015, "totalcost" 139314, "audience" { "id" "1", "customerid" "123", "metadata" { "size" 58015, "gender f" 28613, "gender m" 28394, "num phones" 23219, "party dem" 19474, "party ind" 24750, "party rep" 13791, "race aapi" 6404, "race none" 4749, "race black" 5995, "race white" 28536, "gender none" 1008, "race latino" 11811, "age group 55+" 12733, "age group 18 34" 29053, "age group 35 54" 15211, "age group alt 65+" 7171, "age group alt 18 24" 11803, "race native american" 520 } } } post /purchase csv export after creating an export via audiences /#post createcsvexport and receiving a response with status requires payment , synchronously purchase the export response is the export record, including downloadurl , along with a few fields of information about the associated audience record nested under the audience key your organization will be invoiced for the purchase request parameters exportid the export id from audiences /#post createcsvexport customerid (optional) the customer id associated with the audience/export if the audience has a customer id (i e was created via the api), this will be required if the audience does not have a customer id (i e was created via the app), this isn't required example request { "exportid" "1", "customerid" "123" } example response { "id" "1", "createdat" "2025 01 22t18 43 38 342670+00 00", "downloadurl" "https //storage googleapis com/matchbook exports/ ", "externalbqtablename" null, "purchasecostbreakdown" { "phone" { "price per record" 6, "count total available" 23219, "count already paid" 0, "count requiring payment" 23219 } }, "status" "active", "totalcost" 139314, "audience" { "id" "1", "customerid" "123", "metadata" { "size" 58015, "gender f" 28613, "gender m" 28394, "num phones" 23219, "party dem" 19474, "party ind" 24750, "party rep" 13791, "race aapi" 6404, "race none" 4749, "race black" 5995, "race white" 28536, "gender none" 1008, "race latino" 11811, "age group 55+" 12733, "age group 18 34" 29053, "age group 35 54" 15211, "age group alt 65+" 7171, "age group alt 18 24" 11803, "race native american" 520 } } } post /create lookalike audience asynchronously create a lookalike audience based on an existing matched audience to be eligible for lookalike expansion, an audience must be based on matching at least 1,000 people to the voter file from an uploaded csv response is the audience record request parameters baseaudienceid id of a matched audience to use as the base for the lookalike customerid c ustomer id to use for the new audience if the base audience does not have a customer id (i e it was created via the app), that is ok — the base audience only needs to match the passed in customer id if it has one size desired size of your lookalike audience as an integer audiencename name for the new lookalike audience must be unique by customerid includeoriginalaudience (optional) boolean, whether to include the original audience's members in the lookalike filters (optional) a json dictionary containing filters to be applied, in which entries are of the form specified below "filters" { // integer "ageend" 70, // boolean "ageincludeunknown" true, // integer "agestart" 24, // string cell is only valid option currently "contactinfo" "cell", // list of strings, all possible options listed below "genders" \[ "none", "m", "f" ], // boolean "hasdonorhistory" true, // list of strings, all possible options listed below "races" \[ "black", "latino", "native american", "white", "none", "aapi" ], // date (string) formatted like 'yyyy mm dd' "registrationdateend" "2025 12 31", // date (string) formatted like 'yyyy mm dd' "registrationdatestart" "1900 01 01", // see "geographic filters" pages (links below) for details "congressionaldistricts" null, "stateleglowerdistricts" null, "statelegupperdistricts" null, "counties" null, // list of strings, all two digit state codes including dc "states" \["ny"], // five digit zip code as string if present, `distancefromzip` must also be present "zip" "11215" // integer, in miles (can be 0) if present, `zip` must also be present "distancefromzip" 3, } see counties docid 4av 7 40kr95pixgj7t9h , congressional districts docid\ ixcvra3bersrg prmq4ir , upper state legislative districts docid 61wktlkm0hwxodajq3cql , and lower state legislative districts docid\ gjgzg mjrcfzxcwn6 qq1 for details on the possible values for those fields note that geographic filters are applied with a conjunction, meaning that only voters who match all of these geographic filters will be included in your audience e xample request { "audiencename" "lookalike of some unique audience name", "baseaudienceid" 1, "size" 2000, "customerid" "123", "filters" { "states" \[ "co", "ca" ] } } e xample response { "id" "6", "createdat" "2025 01 22t17 17 17 715679+00 00", "customerid" "123", "name" "lookalike of some unique audience name", "status" "pending", "metadata" null, "isarchived" false, "cancreatelookalikefrom" false, "errorinfouserfacing" null, "numlookalikesrequested" 2000, "lookalikeincludeoriginalaudience" null, "isfilteredfromlookalike" false, "audiencelookalikecreatedfrom" { "id" "1" }, "csvexports" \[], "filters" { "id" "10", "createdat" "2025 01 22t18 22 57 710604+00 00", "states" \[ "co", "ca" ], "counties" null, "congressionaldistricts" null, "stateleglowerdistricts" null, "statelegupperdistricts" null, "zip" null, "distancefromzip" null, "agestart" null, "ageend" null, "ageincludeunknown" null, "genders" null, "races" null, "registrationdatestart" null, "registrationdateend" null, "hasdonorhistory" null, "contactinfo" null, "sortfield" null, "sortasc" null, "limit" null }, "uploadedaudiencecsv" null, "uploadedaudiencecsvmatchmetadata" null } get /audiences retrieve a list of audiences for your organization request parameters customerid (optional) only return audiences with this customerid if no customer id is passed, this will return all audiences example request { customerid "123" } example response \[ { "id" "1", "createdat" "2025 01 15t20 13 05 026281+00 00", "customerid" "123", "name" "some unique audience name", "status" "active", "metadata" { "size" 58015, "gender f" 28613, "gender m" 28394, "num phones" 23219, "party dem" 19474, "party ind" 24750, "party rep" 13791, "race aapi" 6404, "race none" 4749, "race black" 5995, "race white" 28536, "gender none" 1008, "race latino" 11811, "age group 55+" 12733, "age group 18 34" 29053, "age group 35 54" 15211, "age group alt 65+" 7171, "age group alt 18 24" 11803, "race native american" 520 }, "isarchived" false, "cancreatelookalikefrom" true, "errorinfouserfacing" null, "numlookalikesrequested" null, "lookalikeincludeoriginalaudience" null, "isfilteredfromlookalike" false, "audiencelookalikecreatedfrom" null, "csvexports" \[], "filters" null, "uploadedaudiencecsv" { "id" "1", "createdat" "2025 01 15t20 13 05 013135+00 00", "status" "active" }, "uploadedaudiencecsvmatchmetadata" { "nummatches" 58333, "numuniquematches" 58015, "columnmatchresults" \[ { "column" "zip", "percentofmatches" 0 9867999245709975, "percentmissing" 0 0 }, { "column" "state", "percentofmatches" 1 0, "percentmissing" 0 0 }, { "column" "address", "percentofmatches" 0 9870913548077418, "percentmissing" 0 0 }, { "column" "last name", "percentofmatches" 1 0, "percentmissing" 0 0 }, { "column" "first name", "percentofmatches" 1 0, "percentmissing" 0 0 } ] } }, { "id" "6", "createdat" "2025 01 22t17 17 17 715679+00 00", "customerid" "123", "name" "lookalike of some unique audience name", "status" "active", "metadata" null, "isarchived" false, "cancreatelookalikefrom" false, "errorinfouserfacing" null, "numlookalikesrequested" 1000, "lookalikeincludeoriginalaudience" null, "isfilteredfromlookalike" false, "audiencelookalikecreatedfrom" { "id" "1" }, "csvexports" \[], "filters" { "id" "10", "createdat" "2025 01 22t18 22 57 710604+00 00", "states" \["co", "ca"], "counties" null, "congressionaldistricts" null, "stateleglowerdistricts" null, "statelegupperdistricts" null, "zip" null, "distancefromzip" null, "agestart" null, "ageend" null, "ageincludeunknown" null, "genders" null, "races" null, "registrationdatestart" null, "registrationdateend" null, "hasdonorhistory" null, "contactinfo" null, "sortfield" null, "sortasc" null, "limit" null }, "uploadedaudiencecsv" null, "uploadedaudiencecsvmatchmetadata" null } ]