Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Listing Resource

(warning)

Migrate from Preview to v1

Marketplace v1 API is now available, and the Preview API for this Resource will be discontinued in December 2024. See the API Preview to v1 Migration Guide for more information.

This resource allows Marketplace publishers to fetch or update Listings. A Listing represents the data of a published Marketplace Catalog Listing.

(information)

Info

To get access to this resource, contact your Twilio Account Executive.

Listing Properties

listing-properties page anchor
Property NameDescriptionTypePII?
urlThe URL of the API call.string<uri>Not PII
sidThe unique identifier of a Listing. Pattern: ^XB[0-9a-fA-F]{32}$ Min length: 34 Max length: 34SID<XB>Not PII
descriptionA JSON object describing the Listing.stringNot PII
supportA JSON object containing information on how Listing users can obtain support for the Listing.stringNot PII
policiesA JSON object describing the Listing's privacy and legal policies.stringNot PII
module_infoA JSON object containing essential attributes that define a Listing.stringNot PII
documentationA JSON object for providing comprehensive information, instructions, and resources related to the Listing.stringNot PII

Fetch a Listing

fetch-a-listing page anchor

GET https://marketplace.twilio.com/v1/Listing/{Sid}

This endpoint returns the data of a given Listing. To find a Listing's SID, use the Available Add-ons resource or view its Listing details page in the Console by visiting the Catalog(link takes you to an external page) or the My Listings tab(link takes you to an external page) and selecting the Listing.

Path parameters

path-parameters page anchor
Parameter NameDescriptionTypeRequired?PII?
SidThe unique identifier of a Listing. Pattern: ^XB[0-9a-fA-F]{32}$. Min length: 34. Max length: 34.SID<XB>RequiredNot PII
Fetch a ListingLink to code sample: Fetch a Listing
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchModuleDataManagement() {

11
  const moduleDataManagement = await client.marketplace.v1

12
    .moduleDataManagement("XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(moduleDataManagement.url);

16
}

17


18
fetchModuleDataManagement();

Output

1
{

2
  "sid": "XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "url": "https://marketplace.twilio.com/v1/Listing/XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "description": {

5
    "body": "aBody",

6
    "highlights": [

7
      {

8
        "title": "aTitle",

9
        "description": "aDescription"

10
      }

11
    ],

12
    "code_samples": [

13
      {

14
        "title": "aTitle",

15
        "description": "aDescription",

16
        "code": "aCode"

17
      }

18
    ]

19
  },

20
  "support": {

21
    "customer_support_email": "anEmail",

22
    "customer_support_phone": "+1 888-888-8888",

23
    "support_description": "aDescription",

24
    "billing_email": "anEmail",

25
    "billing_phone": "+1 888-888-8888",

26
    "technical_email": "anEmail",

27
    "technical_phone": "+1 888-888-8888"

28
  },

29
  "policies": {

30
    "privacy": "someUrl",

31
    "legal": "someOtherUrl"

32
  },

33
  "module_info": {

34
    "tag": "Description",

35
    "tagline": "aTagline",

36
    "logo_url": "aUrl",

37
    "logo_bg_color_hex": "#ff5722"

38
  },

39
  "documentation": {

40
    "body": "aBody"

41
  },

42
  "pricing": {

43
    "body": "Basic plan - $10/month"

44
  },

45
  "configuration": {

46
    "buttons": [

47
      {

48
        "url": "https://example.com",

49
        "label": "Configurable button text",

50
        "help_text": "The button text, url, and help text are now configurable via self service"

51
      }

52
    ],

53
    "notification_configuration": {

54
      "callback_url": "https://example.com"

55
    }

56
  }

57
}

Update a Listing

update-a-listing page anchor

POST https://marketplace.twilio.com/v1/Listing/{Sid}

This endpoint updates the properties of a given Listing.

Path parameters

path-parameters-1 page anchor
Parameter NameDescriptionTypeRequired?PII?
SidThe unique identifier of a Listing. Pattern: ^XB[0-9a-fA-F]{32}$. Min length: 34. Max length: 34.SID<XB>RequiredNot PII

Request body parameters

request-body-parameters page anchor
Parameter NameDescriptionTypeRequired?PII?
ModuleInfoA JSON object containing essential attributes that define a Listing. See the ModuleInfo object details in the table below.stringOptionalNot PII
DescriptionA JSON object describing the Listing. See the Description object details in the table below.stringOptionalNot PII
DocumentationA JSON object for providing comprehensive information, instructions, and resources related to the Listing. See the Documentation object details in the table below.stringOptionalNot PII
PoliciesA JSON object describing the Listing's privacy and legal policies. See the Policies object details in the table below.stringOptionalNot PII
SupportA JSON object containing information on how Listing users can obtain support for the Listing. See the Support object details in the table below.stringOptionalNot PII

ModuleInfo object details

moduleinfo-object-details page anchor
KeyDescription
taglineA succinct and compelling statement that encapsulates the Listing's purpose and benefits.
logo_urlA publicly accessible URL pointing to the Listing's logo image.
logo_bg_color_hexThe hexadecimal color code representing the background color of the Listing's logo.
1
{

2
      "tagline" : "Enhance your communication with our innovative module",

3
      "logo_url" : "https://example.com/wp-content/uploads/2023/07/S-logo-white-256px.png",

4
      "logo_bg_color_hex" : "#ff5722"

5
}

