Populr Developers

API

Integrating with Populr's REST API makes it easy to automatically generate and publish pops, manage assets, domains, and more.




Getting Started

Authentication

The Populr.me API allows you to automate the creation and distribution of pops within your account. You authenticate to the Populr.me API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret! Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Note: The API is not designed to enable the creation of third-party applications which authenticate as Populr.me users on their behalf.

Libraries

We've written adapters for popular languages that make it easy to use Populr's REST API within your application. Click the links below for more information: Need an adapter for a language you don't see here? You can use the REST API below from virtually any language, and we're working to create more native libraries. Reach out to Populr support and let us know what you need.

Common Responses

Populr.me uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Populr.

200 OK - Everything worked as expected.

400 Bad Request - Often missing a required parameter.

401 Unauthorized - No valid API key provided.

402 Request Failed - Parameters were valid but request failed.

404 Not Found - The requested item doesn't exist.

500, 502, 503, 504 Server errors - something went wrong on Stripe's end.

Each error includes a standard set of attributes, including an error_type and a human-readable error string. These are designed to make debugging easier and allow for differentiated handling of scenarios that produce the same HTTP status code.

If you request an endpoint that does not exist, you will receive:

Status 404: Not Found

{"error":"You have reached the Populr.me API, but we do not understand how to service your request.","error_type":"request.not_found_api"}

If you reach the API but your request cannot be completed due to a validation error, missing parameter, or other command-specific problem, you will receive:

Status 400

{"error":"You must provide a pop_id","error_type":"request.validation"}

See the bottom of this document for a list of error_types that can be returned and a list of the associated error messages


Creating and Publishing Pops

Using the Populr API, you can create and publish pops based on templates you've set up in your account. It's important to note that you cannot create arbitrary pops - Populr provides best-in-class tools for designing one-pagers, and we've decided not to expose an API for that design process. Using our template system, your business can define beautiful one-pagers that you can programatically fill with content and deliver. The templates are defined on the Populr.me website, making it easy for non-technical members of your team to update the visual style of your pops.

Creating a Pop API Template

  1. Go to Populr.me and sign in to your account.

  2. Visit the Group Settings page for your team and enable API Access.

  3. Create a new pop.

  4. Add content and design the pop to match your needs.

  5. Return to your pops page and turn your new pop into an API template by clicking the pop's name and selecting 'Make API Template.'

  6. Type anywhere to define a variable you can replace from the API.

  7. Edit an asset region and check the "API Region" checkbox to add images or documents from the API.

Using a Pop API Template

  1. Submit one or more POST requests to upload documents, images, etc…

  2. Submit a POST request to create a new pop based on your template

  3. Submit a POST request to publish the pop.

You can create a variety of Pop templates to meet the needs of your business. Need a more flexible solution? Contact Populr.me sales at sales@populr.me



Pop Model

Throughout the REST API, the structure below is used to represent a pop. An example is shown below, along with an explanation of what each key in the JSON is used for. 
{
    "_id": "0abcde12bcda1", 
    "template_id": "12qwef",
    "name": "Pop Name",
    "title": "Pop Page Title",
    "label_names": ["label_a", "label_b"],
    "password": "1234",
    "tracers": [{
        <tracer models>
    }],
    "published_pop_url": "http://account-name.populr.me/page-slug",
    "domain": "generic",
    "password": nil,
    "created_at": '2013-02-05T22:57:00Z',
    "unpopulated_api_tags": [ 'TITLE', 'ipsum' ],
    "unpopulated_api_regions": {
      "profile_picture_region": {"type":"image"},
      "venue_map_region": {"type":"embed"}
    }
    "custom_links": [
      "http://blogger.com/my-company"
    ],
    "custom_code": "
My Google Analytics Code
",
    "background_image_asset_id": "0abcddae12bc1",
    "clone_link_enabled": true,
    "clone_link_url": "https://populr.me/clone/0abcde12bcda1/123fwer324",
    "collaboration_link_enabled": true,
    "collaboration_link_url": "https://populr.me/collaborate/0abcde12bcda1/fdsf341f",
    "collaboration_interstitial_text": "Please finish editing your pop!".
    "collaboration_webhook": "http://myserver.com/collaborator_left",
}

