How to setup a Flow so that other platforms can trigger it.
Before creating a flow that can be triggered by API, you'll need to create an API connection. Complete that first, before following the steps below.
1. Select Flows from the left side menu and click 'New Flow', then click 'Start Sending' in the API Connection tile.
2. First give your Flow a name that will make easy to identify.
3. Click "define your first trigger." Ensure "API Connection" is the event source and select "Send to Customer" to initiate your flow via an API call:
4. To configure your external platform to trigger this flow, use the specific URL associated with this flow and trigger configuration.
Click the "API Connection Event" text in the trigger block (as shown above) to open a details panel. You can easily copy the URL by clicking the clipboard icon next to the URL. (Or alternatively, highlight and copy the URL shown in the field.)
From here, you can continue to set up the rest of the flow.
Note: You need to add a send block to your flow before it will send anything to your customers!
(For more details on flows in general, please see this help article.)
Calling the "Send to Customer" Endpoint
While clients vary, in general, you'll need to configure your system to make a POST call to the URL.
(Because the URL is write-only, and includes an obfuscated link, API calls to this endpoint do not require authentication or any custom headers.)
The endpoint requires a JSON body with sufficient attributes to allow creation and mailing of a postcard to a recipient:
- reference_id (string), required, a unique identifier for the recipient. (Often, recipient email address is utilized for this.)
- firstname and lastname (string), OR fullname (string), OR company (string); one and only one of these three elements is required.
- email (string), optional
- line1 (string), required
- line2 (string), optional
- city (string), required
- state (string), required, must be a standard USPS two-character state abbreviation.
- postal_code (string), required
- country (string), required, must be a standard ISO 3166 two-character country code. (I.e., "US" for the USA.) (This can always be provided as a fixed value of "US" if sending only to recipients in the United States.)
Remember that when initially creating and testing your new webhook, you can utilize the API Logs screen available in the API connection area of the PostPilot app to quickly troubleshoot activity!