Skip to contentSkip to navigationSkip to topbar
Rate this Page:

Add-on Submission Guide


The following guide serves to help you through the Publisher Onboarding process.


Technical Submission Form

technical-submission-form page anchor

The following section includes tips and examples to help you through the Technical Submission Form. Please be sure to also read through the Add-on API Requirements for details on the technical requirements.

The HttpBin Example Add-on:

The examples listed below outline an Add-on submission for the HttpBin API (see httpbin.org(link takes you to an external page)). HttpBin is a free service that echoes data in your http request back to you. If you were to build an Add-on for HttpBin, you would get back the Add-on data that Twilio sends in its request. Use the HttpBin examples below to understand the different ways to pass parameters to your API.

Describe what your Add-on does

describe-what-your-add-on-does page anchor

Please provide a brief description of your Add-on so we can understand what it does.

HttpBin echoes data in your HTTP request back to you.

Documentation for the API that powers the Add-on

documentation-for-the-api-that-powers-the-add-on page anchor

Please be as specific as possible providing page numbers and section names for your specific API so that we can quickly understand the technical details.

Mapping of Add-on template parameters to your API fields

mapping-of-add-on-template-parameters-to-your-api-fields page anchor

Filling out this question correctly is absolutely critical so that we can test your API and validate it is compatible with our Marketplace interface. Below are examples for how we'd like you to define the mapping of our template parameters to invoke your API.

Querystring Parameters via GET


_10
GET
_10
https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}

JSON Dictionary via POST

In the example below, hardcoded_param=STATIC_VALUE will be sent exactly as-is for all requests and is not seen by the customer.


_10
POST
_10
https://httpbin.org/post?hardcoded_param=STATIC_VALUE
_10
JSON Body
_10
{
_10
"e164": "{{primary_address}}"
_10
"message": "{{body}}"
_10
}

www-form-encoded via POST


_10
POST
_10
https://httpbin.org/post?hardcoded_param=STATIC_VALUE
_10
_10
www-form-encoded Body
_10
key1={{primary_address}}
_10
key2={{secondary_address}}
_10
key3={{body}}
_10
hardcoded_key=STATIC_VALUE

HTTP Headers via GET/POST


_10
GET
_10
https://httpbin.org/get?hardcoded_param=STATIC_VALUE
_10
_10
Headers
_10
key1={{primary_address}}
_10
key2={{secondary_address}}
_10
hardcoded_key=STATIC_VALUE

Vendor-defined Lookup parameters via GET/POST