name: The name of the pop that appears on the pops list page.

title: The title of the published pop web page. This generally appears at the top of the pop, but some themes remove the title region.

label_names: An array of string labels which can be used to filter pops on the pops list.

password: A password that is required for users to view the published pop.

tracers: Custom links to the pop that allow views, clicks, and other metrics to be tracked on a more granular basis. Must be created using one of the tracer API calls.

published_pop_url: The URL of the published pop, or null if the pop has not been published.

domain: The domain where the pop is hosted. When assigning a domain, you must choose one that has already been setup within your Populr.me account.

unpopulated_api_tags: An array of API tags that were defined in the pop template and have not been populated with content.

unpopulated_api_regions: A hash of API regions which are currently empty in the pop and can be populated with assets. Each key is a region ID. The type property associated with each key is important. Regions may only be filled with assets of the expected type.

custom_links: An array of custom links that you would like to add to the default links (if any). These are the links you create in the Options dropdown within the Populr editor.

custom_code: Freeform code that will be inserted at the very end of your pop. Often used to insert Google Analytics or other tracking functionality into pops.

background_image_asset_id: The ID of the pop's background image. To change the pop's background image, add a new image to the background_images collection and then set the pop's background_image_asset_id to that asset's ID.

clone_link_enabled: Set to true if you'd like this pop to be cloneable. After saving, the clone_link_url will contain a valid URL.

clone_link_url: A full URL that one or more users can click to create their own copy of the pop. Users will be prompted to sign up or sign in to a Populr.me account.

collaboration_link_enabled: Set to true if you'd like to enable the user to contribute to the Pop in the Populr.me editor, while you retain ownership of the pop. After saving, the collaboration_link_url will contain a valid URL. Set to false to invalidate any collaboration links you've given out. Users who have already clicked the collaboration link can continue to edit the pop as often as they wish. It's important to note that collaborators cannot access pop revisions, publish the pop, or access analytics.

collaboration_link_url: A full URL that one or more users can click to edit the pop without it being transferred to their account. Users will be prompted to sign up or sign in to a Populr.me account.

collaboration_interstitial_text: When new users click a collaboration link, they'll be prompted to create a Populr.me account or sign in. The interstitial text is displayed on that page so that you can provide your users with more context.

collaboration_webhook: A webhook that will receive a POST with the pop JSON when the user has finished collaborating.


API Calls

GET http://api.populr.me/v0/templates?count=50&offset=100

Fetch a list of the templates you've created on Populr.me. Using a template_id, you can instantiate new pops.

GET http://api.populr.me/v0/templates/:id/pops?count=50&offset=100

Fetch a list of the pops created from a particular template.

GET http://api.populr.me/v0/pops?count=50&offset=100

Fetch a set of existing pops from your account. Note that this endpoints returns all the pops in your account. To fetch the pops created with a specific template, use /templates/:id/pops.

POST http://api.populr.me/v0/pops

Creates a new, unpublished pop based on the template with ID template_id. Populates the tags and with the content provided, and places two image assets in the region called image_region_a.

{
  "pop": {
    "template_id": "12qwef",
    "name": "Node Pop",
    "title": "My New Pop",
    "label_names": ["a", "b", "c"],
    "password": "1234"
  },

  "populate_tags": {
    "first_name": "Ben",
    "last_name": "Gotow"
  },

  "populate_regions": {
    "image_region_a": [<Image Asset ID>, <Image Asset ID>],
    "document_region_a": <Document Asset ID>,
  }
}

Response:

{
  _id: '51536c6add02dc42d9000005',
  title: 'My New Pop',
  created_at: '2013-03-27T22:02:18Z',
  domain: null,
  name: 'Node Pop',
  password: '1234',
  published_pop_url: '' ,
  label_names: ["a", "b", "c"],
  unpopulated_api_tags: ["city"],
  unpopulated_api_regions: {"document_region_b": {"type":"embed"}}
}

