Guides

HTTP Endpoint

Learn how to set up HTTP Endpoint as a destination so you can send audience data to custom APIs.

This article outlines the steps to set up HTTP Endpoint as a GrowthLoop destination and export audiences to your own HTTP APIs. Use this destination when you want GrowthLoop to call a custom API to add or remove audience members, with optional audience lookup and creation before sync.

Requirements

Before you connect HTTP Endpoint in GrowthLoop, make sure you have:

  • Endpoint URL(s) for the API you want GrowthLoop to call when adding or removing audience members.
  • Authentication details, if your API requires them. You can provide custom headers and optionally link a Custom M2M OAuth destination for token-based auth.
  • Request body templates, if your API expects a JSON payload. GrowthLoop uses Handlebars templates so you can shape exported fields into the format your API accepts.
📘

Note

If you do not see HTTP Endpoint in the destination list, contact your GrowthLoop admin or [email protected].

Setting up the destination

  1. Select Destinations from the left rail of your GrowthLoop home screen.

  2. Click New Destination on the top right.

  3. Search for HTTP Endpoint and click Add HTTP Endpoint.

  4. Configure the sections below, then click Create to finalize the destination.

    1. Destination Name: This is how the destination will be named and referred to in the app going forward.
    2. Sync frequency: The default frequency your audiences will be synced to the destination. You can adjust the schedule when you configure an export.

Authentication

Use this section when your API requires credentials on every request.

  • OAuth Destination (Optional): Select or enter the ID of a Custom M2M OAuth destination. When linked, GrowthLoop fetches OAuth tokens automatically and includes them on HTTP Endpoint requests. Set up the OAuth destination first if your API uses machine-to-machine OAuth.
  • Headers (JSON): Add custom HTTP headers as a JSON object. These headers are sent on every request, including get/create audience, add, and remove calls. Example:
{"Authorization": "Bearer token", "X-API-Key": "your-key"}

You can use OAuth, custom headers, or both, depending on what your API requires.


Error Handling

Use this section to control how GrowthLoop responds when requests fail or when you need to pace traffic to your API.

  • Retry on Errors: When enabled, GrowthLoop automatically retries requests that fail with rate limit (429) or server errors (500–504). Retries use increasing delays until the request succeeds or the export stops.
  • Requests Per Hour: Set the maximum number of API requests GrowthLoop should send per hour. GrowthLoop staggers batches to stay within this limit. Examples:
    • 3600 = about one request per second
    • 360 = about one request every 10 seconds
    • 60 = about one request per minute

Leave Requests Per Hour blank for no rate limiting.


Output Schema

Use this section when you want to control which exported fields are sent and how they are typed before GrowthLoop builds request payloads.

  • Output Fields: Use the schema builder to choose which fields to include in the output. Only fields you add are sent. GrowthLoop coerces values to the types you define—for example, a string "99" can be sent as the number 99.

If you leave Output Schema blank, GrowthLoop sends the fields mapped during export without this extra filtering step.


Get/Create Audience

Use this section when your API has its own audience, list, or segment resource that must exist before members can be added or removed.

Get Audience

  • Get Audience Enabled: Turn on to have GrowthLoop check whether the audience already exists before syncing members.
  • Get Audience URL: The URL GrowthLoop calls to look up the audience. Supports Handlebars templates with {{audience_name}}, {{audience_id}}, and {{organization_name}}.
  • Get Audience HTTP Method: Choose GET or POST for the lookup request.
  • Get Audience Filter Path (JMESPath): Use this when the API returns a collection and you need to filter the response in GrowthLoop. For example, tables[?name=='{{audience_name}}']. If the filtered result is empty, GrowthLoop treats the audience as missing.

Create Audience

  • Create Audience Enabled: Turn on to create the audience when the get step does not find one. Requires Get Audience Enabled.
  • Create Audience URL: The URL GrowthLoop calls to create the audience. Supports the same Handlebars variables as the get URL.
  • Create Audience HTTP Method: Choose POST or PUT for the create request.
  • Create Audience Body Template: Handlebars template for the create request body. Available variables: {{audience_name}}, {{audience_id}}, and {{organization_name}}.

If you do not enable get/create audience, GrowthLoop skips these steps and sends add/remove requests using only the URLs configured below.


Add Configuration

Use this section to define how GrowthLoop sends records when audience members are added. Add URL is required.

  • Enabled: Turn off to ignore add actions during export. Enabled by default.
  • URL: The endpoint GrowthLoop calls when members are added to the audience.
  • HTTP Method: Choose GET, POST, PUT, PATCH, or DELETE for add requests.
  • Body Template (Handlebars): Template for the request body.
    • Individual batch mode: use {{user.field}} to reference one record at a time. Example: {"id": "{{user.id}}", "email": "{{user.email}}"}
    • Batched batch mode: use {{#each users}} to send multiple records in one request. Example: {"users": [{{#each users}}{"id": "{{id}}"}{{#unless @last}},{{/unless}}{{/each}}]}
  • Batch Mode:
    • Individual: GrowthLoop sends one request per record.
    • Batched: GrowthLoop sends multiple records in a single request.
  • Batch Size: Number of records per request when Batch Mode is Batched. Defaults to 100.
  • Response Success Path (JMESPath): Optional expression to read how many records succeeded from the API response. Examples:
    • records counts items in a records array
    • created counts items in a created array
    • success treats a boolean as all succeeded or all failed
    • num_records_imported uses a numeric field directly

If Response Success Path is blank, GrowthLoop treats all records in the request as successful when the API returns HTTP 2xx.

Remove Configuration

Use this section when your API supports removing audience members and you want GrowthLoop to call a separate endpoint for removals. Remove is disabled by default.

  • Enabled: Turn on to process remove actions during export.
  • URL: The endpoint GrowthLoop calls when members are removed from the audience.
  • HTTP Method: Choose GET, POST, PUT, PATCH, or DELETE for remove requests.
  • Body Template (Handlebars): Same Handlebars patterns as Add Configuration. Use {{user.field}} for individual requests or {{#each users}} for batched requests.
  • Batch Mode: Choose Individual or Batched, same as add configuration.
  • Batch Size: Number of records per request when batch mode is Batched. Defaults to 100.
  • Response Success Path (JMESPath): Optional expression to read how many removals succeeded. Examples include records, deleted, and success.

If Response Success Path is blank, GrowthLoop treats all records in the request as successful when the API returns HTTP 2xx.


Exporting to the destination

After you create the destination, you can export an audience to HTTP Endpoint.

  1. Navigate to the Audiences section in the left sidebar and open an existing audience or create a new one. (Click here to learn how!)
  2. Click Export Audience.
  3. In the Create Export view, search for your HTTP Endpoint destination and click Select.
  4. In the Export Settings tab, configure your desired Campaign Type and Export Schedule.
  5. In the Match Fields tab, map the identifiers your API expects:
    • Email
    • Unique Identifier
    • Client Customer ID
  6. Map any personalization or additional fields you want to include in the export payload. These fields are available in your Handlebars templates and output schema.
  7. Click Export.

GrowthLoop runs optional get/create audience steps first, then sends add and remove requests to the URLs configured on the destination. You can check export activity in the audience Exports tab within GrowthLoop.

Experiencing any issues connecting to HTTP Endpoint as a destination? Reach out to us at [email protected] and we'll be in touch shortly!