Zeplin

Open your browser and go to `app.zeplin.io`. Log in with your Zeplin account. Click your avatar or profile picture in the top-right corner to open the profile menu, then click **Profile**. On the Profile page, scroll down to find the **Developer** section (or click the **Developer** tab in the left sidebar if your Zeplin version shows one). Click **Personal Access Tokens** → **Create new token**. Give the token a name like `Bubble Integration` so you can identify it later. Zeplin does not let you choose specific scopes for Personal Access Tokens — the token grants read access to all projects and organisations your account has access to. Click **Create**. Zeplin shows you the token value once and only once — copy it immediately and store it in a password manager or a secure note. You cannot view this value again after leaving the page; if you lose it, you will need to delete the token and create a new one. Important security note: a Zeplin Personal Access Token does not expire, but it grants access to ALL projects on your account. For a production Bubble integration, use a dedicated Zeplin service account (a separate Zeplin user account with only the necessary projects shared to it) rather than your main designer account. This limits exposure if the token is ever compromised.

In your Bubble app editor, click **Plugins** in the left sidebar. If the API Connector plugin (by Bubble) is not already installed, click **Add plugins** → search for **API Connector** → click **Install**. The plugin is free. Click the API Connector row to open its settings. Click **Add another API**. In the **API Name** field, type **Zeplin**. In the **Base URL** field, enter: `https://api.zeplin.dev/v1` Now add the authentication header. Click **Add a shared header**: - Key: `Authorization` - Value: `Bearer ` followed by the Personal Access Token you copied in Step 1 (format: `Bearer zeplin_at_...`) - Tick the **Private** checkbox immediately — this is the most important action in this step. The Private flag prevents your Zeplin token from being included in any data sent to the browser. Without it, a technically savvy user could extract the token from a network request and access your entire Zeplin account. Double-check: the Authorization header value starts with `Bearer ` (with a space), followed by the token. The Private checkbox is ticked. The base URL ends in `/v1` with no trailing slash. Your Zeplin API group is now configured. All calls you add to this group will automatically include the Authorization header.

1{
2  "api_group": "Zeplin",
3  "base_url": "https://api.zeplin.dev/v1",
4  "shared_headers": [
5    {
6      "key": "Authorization",
7      "value": "Bearer <private>",
8      "private": true
9    }
10  ]
11}

Inside the Zeplin API group, click **Add a call** to create your first endpoint call. **Call 1 — List Projects:** Set the method to **GET** and the path to `/projects`. Set **Use as** to **Data (list)**. Click **Initialize call** — Bubble sends the GET request to `https://api.zeplin.dev/v1/projects` and reads the response. You will see a JSON array where each item has fields like `id`, `name`, `description`, `platform`, `thumbnail`. Bubble maps these automatically. If your Zeplin free plan only has 1 project, you will see a single-item array — that is fine for initialization. **Call 2 — List Screens for a Project:** Click **Add a call** again. Set the method to **GET**. In the path field, enter `/projects/[projectId]/screens`. Click the `[projectId]` portion — Bubble turns it into a parameter field. Name the parameter `projectId`. Set **Use as** to **Data (list)**. For initialization, you need a real project ID: copy one from the response you got in Call 1 (find the `id` field of a project). Paste it as the test value for `projectId`. Click **Initialize call**. The response will include screen objects with fields like `id`, `name`, `image` (containing a `thumbnails` sub-object with `small` and `large` image URLs), and `created`. Bubble maps all of these. The thumbnail URLs point to Zeplin's CDN — they are publicly accessible HTTPS image URLs that Bubble's Image elements can load directly without any proxying. **Call 3 — Verify token (optional):** Add a GET call at path `/users/me` (Use as: Data). Initialize it. If it returns your profile, your token is valid. You can use this call to show 'Connected as: [Zeplin username]' in your Bubble app's settings panel.

1{
2  "calls": [
3    {
4      "name": "List Projects",
5      "method": "GET",
6      "path": "/projects",
7      "use_as": "Data (list)",
8      "example_response_item": {
9        "id": "5f8a3c2e1a2b3c4d5e6f7g8h",
10        "name": "Mobile App v2",
11        "description": "Redesign 2026",
12        "platform": "ios",
13        "thumbnail": "https://img.zeplin.io/..."
14      }
15    },
16    {
17      "name": "List Screens",
18      "method": "GET",
19      "path": "/projects/{projectId}/screens",
20      "parameters": [
21        { "key": "projectId", "value": "<your-project-id>" }
22      ],
23      "use_as": "Data (list)",
24      "example_response_item": {
25        "id": "screen_abc123",
26        "name": "Home Screen",
27        "image": {
28          "thumbnails": {
29            "small": "https://img.zeplin.io/thumbnail_small.png",
30            "large": "https://img.zeplin.io/thumbnail_large.png"
31          }
32        },
33        "created": 1748000000
34      }
35    }
36  ]
37}