PUT http://api.populr.me/v0/pops/:id

Updates the pop with a new title, fills in the tag, and adds a document to document_region_b.

{
  "pop": {
    "title": "New Title",
  },

  "populate_tags": {
    "city": "Blacksburg"
  },

  "populate_regions": {
    "document_region_b": "12346",
  }
}

Failed Response:

{
  "error_type":"request.validation",
  "error": "You must pass a valid asset ID for each asset you plan to populate (evaluating '12346' for document_region_b)"
}

Successful Response:

{ 
  _id: '51536c6add02dc42d9000005',
  title: 'New Title',
  created_at: '2013-03-27T22:02:18Z',
  domain: null,
  name: 'Node Pop',
  password: '1234',
  published_pop_url: '' ,
  label_names: ["a", "b", "c"],
  unpopulated_api_tags: [],
  unpopulated_api_regions: {}
}

DELETE http://api.populr.me/v0/pops/:id

Deletes the pop permanently. This action cannot be undone.

POST http://api.populr.me/v0/pops/:id/publish

Publishes the pop, making it available on the web. Returns the pop JSON, with published_pop_url defined.

POST http://api.populr.me/v0/pops/:id/unpublish

Unpublishes the pop, taking down the page from the web immediately and rendering tracers unusable. Returns the pop JSON.



Tracers & Analytics

Tracers allow you to track interactions with a published pop. Each pop can have multiple tracers, and each tracer has a code which must be appended to the pop URL.

Tracer Model

{
    "code": "tc",
    "name": "Twitter",
    "notify_on_open": true,
    "notify_webhook": "http://api.mysite.com/pop_was_opened/%{pop-id}",
    "analytics": {
        "views": 6,
        "clicks": 24,
        "links": {
            "http://www.populr.me/": {
                "clicks": 4
            }
        },
        "assets": {
            "unnamed_region_0": {
                "132213ae12bc1312": {
                    "clicks": 10
                }
            },
            "my_image_region": {
                "132213ae21f4812f": {
                    "clicks": 10
                },
                "f48121f48121f421": {
                    "clicks": 3
                }
            }
        }
    }
}

name: The name of the tracer that appears on the tracer list page. Tracers with email addresses as names will automatically be categorized under the email section of the Populr analytics dashboard.

code: An autogenerated code that is appended to the pop URL

analytics: Data collected as users interact with the published pop. Allows you to retrieve information about clicks on particular assets or links. Items which have not been clicked do not appear.

notify_on_open: Set to true to enable the webhook.

notify_webhook: A URL that Populr will POST to when the tracer URL is viewed. You can include the arguments %{pop-id} and %{tracer-id} in the URL. The URL will be hit 15 minutes after the first view and hit again hourly as long as the pop continues to be viewed. The trigger is deactivated once it has been fired more than a dozen times. The following JSON is posted:

"group": {
    "id": <Your Populr Group's ID>,
    "name": <Your Populr Group's Name>
},
"pop": {
    "id": <Pop ID>,
     "name": <Pop Name>,
     "title": <Pop Title>,
     "slug": <Pop Slug>,
     "domain": <Pop Domain>,
     "published_pop_url": <URL>,
     "created_at": <Timestamp>,
},
"tracer": {
    "name": "Twitter"
    "code": "tc",
    "analytics": {
        "views": 6,
        "clicks": 24,
        "links": {
            "http://www.populr.me/": {
                "clicks":4
            }
        },
        "assets": {
            "unnamed_region_0": {
                "132213ae12bc1312": {
                    "clicks": 10
                },
            }
            "my_image_region": {
                "132213ae21f4812f": {
                    "clicks": 10
                },
                "f48121f48121f421": {
                    "clicks": 3,
                }
            }
        }
    }
}


POST http://api.populr.me/v0/pops/:id/tracers

