API reference · Templates

Import brand from website

POSThttps://api.pidgely.com/brand/import

Scale plan. Reads your website and proposes a visual builder theme: logo candidates (stored by Pidgely and served from an absolute URL, as e-mails need), a palette ranked into roles with WCAG-checked button and link colors, fonts mapped to e-mail-safe stacks with Google Fonts, the company name, social profiles and postal address. Pass apply: true to save it as the organization default used by new builder templates and AI assist. Without url, the root site of your first verified sending domain is used.

Scale plan (403 plan_required otherwise). Fetches the website (public addresses only, every redirect re-checked, bounded sizes and timeouts) and proposes a builder theme and brand profile: logo candidates (stored and served from /files/brand/... so e-mails get absolute URLs), a palette ranked into roles with WCAG-checked button and link colors, fonts mapped to e-mail-safe stacks with Google Fonts, the company name, social profiles and postal address. With AI assist configured and included in the plan, Claude picks among the extracted candidates (it never sees the page); the heuristic result stands on its own. Nothing is saved unless apply is true. At most 6 imports per minute per organization.

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Body parameters

JSON object.

Name	Type	Required	Description
`url`	string	No	Website address (`acme.com` or `https://acme.com`). Defaults to the root site of the first verified sending domain.
`apply`	boolean	No	Save the proposed theme and brand profile as the organization's builder defaults. Default `false`.
`ai`	boolean	No	Let AI assist choose among the candidates when available (counts against the monthly AI quota). Default `true`.
`language`	string	No	Language of the AI rationale (BCP 47, e.g. `en`, `pt-br`, `es`). Default English.

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL

curl -X POST 'https://api.pidgely.com/brand/import' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://acme.com",
  "apply": false
}'

Response

200 OK

JSON

{
  "object": "brand_import",
  "url": "https://acme.com/",
  "name": "Acme",
  "logos": [
    {
      "url": "https://api.pidgely.com/files/brand/8kQ2v1fWbqzJcR0mT5yH3xLa9sPn6dEe.png",
      "source_url": "https://acme.com/logo.png",
      "source": "header",
      "content_type": "image/png",
      "width": 320,
      "height": 80,
      "transparent": true,
      "on_light": true,
      "on_dark": false,
      "email_safe": true,
      "colors": [
        "#2563eb"
      ],
      "score": 17.5
    }
  ],
  "colors": [
    {
      "hex": "#2563eb",
      "role": "primary",
      "score": 11.5,
      "sources": [
        "meta:theme-color",
        "css_var:--primary",
        "css:button",
        "logo"
      ]
    }
  ],
  "palette": {
    "primary": "#2563eb",
    "text": "#0f172a",
    "background": "#f2f4f9",
    "link": "#2563eb",
    "button_text": "#ffffff",
    "button_contrast": 5.17
  },
  "fonts": [
    {
      "family": "Poppins",
      "role": "body",
      "google": true,
      "fallback": "system",
      "source": "css"
    }
  ],
  "socials": [
    {
      "network": "x",
      "url": "https://x.com/acme"
    },
    {
      "network": "github",
      "url": "https://github.com/acme"
    }
  ],
  "address": "500 Market St, San Francisco, CA 94105, US",
  "theme": {
    "brand_color": "#2563eb",
    "text_color": "#0f172a",
    "background_color": "#f2f4f9",
    "content_color": "#ffffff",
    "button_text_color": "#ffffff",
    "font": "system",
    "web_font": "Poppins",
    "content_width": 600,
    "radius": 8,
    "logo_url": "https://api.pidgely.com/files/brand/8kQ2v1fWbqzJcR0mT5yH3xLa9sPn6dEe.png",
    "logo_width": 160,
    "logo_alt": "Acme",
    "logo_align": "left"
  },
  "brand": {
    "name": "Acme",
    "website": "https://acme.com/",
    "address": "500 Market St, San Francisco, CA 94105, US",
    "socials": [
      {
        "network": "x",
        "url": "https://x.com/acme"
      },
      {
        "network": "github",
        "url": "https://github.com/acme"
      }
    ],
    "imported_from": "https://acme.com/"
  },
  "ai": {
    "used": true,
    "rationale": "Blue from the buttons, the theme color and the logo; dark slate for body text."
  },
  "warnings": [
    "logo_not_on_dark"
  ],
  "applied": false
}

Response fields

