UTM Builder REST API

Send a POST to /wp-json/sunshine-utm/v1/links with a list of pages and the tags, and you get the tagged links back. It’s handy for spreadsheets, automation tools and your own scripts that need links spelled the same way as the ones made in WordPress.

The endpoint only answers requests from an administrator. An Application Password is the easiest way to log in from a script: make one under Users > Profile > Application Passwords and send it with basic authentication.

Example

curl -X POST https://yoursite.com/wp-json/sunshine-utm/v1/links \
  -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://yoursite.com/spring-sale/", "https://yoursite.com/blog/new-post/"],
    "source": "newsletter",
    "medium": "email",
    "campaign": "spring_sale",
    "shorten": true,
    "save": true,
    "name": "Spring sale newsletter"
  }'

What you can send

Field	What it does
urls	Required. A list of pages to link to.
source, medium, campaign, term, content	The tags. A source is required unless the preset has one.
preset	A preset’s ID. Its tags are used, and any tag you also send replaces the preset’s value.
params	Other parameters to add exactly as given, like {"ref": "partner"}.
shorten	true to make a short link for each link.
shortener	site (your own domain), bitly or rebrandly. Leave it out to use the Default from Settings.
save	true to keep the links as a batch under Saved Batches.
name	The batch name, when saving.

Tokens like {slug} and {date} work in any tag, the same as in the Bulk Builder. See presets and tokens.

What you get back

{
  "links": [
    {
      "url": "https://yoursite.com/spring-sale/",
      "tagged_url": "https://yoursite.com/spring-sale/?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale",
      "short_url": "https://yoursite.com/x8d89c",
      "extra_params": [],
      "url_ok": true,
      "url_status": "",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "spring_sale",
      "utm_term": "",
      "utm_content": ""
    }
  ],
  "count": 2,
  "skipped": [],
  "batch_id": 14
}

• tagged_url is the full link and short_url is the short one, when you asked for it.
• The tags are shown as they ended up after the formatting rules.
• skipped lists any line that wasn’t a full web address, and why.
• batch_id is the saved batch’s ID, or 0 when you didn’t save.

Limits and rules

• Up to 2,000 links per request.
• Bitly and Rebrandly work on up to 50 links per request. Short links on your own domain work on any number.
• Link checks don’t run through the API, even when they’re on in Settings.
• Team lists set to Only allow these apply here too. A link with a source or medium that isn’t on the list is left out and listed in skipped with the reason, and if every link is left out you get an error back.

To let an AI assistant make links instead of a script, see Let an AI assistant build your UTM links. The abilities there can also use social networks, every combination and CSV text, which this endpoint doesn’t.