Now wire the Zeplin API data to your Bubble UI. You will build a two-level browsing experience: a project list page and a screen gallery that appears when a project is selected. In your Bubble editor, create a new page called `design-portal`. From the element toolbar, drag in a **Repeating Group**. Click it to open properties. Set **Type of content** to **Zeplin List Projects** (Bubble auto-created this type from the initialization). Set **Data source** to **Get data from an external API → Zeplin - List Projects**. No parameters needed. Inside the Repeating Group's first cell, add: - A **Text** element bound to `Current cell's Zeplin List Projects → name` - An **Image** element bound to `Current cell's Zeplin List Projects → thumbnail` - A **Button** labelled 'View Screens' Now create a second Repeating Group on the same page (or a separate screen). Set its **Type of content** to **Zeplin List Screens** and its **Data source** to **Get data from an external API → Zeplin - List Screens**, with `projectId` set to a page URL parameter or a custom state that stores the selected project ID. Inside the Screens Repeating Group cell, add: - An **Image** element bound to `Current cell's Zeplin List Screens → image - thumbnails - small` - A **Text** element bound to `Current cell's Zeplin List Screens → name` For the button 'View Screens' on the project row: add a workflow — **Element Actions → Set state → page's custom state 'selected_project_id' = Current cell's project id**. Then show the screens Repeating Group (which reads from that custom state as its projectId parameter) and hide the projects Repeating Group. Preview the page. You should see your Zeplin projects listed with thumbnails. Clicking 'View Screens' on any project shows that project's screens as a thumbnail gallery.

The client portal is more valuable when clients can take action on what they see. This step adds a feedback form to each screen thumbnail so clients can leave comments and mark screens as approved — all stored in Bubble's database. First, create a new Bubble data type called **ScreenFeedback** with these fields: - `screen_id` (text) — Zeplin's screen ID - `screen_name` (text) — the screen's name for display - `project_id` (text) — the Zeplin project ID - `client_name` (text) — who left the feedback - `comment` (text) — the feedback text - `status` (option set: Pending / Approved / Needs Revision) - `created_date` (date) Go to **Data → Privacy** and add a privacy rule for ScreenFeedback: set it so that only logged-in users can see their own organisation's feedback records (or configure as appropriate for your app's auth setup). Without a privacy rule, all records are visible to all Bubble users by default. Back on the design-portal page, inside the Screens Repeating Group cell, add a **Popup** element or an expandable group that appears on screen click. Inside it, add: - A **Text** element: `Current cell's Zeplin List Screens → name` - An **Image** element: `Current cell's Zeplin List Screens → image - thumbnails - large` - A **Text Input** element for client comments - A **Dropdown** element with options Pending / Approved / Needs Revision - A **Button** labelled 'Submit Feedback' For the Submit Feedback button's workflow: 1. Step 1 → **Data (Things) → Create a new ScreenFeedback** with: - `screen_id` = Current popup's screen ID custom state - `screen_name` = current screen name - `project_id` = page's selected_project_id custom state - `comment` = Input's value - `status` = Dropdown's value - `created_date` = Current date/time 2. Step 2 → **Element actions → Reset relevant inputs** (clear the form) 3. Step 3 → **Element actions → Hide popup** RapidDev's team has built client-portal workflows exactly like this for design agencies — if you need help wiring up email notifications when a client leaves feedback, or building a consolidated approval status view for the design team, book a free scoping call at rapidevelopers.com/contact.

Complete the portal by showing each screen's current approval status alongside its thumbnail and building a designer summary view showing overall handoff progress. In the Screens Repeating Group cell (alongside the thumbnail and screen name), add a text element for status. Set its data source to: `Search for ScreenFeedback items` where `screen_id = Current cell's Zeplin List Screens → id`, sorted by `created_date descending`, with `:first item`'s `status`. Add Conditional formatting: when status is 'Approved', show green text; when 'Needs Revision', show red; when 'Pending' or empty, show gray. For the designer summary view, create a new page `design-summary` (visible only to team members, not clients). On this page: - Add a text element: `Search for ScreenFeedback items where status = Approved → count` + ' screens approved' - Add another: `Search for ScreenFeedback items where status = Needs Revision → count` + ' screens need revision' - Add a Repeating Group of all ScreenFeedback items where status = 'Needs Revision', showing screen_name, comment, client_name, and created_date This gives the design team a single page showing which screens need rework and what clients said — without any manual Zeplin account management. Optional: add an email notification workflow. After the ScreenFeedback Create step, add a Sendgrid or built-in email action to notify the design team's email address when a client marks a screen as 'Needs Revision'. This closes the feedback loop automatically.