# Import brand from website

> 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…

Source: https://docs.pidgely.com/api-reference/templates/import-brand/

`POST https://api.pidgely.com/brand/import`

Scale plan. Reads your website and proposes a [visual builder](https://docs.pidgely.com/guides/templates/#import-your-brand-from-your-website) 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](https://docs.pidgely.com/sdks/) yet; call it over HTTP.

```bash tab="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](https://docs.pidgely.com/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. |