Name	Type	Required	Description
`object`	string	Yes	Object type. One of `brand_import`.
`url`	string	Yes	Final URL after redirects.
`name`	string	Yes	Display name.
`logos`	object[]	Yes	Stored logo candidates, best first.
`logos[].url`	string	Yes	Public, absolute URL of the stored file (use it in e-mails).
`logos[].source_url`	string	No	—
`logos[].source`	string	Yes	One of `header`, `img`, `inline_svg`, `json_ld`, `apple_touch_icon`, `icon`, `manifest`, `og_image`.
`logos[].content_type`	string	Yes	—
`logos[].width`	integer	Yes	—
`logos[].height`	integer	Yes	—
`logos[].transparent`	boolean	Yes	—
`logos[].on_light`	boolean	Yes	Reads on a light background.
`logos[].on_dark`	boolean	Yes	Reads on a dark background.
`logos[].email_safe`	boolean	Yes	Raster image every e-mail client shows (SVG is not shown by Gmail or Outlook).
`logos[].colors`	string[]	Yes	—
`logos[].score`	number	Yes	—
`colors`	object[]	Yes	Candidate colors, merged and ranked.
`colors[].hex`	string	Yes	—
`colors[].role`	string	Yes	One of `primary`, `accent`, `text`, `background`, `other`.
`colors[].score`	number	Yes	—
`colors[].sources`	string[]	Yes	—
`palette`	object	Yes	—
`palette.primary`	string	Yes	—
`palette.accent`	string	No	—
`palette.text`	string	Yes	—
`palette.background`	string	Yes	—
`palette.link`	string	Yes	Primary darkened when needed to reach 4.5:1 on white.
`palette.button_text`	string	Yes	—
`palette.button_contrast`	number	Yes	WCAG contrast ratio of the button label on the primary color.
`fonts`	object[]	Yes	—
`fonts[].family`	string	Yes	—
`fonts[].role`	string	Yes	One of `body`, `heading`, `other`.
`fonts[].google`	boolean	Yes	—
`fonts[].fallback`	string	Yes	—
`fonts[].source`	string	Yes	—
`socials`	object[]	Yes	—
`socials[].network`	string	Yes	—
`socials[].url`	string	Yes	Public `https` URL that receives the events.
`address`	string	Yes	Email address.
`theme`	object	Yes	Global look of a builder e-mail. Colors are hex (`#rrggbb`).
`theme.brand_color`	string	No	—
`theme.text_color`	string	No	—
`theme.background_color`	string	No	—
`theme.content_color`	string	No	Background of the content card.
`theme.link_color`	string	No	—
`theme.font`	string	No	One of `system`, `inter`, `helvetica`, `georgia`, `verdana`, `trebuchet`.
`theme.content_width`	integer	No	Between 480 and 800.
`theme.radius`	integer	No	Between 0 and 32.
`theme.logo_url`	string	No	—
`theme.logo_width`	integer	No	—
`theme.logo_alt`	string	No	—
`theme.logo_align`	string	No	One of `left`, `center`, `right`.
`theme.logo_dark_url`	string	No	Logo variant shown in dark mode by clients that support it (Apple Mail, iOS); others keep `logo_url`.
`theme.button_text_color`	string	No	Label color of buttons on the brand color; empty picks white or near-black automatically.
`theme.web_font`	string	No	Google Fonts family loaded where e-mail clients support web fonts; `font` is the fallback stack.
`theme.heading_font`	string	No	Heading stack (empty = `font`). One of `system`, `inter`, `helvetica`, `georgia`, `verdana`, `trebuchet`.
`theme.heading_web_font`	string	No	Google Fonts family for headings (empty = `web_font`).
`brand`	object	Yes	The organization's identity used by AI assist (sender name, links, footer) and the brand import.
`brand.name`	string	No	Display name.
`brand.website`	string	No	—
`brand.address`	string	No	Postal address shown in footers.
`brand.socials`	object[]	No	—
`brand.socials[].network`	string	Yes	One of `x`, `linkedin`, `instagram`, `facebook`, `youtube`, `github`, `tiktok`, `discord`, `website`.
`brand.socials[].url`	string	Yes	Public `https` URL that receives the events.
`brand.imported_from`	string	No	Page the brand was imported from.
`ai`	object	Yes	—
`ai.used`	boolean	Yes	—
`ai.rationale`	string	No	—
`ai.skipped`	string	No	Why AI was not used (disabled, plan, quota, error, invalid).
`warnings`	string[]	Yes	—
`applied`	boolean	Yes	—

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status	Name	When
401	`missing_api_key`, `restricted_api_key`	No `Authorization: Bearer` header, or a `sending_access` key called an endpoint that needs `full_access`.
403	`invalid_api_key`, `validation_error`	The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
422	`validation_error`	A field is missing or invalid; `message` names it.
429	`rate_limit_exceeded`	Too many requests per second. Wait for `Retry-After` seconds.
403	`plan_required`	The organization is not on the Scale plan.
422	`brand_url_forbidden`	The address is private or internal (localhost, 10.0.0.0/8, metadata services...) or uses a port other than 80/443.
422	`brand_fetch_failed`	The site could not be loaded: DNS, timeout, HTTP error or not an HTML page.
429	`rate_limit_exceeded`	More than 6 imports per minute.

Import brand from website

#Body parameters

#Request

#Response

#Response fields

#Errors

Body parameters

Request

Response

Response fields

Errors