Skip to main content

API

Support Team avatar
Written by Support Team
Updated yesterday

Supported data

  • events (name, date, location, capacity, etc.)

  • event images (the API supports multiple, but only one is imported to the product)

  • tours (linked to an event but not shown in the product)

  • purchase orders (a bunch of tickets bundled into one order)

  • tickets

  • ticket classes

  • contacts

    • fans who have made purchases

    • fans who have attended events (ticket holders)

  • Message list subscriptions


Sync time

The sync time is determined by who imports the data and how busy the API is.

When someone imports data into the API, it is added to a 'waiting list'; if the 'waiting list' is small, it will only take a few minutes to import the data into the product.

If there is a large amount of data on the 'waiting list,' this could take several hours to complete.


Throughput

Audience Republic has a scheduled task that scans this list every 5 minutes and processes it at a steady pace. Currently, there are approximately 50,000 of each type of entity, for a maximum of 400,000 entities. If all of the commonly large sets of data are full (contacts, orders, tickets, tags, subscriptions), then you're looking at approximately 250,000 records every 5 minutes at the highest rate of throughput.


Caching

Once the data from the 'waiting list' is imported into the product, it goes through a process of aggregation and caching (for faster access), which we call materialisation. This is essentially a way to speed up your audience filtering.

Our platform has another set of periodic tasks that handle this, with periods ranging from 5 to 20 minutes. In general, they will be able to handle all outstanding tasks within each period, so 'caching' for audience filtering will typically take no more than 30 minutes.

This means that imported contact data with associated ticket sales, event attendance, etc. will be filterable in the Audience section of the product from as little as a few minutes, up to several hours, depending on when the period tasks next run and the number of pending tasks. In most cases, it will be available within 30 minutes.

Audience Republic can handle the following data types, depending on the information provided by the client via an external API.


API Tokens

Before you get started

  • Make sure your account has a subscription plan (such as Audience Manager, Plus Plan, or Pro plan)

  • Please ask your customer success manager to enable the API Token feature in your account

  • Check out Audience Republic's hosted API documents HERE

  • Please note, Custom Fields cannot be exposed through the ingestion API

  • Go to Account Settings

  • Once Customer Success or Support have enabled this feature, the API Tokens feature will appear in your account here:

  • Click API Tokens

  • Select Issue New Token

  • A new Token will be automatically generated

  • To remove a Token, click Revoke Token

API Key for signup forms

Use the API feature to connect your own bespoke signup form and then sync contacts to a nominated list. Learn more about assigning contacts to lists in the Contacts call section.

About API tokens

The design is asynchronous, data sent to this API is loaded into temporary storage (the 'Ingestion DB'), held there (currently for around 15 minutes) then eventually loaded into the database that backs the website. During this process, it does not have access to the IDs that will be used in the primary DB. This API expects you, the caller, to provide your own IDs that can be used to track objects.

An API token is a unique identifier used to authenticate a user to access an API. These API Tokens are automatically generated by Audience Republic.

API Test Calls

How to do API test calls

When using API, there is a field available for including tags. This can be found in the Contacts call section. Including tags in your API call is a great way to organise your contacts and make them easier to manage.

1. Create an API token in your Audience Republic account

3. To create a new contact, click Contacts > Create Contacts

4. On the right-hand side bar, click on Post Contacts and copy the URL

4. Open your Integration (such as Talend Chrome Extension), go to Requests > Repository tab, and paste the URL in the Scheme/Host section

5. Add a ? and the provider name at the end of the URL

Example: ?provider=aaronstahi

6. Add Authorisation (which is the API key) and add 'Bearer,' then paste in the API key

7. Go back to the documentation page and copy the contact call

8. Populate it into the Body, adding details such as tags

9. Once completed, click Send

**Please note: Our API isn't immediate also, takes a minute or so for info to come across

Including tags in your API call can help you segment your contacts and target them with more relevant content. For example, if you have a promotion for VIP customers, you can use the tag "VIP" to send the promotion only to those customers.

