API integration guide
Overview
Section titled “Overview”This page is for development teams building or checking an API to be called by Connected Content. Give your marketers the API URL, request method, authentication method, and a sample response (JSON).
API requirements
Section titled “API requirements”| Item | Requirement |
|---|---|
| Scheme and port | http or https, standard ports (80, 443) only |
| Private networks | Internal networks and internal IPs can’t be called. The URL must be reachable from outside |
| URL | Up to 2048 characters after variables are filled in. Credentials can’t be included as user:pass@ (use a registered credential) |
| Redirects | 3xx responses aren’t followed. Use the final URL |
| Success | Only 2xx counts as success. 4xx and 5xx are treated as failures even if they have a body |
| Response time and size | Within 2 seconds, up to 1MB |
| Response format | A JSON object is recommended. Plain text also works |
| JSON response header | · To use JSON, always include Content-Type: application/json· Without the header, or with text/plain, the body is treated as text even if it’s JSON· If declared as JSON but the body isn’t JSON, it’s treated as a failure |
Outbound IPs and request headers
Section titled “Outbound IPs and request headers”FlareLane calls from fixed IPs. If you restrict access with a firewall, get the outbound IPs from your account manager and add them to your allowlist. Every call includes the headers below.
| Header | Value |
|---|---|
User-Agent | FlareLane-ConnectedContent/1.0 |
X-flarelane-connected-content-request-id | A unique ID for each request |
X-flarelane-connected-content-request-timestamp | Request time (ISO 8601) |
Call volume and duplicate requests
Section titled “Call volume and duplicate requests”- The number of calls isn’t the same as the number of recipients. A call is made per instruction, calls may repeat when processing is retried, and the cache may reduce them.
- An API used for bulk sends must handle more requests than there are recipients. Repeated 429 responses can trigger the circuit breaker.
- For APIs that create something on each call, such as issuing coupons, make sure a repeated request doesn’t create duplicates. For example, return the coupon that was already issued.
Find the cause in server logs
Section titled “Find the cause in server logs”When a call fails, the message only shows a blank. Check the response codes for FlareLane requests in your server logs (identified by User-Agent and the request ID header).
| Response code | What to check |
|---|---|
| 400 | Whether the body format matches what the API expects. For JSON, whether the recommended way of writing it was followed |
| 401 | Whether the credential values (ID, PW, Header value) are correct |
| 403 | Whether the outbound IPs are allowed, whether User-Agent is blocked, and whether the token has permission for that API |
| 404 | Whether the URL and the variable values in the path are correct |
| 405 | Whether :method matches the method the API accepts |
| 429 | Whether the rate limit was exceeded. If it repeats, it can trigger the circuit breaker |
| 5xx | A server error. Repeated 502, 503, or 504 responses can trigger the circuit breaker |