Audiences
- Using the audience ID returned in step 1, retrieving that audience every 5 seconds or so until the uploadedAudienceCsv.status value in the audience response is READY_FOR_COLUMN_SELECTION.
- Using that same audience ID (which will be returned in step 3 as well), retrieve that audience every 5 seconds or so until the audience's status is ACTIVE.
- Follow steps 1-4 in 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, create a lookalike audience from your matched audience.
- Using the audience ID returned by step 2, retrieve that audience every 5 seconds or so until the audience's status is ACTIVE.
To export an audience created via uploading a CSV and matching it to the voter file or creating a lookalike of a matched CSV audience:
- Purchase your CSV export by passing in the export ID returned in step 1. You can use the downloadUrl field in the response to download your export CSV.
If you need to download your export again in the future, you can access it by retrieving that audience and then finding your export in the csvExports field on the audience.
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.
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.
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" }
Asynchronously upload a CSV of people in order to match it to the voter file. Response is a stub audience.
- 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.
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.
- 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 first_name, last_name, full_name, city, state, zip, phone, dob (date of birth), address, or 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 or b) full_name and at least one other field.)
- 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 (not for the purpose of matching your records to the voter file). 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 if you include id, you must make it a required field.
Retrieve an existing audience.
- 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.
Synchronously create a preview CSV export. This will include the purchase price for the export. Response is the export record, with information about the associated audience record nested under the audience key.
- 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 is required. If the audience does not have a customer ID (i.e. was created via the app), this isn't required.
- optionalFieldTypes: 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.
Synchronously purchase a CSV export after creating a preview via /create_preview_csv_export. Response is the export record, with a couple fields of information about the associated audience record nested under the audience key. Note that if the export has a cost associated with it, your organization will be invoiced for the purchase.
- exportId: The export ID from /create_preview_csv_export.
- 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.
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.
- baseAudienceId: ID of a matched audience to use as the base for the lookalike.
- customerId: Customer 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:
See Counties, Congressional districts, Upper state legislative districts, and Lower state legislative districts 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.
Retrieve a list of audiences for your organization.
- customerId (optional): Only return audiences with this customerId. If no customer ID is passed, this will return all audiences.