Currently, only Lookup supports request-time parameters. If you are submitting a Lookup Add-on and would like to define custom parameters please do so by indicating your custom field value in double curly braces, {{ like in the example below. See our REST API: Lookups docs on how our API users will be passing the parameter.

Note: Support for vendor-defined parameters across other integrations will be available in the Console soon. When that is released, this guide will be updated accordingly.


_10
GET
_10
https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}&custom_param={{vendor_defined_field}}

Request Validation Schema

request-validation-schema page anchor

Define a JSON schema to validate a request prior to invoking your API. The following schema limits phone numbers with +91 or +1 prefixes only. See Add-on Publisher Guide. This is optional.


_13
{
_13
"$schema": "http://json-schema.org/draft-04/schema#",
_13
"type": "object",
_13
"properties": {
_13
"primary_address": {
_13
"type": "string",
_13
"pattern": "^\\+(91|1)[0-9]*$"
_13
}
_13
},
_13
"required": [
_13
"primary_address"
_13
]
_13
}

Response Validation Schema

response-validation-schema page anchor

Define a JSON schema to validate a response before billing the end-user. The following schema ensures the response always contains the args.e164 parameter. See Add-on Publisher Guide. This is optional.


_20
{
_20
"$schema": "http://json-schema.org/draft-04/schema#",
_20
"type": "object",
_20
"properties": {
_20
"args": {
_20
"type": "object",
_20
"properties": {
_20
"e164": {
_20
"type": "string"
_20
}
_20
},
_20
"required": [
_20
"e164"
_20
]
_20
}
_20
},
_20
"required": [
_20
"args"
_20
]
_20
}

Result Cleaning JSON Paths

result-cleaning-json-paths page anchor

Define a JSON path to clean an element from your response. See JSONPath Online Evaluator(link takes you to an external page) to test your JSON path. Also see Add-on Publisher Guide for more details. This is optional.

Result Cleaning Path:

By defining the two JSON paths below we are removing the origin and headers.Cookie elements from our HttpBin JSON body before it is wrapped in our response and passed to the user.


_10
$.origin
_10
$.headers.Cookie

JSON response before:


_17
{
_17
"args": {
_17
"apikey": "YOUR_API_KEY",
_17
"phone_number": "{{primary_address}}"
_17
},
_17
"headers": {
_17
"Accept": "*/*",
_17
"Accept-Encoding": "gzip, deflate, sdch, br",
_17
"Accept-Language": "en-US,en;q=0.8",
_17
"Cache-Control": "no-cache",
_17
"Cookie": "_cookie=monster",
_17
"Host": "httpbin.org",
_17
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
_17
},
_17
"origin": "127.0.0.1",
_17
"url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"
_17
}

JSON response after:


_16
{
_16
"args": {
_16
"apikey": "YOUR_API_KEY",
_16
"phone_number": "{{primary_address}}"
_16
},
_16
"headers": {
_16
"Accept": "*/*",
_16
"Accept-Encoding": "gzip, deflate, sdch, br",
_16
"Accept-Language": "en-US,en;q=0.8",
_16
"Cache-Control": "no-cache",
_16
"Host": "httpbin.org",
_16
"Postman-Token": "60abdc13-1c06-5233-b6dc-00ba98f22070",
_16
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
_16
},
_16
"url": "https://httpbin.org/get?apikey=YOUR_API_KEY&phone_number={{primary_address}}"
_16
}

Live Endpoint and Authentication Credentials

live-endpoint-and-authentication-credentials page anchor

We support the following authentication schemes to access your API. Please use one of the examples below as a guide to how we'd like you to submit your credentials. Also take a look at our Default HTTP Headers to understand what we will be sending in our HTTP request.

Querystring via GET


_10
https://httpbin.org/get?key=YOUR_API_KEY

Request Body via POST


_10
https://httpbin.org/post
_10
_10
www-form-encoded Body
_10
username=TWILIOPROD
_10
password=PASSWORD

HTTP Headers (Basic, Bearer) via GET/POST


_10
Basic/Bearer Auth
_10
https://httpbin.org/get
_10
Username: TWILIOPROD
_10
Password: PASSWORD
_10
OR
_10
Bearer Token: BEARER_TOKEN

Description and examples of the different pricing models available are listed below:

  1. Single Price: Regardless of volume usage, customer will be charged a flat unit rate
    • Example: $.0080/unit
  2. Tiered Pricing: For customers who will reach volume scale, offer tiered volume pricing
    • Example: 0 - 100,000: $.0075; 100,001 - 1,000,000: $.0070; 1,000,000+: $.0065
    • Tiers reset on a monthly basis
  3. Commit Pricing: Offer special discounts to customers in return for a monthly commit
    • Set committed amount
    • Set overage fee if customer goes above the committed threshold
    • Example: $500 commit for 100,000 requests; overage rate: $.0055/request
    • Commit pricing resets on a monthly basis and any overage does not roll over to the next month

Marketing and Support Submission Form

marketing-and-support-submission-form page anchor

Tips to help you through the Marketing and Support Submission Form.

The Title, Provider Name, Partner Website or Landing Page, Logo, and Tagline appear in your Add-on detail page as well as in the Catalog.

Header.

Add-on Long Description and Highlights

add-on-long-description-and-highlights page anchor

The Long Description appears in your Add-on listing like in the screenshot below. The field accepts Markdown which is a plain text formatting syntax which converts to structurally valid HTML. Read more about Markdown and how to use it here: https://daringfireball.net/projects/markdown/(link takes you to an external page)

You can list up to four highlights. Each highlight requires a Title and Description.

Description.

You can list up to three Sample Responses. Each sample response requires a Title, Description and Code Snippet.

Snippets.

Like the Long Description, the Documentation field accepts Markdown. Use this template(link takes you to an external page) so that your docs conform to our standard format.

Documentation.

The Requesting Support Process Description accepts Markdown and is a free-form field for you to describe your support process. Customer Support Email and Customer Support Phone will be listed here directly.

Support.

Policies

policies page anchor

The Terms of Service field accepts Markdown. The Privacy Policy field should be a link to your Privacy Policy on your website.

Policies.

Rate this Page: