Get Organization Brands

This guide walks you through retrieving the list of available brands for your organization using the Stewart Sign API. Brands are used to customize the appearance of eSignature transactions with your organization's branding.

When to Use

The brands endpoint is useful when you need to:

• List all available brands your organization has configured
• Retrieve brand IDs for use in transaction creation or updates
• Access brand metadata (colors, logos, etc.) for display in your UI
• Ensure a valid brand ID before creating a transaction

Requirements

1. You need to have Node.js installed on your system.
2. You'll also need the axios library. You can install it using the following command:

npm install axios

3. A valid Bearer token (JWT) for authentication.

Endpoint

GET /brands

Query Parameters

This endpoint has no required query parameters. All brands belonging to your organization are returned.

Code Snippet

Use the following code snippet to retrieve your organization's brands. Replace <accessToken> with your API access token.

const axios = require("axios");

const config = {
  method: "get",
  url: "https://public-api.sign.stewart.com/brands",
  headers: {
    Authorization: "Bearer <accessToken>",
  },
};

axios(config)
  .then(function (response) {
    console.log("Brands retrieved:", response.data);
    response.data.forEach((brand) => {
      console.log(`Brand: ${brand.name} (ID: ${brand.id})`);
    });
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Successful Response

On success, the API returns an array of brand objects:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Default Brand",
    "colorPrimary": "#1A73E8",
    "colorSecondary": "#FFFFFF",
    "colorBackground": "#F5F5F5",
    "logoWebUrl": "https://cdn.example.com/logo.png",
    "logoEmailUrl": "https://cdn.example.com/logo-email.png"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Alternative Brand",
    "colorPrimary": "#FF6B6B",
    "colorSecondary": "#FFE66D",
    "colorBackground": "#FFFFFF",
    "logoWebUrl": "https://cdn.example.com/alt-logo.png",
    "logoEmailUrl": "https://cdn.example.com/alt-logo-email.png"
  }
]

Response Fields

Field	Type	Description
id	string (UUID)	The unique identifier for the brand. Use this when creating or updating transactions.
name	string	The display name of the brand.
colorPrimary	string	Hex color code for the primary brand color.
colorSecondary	string	Hex color code for the secondary brand color.
colorBackground	string	Hex color code for the background color.
logoWebUrl	string	URL to the brand logo for web/iframe displays.
logoEmailUrl	string	URL to the brand logo for email communications.

Using Brands with Transactions

Once you've retrieved the brand ID, you can use it when creating or updating transactions:

Create Transaction with Brand

const transactionConfig = {
  method: "post",
  url: "https://public-api.sign.stewart.com/transactions",
  headers: {
    Authorization: "Bearer <accessToken>",
    "Content-Type": "application/json",
  },
  data: {
    brandId: "550e8400-e29b-41d4-a716-446655440000",
    documents: [...],
    participants: [...],
    status: "esign_pending",
  },
};

axios(transactionConfig)
  .then(function (response) {
    console.log("Transaction created with brand:", response.data);
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Update Transaction with Brand

const updateConfig = {
  method: "put",
  url: "https://public-api.sign.stewart.com/transactions/{transactionId}",
  headers: {
    Authorization: "Bearer <accessToken>",
    "Content-Type": "application/json",
  },
  data: {
    brandId: "550e8400-e29b-41d4-a716-446655440001",
  },
};

axios(updateConfig)
  .then(function (response) {
    console.log("Transaction updated with brand:", response.data);
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Error Responses

Status	Reason
403 Forbidden	The brandsManagement feature flag is not enabled for your organization. Contact your account manager to enable this feature.
401 Unauthorized	Invalid or expired Bearer token

Feature Flag

The brands endpoint is gated behind the brandsManagement feature flag on your organization. If this feature is not enabled, the endpoint returns a 403 Forbidden response with details on how to request access.

Steps to Execute the Code Snippet

1. Create a new file named get_brands.js.
2. Copy and paste the code snippet provided above into the new file.
3. Replace <accessToken> with your API access token.
4. Save the file and open a terminal or command prompt.
5. Navigate to the folder where you saved the get_brands.js file.
6. Run the following command to execute the script:

node get_brands.js

If the request is successful, you'll see the list of available brands displayed in the console. In case of an error, the error details will be displayed instead.

Additional Resources

For more information about the eSignature API, visit the API reference.

For examples of using brands with transactions, see:

• Create Your First eSignature Transaction
• Update a Transaction
• Create a Test Transaction

If you need further assistance or have questions, feel free to reach out to our support team.