Description object details

description-object-details page anchor
KeyDescription
bodyThe core description of the Listing in Markdown formatting. HTML tags and images are not supported.
highlightsA complete list of all highlights objects of the Listing. You can pass a title and a corresponding description for each highlight.
1
{

2
    "body" : "Enhance your communication with our innovative module",

3
      "highlights" : [

4
        {"title":"Feature 1" ,"description":"Streamline your workflows."},

5
        {"title":"Feature 2" ,"description":"Seamless integration with your apps."}

6
      ]

7
}

Documentation object details

documentation-object-details page anchor
KeyDescription
bodyInformative and helpful Markdown text guiding users on how to use the Listing. HTML tags and images are not supported.
1
{

2
    "body" : "### Instant Free Trial -- Start Today within Minutes… \r\n\r\n"

3
}

Policies object details

policies-object-details page anchor
KeyDescription
privacyText describing the privacy policy for users using the Listing. Use Markdown when providing links. HTML tags and images are not supported.
legalText describing the legal policy for users using the Listing. Use Markdown when providing links. HTML tags and images are not supported.
1
{

2
    "privacy" : "[https://www.twilio.com/legal/privacy](https://www.twilio.com/legal/privacy)",

3
    "legal" : "[https://www.twilio.com/legal/tos](https://www.twilio.com/legal/tos)"

4
}

Support object details

support-object-details page anchor
KeyDescription
billing_emailEmail address for billing-related inquiries.
billing_phonePhone number for billing-related inquiries.
technical_emailEmail address for technical support.
technical_phonePhone number for technical support.
customer_support_emailEmail address for general customer support.
support_descriptionA description of available support resources, presented in Markdown format. HTML tags and images are not supported.
1
{

2
    "billing_email":"accounts@example.com",

3
    "billing_phone":"+1 617-555-1313",

4
    "technical_email":"support@example.com",

5
    "technical_phone":"+1 617-555-3434",

6
    "customer_support_email":"support@example.com",

7
    "customer_support_phone":"+1 617-555-1212",

8
    "support_description":"Please use Add-on Support form to request support for this Add-on"

9
}
Update a ListingLink to code sample: Update a Listing
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateModuleDataManagement() {

11
  const moduleDataManagement = await client.marketplace.v1

12
    .moduleDataManagement("XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({ moduleInfo: "ModuleInfo" });

14


15
  console.log(moduleDataManagement.url);

16
}

17


18
updateModuleDataManagement();

Output

1
{

2
  "sid": "XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "url": "https://marketplace.twilio.com/v1/Listing/XBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "description": {

5
    "body": "aBody",

6
    "highlights": [

7
      {

8
        "title": "aTitle",

9
        "description": "aDescription"

10
      }

11
    ],

12
    "code_samples": [

13
      {

14
        "title": "aTitle",

15
        "description": "aDescription",

16
        "code": "aCode"

17
      }

18
    ]

19
  },

20
  "support": {

21
    "customer_support_email": "anEmail",

22
    "customer_support_phone": "+1 888-888-8888",

23
    "support_description": "aDescription",

24
    "billing_email": "anEmail",

25
    "billing_phone": "+1 888-888-8888",

26
    "technical_email": "anEmail",

27
    "technical_phone": "+1 888-888-8888"

28
  },

29
  "policies": {

30
    "privacy": "someUrl",

31
    "legal": "someOtherUrl"

32
  },

33
  "module_info": {

34
    "tag": "Description",

35
    "tagline": "aTagline",

36
    "logo_url": "aUrl",

37
    "logo_bg_color_hex": "#ff5722"

38
  },

39
  "documentation": {

40
    "body": "aBody"

41
  },

42
  "pricing": {

43
    "body": "Basic plan - $10/month"

44
  },

45
  "configuration": {

46
    "buttons": [

47
      {

48
        "url": "https://example.com",

49
        "label": "Configurable button text",

50
        "help_text": "The button text, url, and help text are now configurable via self service"

51
      }

52
    ],

53
    "notification_configuration": {

54
      "callback_url": "https://example.com"

55
    }

56
  }

57
}

Errors

errors page anchor

If an error occurs when updating a Listing, the API returns a 400 HTTP status along with relevant error messages. Additionally, a notification is published in the Twilio Debugger to help with further troubleshooting and analysis.

Here are some common error scenarios along with their associated HTTP statuses and messages:

Error ScenarioHTTP Response and Error Message
Missing required parameter400. The [parameter name] parameter is required and must be provided.
Invalid JSON format400. Invalid JSON format. Please ensure the request body adheres to the correct JSON structure.
Exceeding maximum file size400. The JSON size exceeds the maximum allowed limit of 5MB. Please reduce the JSON size and try again.
Module not found404. The specified Module was not found. Please provide a valid Module ID.
Internal server error500. An internal server error occurred. Please contact support for further assistance.