Other Endpoints

For more complex 3rd party integrations or custom middleware we also expose the following additional endpoints for your use.

Fetch Current Organization

GET https://api.heypoplar.com/v1/me

This endpoint will return the Organization associated with your access token. It is intended to be used when testing connectivity and the validity of an access token.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Returns organization name

{
	"id": "478086b3-bf5e-42a3-9ecc-b539f0b4f71a",
	"name": "Acme Corporation",
	"mode": "production"
}

Fetch Active Campaigns

GET https://api.heypoplar.com/v1/campaigns

This endpoint will return any active campaigns.

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Returns a list of all active campaigns

[
    {
        "id": "25358f3d-121e-4b07-b2fa-4ed8c7054ac1",
        "name": "Prospecting USA 2023"
    }
]

Fetch Campaign

GET https://api.heypoplar.com/v1/campaign/:id

This endpoint will return the details of a given campaign. It may be used to validate that a provided campaign ID is valid.

Path Parameters

Name	Type	Description
id*	string	Campaign ID

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Returns campaign details

{
    "id": "25358f3d-121e-4b07-b2fa-4ed8c7054ac1",
    "name": "Prospecting USA 2023"
}

Fetch Campaign Creatives

GET https://api.heypoplar.com/v1/campaign/:id/creatives

This endpoint returns a list of active creatives belonging to a campaign

Path Parameters

Name	Type	Description
ID*	string	Campaign ID

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Returns a list of active creatives

[
    {
        "id": "eb822983-eb13-43a1-a192-f97e0edec138",
        "name": "Creative 1",
        "mail_type": "USPS First Class",
        "creative_type": "6x9 Postcard",
        "merge_tags": {},
        "thumbnail_url": "https://app.heypoplar.com/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCSkdrRFFRPSIsImV4cCI6bn.png",
        "default": false,
        "format": "PDF",
        "image_formats": "PDF"
    }
]

Fetch Campaign Mailings

GET https://api.heypoplar.com/v1/campaign/:id/mailings

This endpoint can be used to fetch all mailings belonging to a campaign.

Since there are typically a large number of mailings associated with a campaign, this endpoint is paginated. Please refer to the following HTTP headers on the response which provide information around the number of mailings and pages, and pay attention to our rate limits when fetching mailings from the API.

Response Headers:

X-Total - the total number of mailings

X-Total-Pages - the total number of pages

X-Page - the current page

X-Per-Page - the number of results per page

X-Next-Page - the next page

X-Prev-Page - the previous page

Path Parameters

Name	Type	Description
id*	string	Campaign ID

Query Parameters

Name	Type	Description
page	number	The page of mailings to be returned
per_page	number	The number of mailings to be returned per page default: 5 maximum: 100
start_date	string	ISO8601 formatted start date time to limit mailings created after Example 2021-01-16T10:30:00
end_date	string	ISO8601 formatted end date time to limit mailings created before Example 2021-02-19T18:30:00
	String

Headers

Name	Type	Description
Authorization*	string	Bearer ProductionAccessToken

200: OK Returns a list of mailers under the campaign

[
    {
        "id": "a1a95b49-eb93-4bee-a3b2-f7b4ee6d87d4",
        "campaign_id": "aef13242-e4a9-4494-857f-2acc1c3337f6",
        "creative_id": "c4b37e00-9163-4b4e-be3e-65fea6f5a165",
        "merge_tags": {},
        "state": "delivered",
        "front_url": "https://assets.heypoplar.com/path/to/front.jpg",
        "back_url": "https://assets.heypoplar.com/path/to/back.jpg",
        "pdf_url": "https://assets.heypoplar.com/path/to/preview.pdf",
        "total_cost": "0.65",
        "created_at": "2021-07-26T19:02:15Z",
        "address": {
            "name": "John Doe",
            "company": "Share Local Media",
            "address_1": "123 Main Street",
            "address_2": "Suite 2",
            "city": "New York",
            "state_name": "NY",
            "postal_code": "10004"
        }
    }
]