{
    "name": "tracer_for_recipient_1",
    "notify_on_open": true,
    "notify_webhook": "http://www.mysite.com/pop_opened/%{pop-id}"
}

Response:

{
    "_id": '51536c6add02dc42d9000005',
    "name": "tracer_for_recipient_1",
    "notify_on_open": true,
    "notify_webhook": "http://www.mysite.com/pop_opened/%{pop-id}",
    "analytics": {
        "views": 0,
        "clicks": 0
    }
}

GET http://api.populr.me/v0/pops/:id/tracers/:tracer_id

{
}

Response:

{
    "_id": '51536c6add02dc42d9000005',
    "name": "tracer_for_recipient_1",
    "notify_on_open": true,
    "notify_webhook": "http://www.mysite.com/pop_opened/%{pop-id}",
    "analytics": {
        "views": 6,
        "clicks": 2
    }
}



Assets

You can add assets to your API templates directly on the Populr website. However, many uses of the API require adding custom documents and images to each pop that is generated. Attaching an asset to a pop is a two-step process. First, upload the asset using one of the POST methods below. Then create (or update) a pop with the new asset's id in the assets hash.

Asset Model

{
    _id: '51536582dd02dcccf9000004',
    description: null,
    link: null,
    title: '',
    asset_id: '51536582dd02dcccf9000004',
    upload_identifier: null,
    source_html: '...only in embeds...'
}

POST http://api.populr.me/v0/documents

POST http://api.populr.me/v0/images

POST http://api.populr.me/v0/background_images

POST http://api.populr.me/v0/embeds

To upload a new image or document asset, make a multi-part/form POST with the following keys:

file: An image or document file attached to the form post.

title: (Optional) The title that should be displayed within the asset list.

link: (Optional) For images, an optional href for the image once placed in a pop.

To upload a new embed asset, make a JSON POST with the following keys:

source_html: HTML that you want to display within the pop. For best results, use HTML that has a flexible width, or both a fixed width and height.

title: (Optional) The embed title that should be displayed when viewing the embed in the asset list.

description: (Optional) A description that is displayed in the editor.


DELETE http://api.populr.me/v0/documents/:id

DELETE http://api.populr.me/v0/images/:id

DELETE http://api.populr.me/v0/background_images/:id

DELETE http://api.populr.me/v0/embeds/:id



Domains

You can attach one or more domains to your Populr account. By default, published pops are available at a subdomain of populr.me, such as http://myaccount.populr.me/my-page. By pointing a domain at Populr and registering it with your account, you can publish pops to that domain as well.

For more information about setting up custom domains, check out the Populr.me documentation.

GET http://api.populr.me/v0/domains

A list of the domains attached to your Populr.me account. The list always includes at least one item, which is the default domain.

[
   "mygroup.populr.me",
   "www.apple.com"
]

POST http://api.populr.me/v0/domains

domain: The domain to add to your account, such as www.mysite.com, pops.mysite.com, or mysite.com. The domain should already be pointing at Populr's IP address. If the domain is not mis-formatted, not pointing at Populr, or already in use within another Populr group, you'll receive a 400 response with an error.

DELETE http://api.populr.me/v0/domains

domain: The domain to delete from your account. Must match one of the options returned from the listing request.

Request Error Types

General

illegial_asset_type: You attempted to place an invalid asset of type %{value} within a pop. Acceptable types are %{extra}.

domain_not_available: The domain %{value} is not attached to your account. Available options are %{extra}.

missing_param: "Please provide a value for %{value}."

region_not_found: "The region %{value} could not be found in the pop. Available regions are: %{extra}"

tag_not_found: "The tag %{value} could not be found in the pop. Available tags are: %{extra}"

not_fully_populated: "The pop you are trying to publish contains unfilled %{value}: %{extra}."

invalid_webhook_url: "The webhook URL you provided (%{value}) cannot be used. It must be a valid URL, and the only allowed arguments are 'id' (or 'pop-id') and 'tracer-id'"

file_upload_required: "You must submit a multi-part form POST with a 'file' key to create an asset."