Including tags in your API call is a simple but powerful way to organise your contacts and improve your marketing efforts.

Adding contacts to a list using the API

How to add contacts to a list using the API

Step 1: Trigger the Mail Call

After adding a contact, trigger the mail call to ensure the contact is added to the intended list. This can be done immediately after creating the contact.

Step 2: Automate the Process

To streamline the process, you can set up an automated workflow where the mail call is triggered upon receiving a contact ID (email address). This ensures contacts are promptly assigned to the correct list without manual intervention.

Please note, it can sometimes take up to 24 hours for emails to land in the console

Step 3: Use the Tagging Feature

The API includes a field for adding tags in the Contacts call section. By assigning tags to your contacts during the API call, they will automatically be categorized into the appropriate list. This eliminates the need for manual sorting or categorization.

Helpful Resources

By following these steps and using the tagging feature, you can efficiently add contacts to specific lists and streamline your workflow.

About API tokens

The design is asynchronous, data sent to this API is loaded into temporary storage (the 'Ingestion DB'), held there (currently for around 15 minutes) then eventually loaded into the database that backs the website. During this process, it does not have access to the IDs that will be used in the primary DB. This API expects you, the caller, to provide your own IDs that can be used to track objects.

Adding contacts to a specific list using the Audience Republic API can be a seamless process when set up correctly.

Best practices for using API Tokens

  1. Batch Contacts: If you are adding multiple contacts at once, it’s more efficient to batch them in a single API call. Simply add more contact objects within the `"contacts"` array.

  2. Tag Usage: Adding relevant tags helps organize contacts for segmentation. Ensure you use descriptive and appropriate tags to categorize your audience for better targeting.

  3. Error Handling: Be sure to handle any API responses or errors appropriately. Successful responses will confirm that contacts were added, while errors can give insight into potential issues (e.g., invalid email format or missing required fields).

  4. Test Before Sending
    Always run a test with a small batch of contacts to ensure the process works as expected before scaling up. This helps ensure your API integration is smooth and working without errors.

  5. Regularly Update Your Contacts
    Using tags in conjunction with the API allows for more dynamic list management. As your marketing campaigns evolve, be sure to keep contacts and their tags up to date by making API calls to add, update, or remove tags based on their interaction with your campaigns.

Using the Audience Republic API to add contacts directly into mailing lists with tags is a powerful way to streamline your email and contact management workflows. By following these steps and best practices, you can ensure that your contacts are properly organised, tagged, and ready for your marketing campaigns.

For more information on using the Audience Republic API, check out our full API documentation here

Managing Opt-In status via API (Outside GDPR Regions)

When setting up marketing opt-ins through the API, follow these steps to ensure compliance and correct list assignment (Outside GDPR Regions):

  1. Use the Contact API to Check Opt-In Status

    • The marketing-opt-in field is a boolean that indicates a contact's opt-in status:

      • TRUE = the contact has opted in

      • FALSE = the contact has not opted in

    • This applies to both email and SMS communications — make sure this is clearly communicated to the customer.

  2. Add Opted-In Contacts to Mailing Lists

    • Use the Mailing List API to add contacts.

    • Only add contacts to the appropriate list (email or SMS) if marketing-opt-in = TRUE.

  3. Clearly Communicate Dual Consent

Always remind the customer that marketing opt-in applies to both email and SMS — they must have permission to contact via the selected channel(s).

Please note: Our signup forms are designed to support separate opt-ins for both email and SMS, allowing users to clearly choose their preferred communication channels. We don’t recommend using the API for consent collection in GDPR regions, as it lacks the granularity and safeguards built into our product UI. This is a deliberate design choice — we prioritise product-based compliance to minimise risk and reduce the need for manual handling.

A recommended approach is to create distinct opt-in journeys, such as “Sign up for SMS” and “Sign up for Email,” and apply tags based on the user’s choice. These tags can then trigger automations that assign users to the relevant opt-in lists.

This method ensures a compliant, user-friendly experience while giving you the flexibility to scale marketing workflows effectively.

Did this answer your question?