Custom connector examples
This topic provides several examples of custom connectors that show different ways a connector can be configured using the JSON schema.
OpenAI
The OpenAI custom connector example uses a bearer token for authorization requests and handlebars syntax to reference the API key from the authFields object.
Copy
OpenAI custom connector
{
"schema": "1.0",
"name": "OpenAI",
"link": "https://www.openai.com",
"description": "OpenAI’s API provides access to GPT-3, which performs a wide variety of natural language tasks, and Codex, which translates natural language to code.",
"auth_components": {
"type": "none"
},
"requiredSettings": {
"authFields": [
{
"label": "API Key",
"key": "api_key",
"description": "API key",
"masked": true
}
]
},
"auth_request": {
"type": "bearer",
"token": "{{authFields.api_key}}"
},
"endpoints": {
"GET": {
"/models": {
"url": "https://api.openai.com/v1/"
}
},
"POST": {
"/completions": {
"url": "https://api.openai.com/v1/"
},
"/edits": {
"url": "https://api.openai.com/v1/"
}
}
},
"actions": [
{
"modelId": "create",
"actionId": "completion",
"endpoint": "/completions",
"method": "POST",
"label": "Create a completion",
"helpText": "Creates a completion for the provided prompt and parameters",
"actionFields": [
{
"key": "model",
"label": "Model",
"description": "Provide the model to us",
"type": "string",
"required": true
},
{
"key": "prompt",
"label": "Prompt",
"description": "Provide the prompt to generate completions for",
"type": "string",
"required": false
},
{
"key": "max_tokens",
"label": "Maximum tokens",
"description": "The maximum number of tokens to generate in the completion",
"type": "number",
"required": false
},
{
"key": "temperature",
"label": "Temperature",
"description": "Enter what sampling temperature to use",
"type": "number",
"required": false
},
{
"key": "n",
"label": "Amount of completions",
"description": "Enter how many completions to generate for each prompt.",
"type": "number",
"required": false
}
],
"urlFields": []
},
{
"modelId": "create",
"actionId": "edit",
"endpoint": "/edits",
"method": "POST",
"label": "Create an edit",
"helpText": "Creates a new edit for the provided input, instruction, and parameters",
"actionFields": [
{
"key": "model",
"label": "Model",
"description": "Enter the ID of the model to use",
"type": "string",
"required": true
},
{
"key": "instruction",
"label": "Instruction",
"description": "Enter the instruction that tells the model how to edit the prompt.",
"type": "string",
"required": true
},
{
"key": "input",
"label": "Input",
"description": "Enter the input text to use as a starting point for the edit.",
"type": "string",
"required": false
},
{
"key": "temperature",
"label": "Temperature",
"description": "Enter what sampling temperature to use",
"type": "number",
"required": false
},
{
"key": "n",
"label": "Amount of edits",
"description": "Enter how many edits to generate for the input and instruction.",
"type": "number",
"required": false
}
],
"urlFields": []
}
],
"testConnection": {
"endpoint": "/models",
"method": "GET",
"body": {}
}
}
Google Maps
The Google Maps custom connector example specifies a custom query for authorization requests and uses handlebars syntax to reference variables expected to be input by the user such as API keys or queryParameters of actions.
Copy
Google Maps custom connector
{
"schema": "1.0",
"name": "Google Maps",
"description": "Google Maps is a web-based mapping service that provides detailed information about geographical sites including aerial and satellite views.",
"requiredSettings": {
"authFields": [
{
"label": "Api Key",
"key": "api_key",
"errorText": "Missing parameter. Try reconnecting.",
"masked": true
}
]
},
"auth_components": {
"type": "none"
},
"auth_request": {
"type": "custom_query",
"query_parameters": {
"key": "{{authFields.api_key}}"
},
"blacklist": ["key"],
"errorResponseKey": "error"
},
"endpoints": {
"GET": {
"/geocode/json": {
"url": "https://maps.googleapis.com/maps/api/"
},
"/directions/json": {
"url": "https://maps.googleapis.com/maps/api/"
}
}
},
"actions": [
{
"modelId": "address",
"actionId": "lookup",
"endpoint": "/geocode/json",
"queryParameters": "latlng={{urlFields.latitude}},{{urlFields.longitude}}&language={{urlFields.language}}",
"method": "GET",
"label": "Get address from coordinates",
"helpText": "Translate latitude and longitude coordinates into a street address",
"urlFields": [
{
"key": "latitude",
"label": "Latitude",
"description": "Enter the latitude value of the location",
"helpText": "Example: 40.714224",
"required": true,
"type": "string"
},
{
"key": "longitude",
"label": "Longitude",
"description": "Enter the longitude value of the location",
"helpText": "Example: -73.961452",
"required": true,
"type": "string"
},
{
"key": "language",
"label": "Language",
"description": "Select the language to return the results in",
"required": true,
"type": "choice",
"choices": {
"ar": "Arabic",
"bg": "Bulgarian",
"bn": "Bengali",
"ca": "Catalan",
"cs": "Czech",
"da": "Danish",
"de": "German",
"el": "Greek",
"en": "English",
"en-AU": "English (Australian)",
"en-GB": "English (Great Britain)",
"es": "Spanish",
"eu": "Basque",
"fa": "Farsi",
"fi": "Finnish",
"fil": "Filipino",
"fr": "French",
"gl": "Galician",
"gu": "Gujarati",
"hi": "Hindi",
"hr": "Croatian",
"hu": "Hungarian",
"id": "Indonesian",
"it": "Italian",
"iw": "Hebrew",
"ja": "Japanese",
"kn": "Kannada",
"ko": "Korean",
"lt": "Lithuanian",
"lv": "Latvian",
"ml": "Malayalam",
"mr": "Marathi",
"nl": "Dutch",
"no": "Norwegian",
"pl": "Polish",
"pt": "Portuguese",
"pt-BR": "Portuguese (Brazil)",
"pt-PT": "Portuguese (Portugal)",
"ro": "Romanian",
"ru": "Russian",
"sk": "Slovak",
"sl": "Slovenian",
"sr": "Serbian",
"sv": "Swedish",
"ta": "Tamil",
"te": "Telugu",
"th": "Thai",
"tl": "Tagalog",
"tr": "Turkish",
"uk": "Ukrainian",
"vi": "Vietnamese",
"zh-CN": "Chinese (Simplified)",
"zh-TW": "Chinese (Traditional)"
}
}
],
"actionFields": []
},
{
"modelId": "address",
"actionId": "lookup_lat_long",
"endpoint": "/geocode/json",
"queryParameters": "address={{urlFields.address}}",
"method": "GET",
"label": "Get coordinates from address",
"helpText": "Translate an address to latitude and longitude coordinates",
"urlFields": [
{
"key": "address",
"label": "Street address",
"description": "Enter the address of the location to translate to coordinates",
"helpText": "Example: 1600 Amphitheatre Parkway, Mountain View, CA",
"required": true,
"type": "string"
}
],
"actionFields": []
}
],
"testConnection": {
"endpoint": "/geocode/json",
"queryParameters": "latlng=40.714224,-73.96145",
"method": "GET"
}
}
Shopify
The Shopify custom connector example uses a custom headers for authorization requests, handlebars syntax to reference various parameters, in-line text formatting in text fields, and includes actions that use several different HTTP methods.
Copy
Shopify custom connector
{
"name": "Shopify",
"schema": "1.0",
"link": "https://shopify.com",
"requiredSettings": {
"authFields": [
{
"key": "domain",
"errorText": "Missing parameter. Try reconnecting.",
"preAddOn": "https://",
"label": "Shop Domain"
},
{
"key": "access_token",
"errorText": "Missing parameter. Try reconnecting.",
"label": "Access Token"
}
]
},
"auth_components": {
"type": "none"
},
"auth_request": {
"type": "custom_headers",
"headers": {
"X-Shopify-Access-Token": "{{authFields.access_token}}"
},
"errorMessageKey": "message"
},
"endpoints": {
"GET": {
"/admin/shop": {
"url": "https://{{authFields.domain}}/"
},
"/admin/products": {
"url": "https://{{authFields.domain}}/"
},
"/admin/products/:productId": {
"url": "https://{{authFields.domain}}/"
},
"/admin/orders/:orderId/transactions": {
"url": "https://{{authFields.domain}}/"
}
},
"POST": {
"/admin/customers": {
"url": "https://{{authFields.domain}}/"
},
"/admin/products": {
"url": "https://{{authFields.domain}}/"
},
"/admin/webhooks": {
"url": "https://{{authFields.domain}}/"
}
},
"PUT": {
"/admin/customers/:customerId": {
"url": "https://{{authFields.domain}}/"
},
"/admin/products/:productId": {
"url": "https://{{authFields.domain}}/"
}
},
"DELETE": {
"/admin/webhooks/:webhookId": {
"url": "https://{{authFields.domain}}/"
}
}
},
"actions": [
{
"modelId": "customer",
"actionId": "create",
"endpoint": "/admin/customers",
"method": "POST",
"helpText": "Add a new customer",
"label": "Create Customer",
"actionFields": [
{
"key": "customer.first_name",
"helpText": "Example: Jesse",
"type": "string",
"required": false,
"label": "First Name",
"description": "The customer's first name"
},
{
"key": "customer.last_name",
"helpText": "Example: Doe",
"type": "string",
"required": false,
"label": "Last Name",
"description": "The customer's last name"
},
{
"key": "customer.email",
"helpText": "Example: jessedoe@example.com",
"type": "string",
"required": false,
"label": "Email",
"description": "The customer's email address"
},
{
"key": "customer.phone",
"helpText": "Example: +15142546011",
"type": "string",
"required": false,
"label": "Phone",
"description": "The customer's phone number"
},
{
"key": "customer.note",
"helpText": "Example: Must confirm the delivery address",
"type": "string",
"required": false,
"label": "Note",
"description": "A note about the customer"
},
{
"key": "customer.tags",
"helpText": "Example: credit_card, wholesale",
"type": "string",
"required": false,
"label": "Tags",
"description": "Tags that the shop owner has attached to the customer."
},
{
"key": "customer.accepts_marketing",
"type": "boolean",
"required": false,
"label": "Accepts Marketing",
"description": "Indicates whether the customer has consented to be sent marketing material via email."
},
{
"key": "customer.tax_exempt",
"type": "boolean",
"required": false,
"label": "Tax Exempt",
"description": "Indicates whether the customer is exempt from paying taxes on their order."
},
{
"key": "customer.addresses[0].address1",
"helpText": "Example: 123 Main Street",
"type": "string",
"required": false,
"label": "Address 1",
"description": "The customer's mailing address"
},
{
"key": "customer.addresses[0].company",
"helpText": "Example: ABC Company, Inc.",
"type": "string",
"required": false,
"label": "Company",
"description": "The customer's company"
},
{
"key": "customer.addresses[0].first_name",
"helpText": "Example: Jesse",
"type": "string",
"required": false,
"label": "First Name",
"description": "The customer's first name"
},
{
"key": "customer.addresses[0].last_name",
"helpText": "Example: Doe",
"type": "string",
"required": false,
"label": "Last Name",
"description": "The customer's last name"
},
{
"key": "customer.addresses[0].city",
"helpText": "Example: Anytown",
"type": "string",
"required": false,
"label": "City",
"description": "The customer's city"
},
{
"key": "customer.addresses[0].zip",
"helpText": "Example: 95051",
"type": "string",
"required": false,
"label": "Zip",
"description": "The customer's zip or postal code"
}
]
},
{
"modelId": "customer",
"actionId": "update",
"endpoint": "/admin/customers/{{urlFields.customer_id}}",
"method": "PUT",
"helpText": "Update an existing customer record",
"label": "Update Customer",
"urlFields": [
{
"key": "customer_id",
"helpText": "Example: 207119551",
"type": "string",
"required": true,
"label": "Customer ID",
"description": "The unique identifier for the customer"
}
],
"actionFields": [
{
"key": "customer.first_name",
"helpText": "Example: Jesse",
"type": "string",
"required": false,
"label": "First Name",
"description": "The customer's first name"
},
{
"key": "customer.last_name",
"helpText": "Example: Doe",
"type": "string",
"required": false,
"label": "Last Name",
"description": "The customer's last name"
},
{
"key": "customer.email",
"helpText": "Example: johndoe@example.com",
"type": "string",
"required": false,
"label": "Email",
"description": "The customer's email address"
},
{
"key": "customer.phone",
"helpText": "Example: +15142546011",
"type": "string",
"required": false,
"label": "Phone",
"description": "The customer's phone number"
},
{
"key": "customer.note",
"helpText": "Example: Must confirm the delivery address",
"type": "string",
"required": false,
"label": "Note",
"description": "A note about the customer"
},
{
"key": "customer.tags",
"helpText": "Example: credit_card, wholesale",
"type": "string",
"required": false,
"label": "Tags",
"description": "Tags that the shop owner has attached to the customer."
},
{
"key": "customer.accepts_marketing",
"type": "boolean",
"required": false,
"label": "Accepts Marketing",
"description": "Indicates whether the customer has consented to be sent marketing material via email."
},
{
"key": "customer.tax_exempt",
"type": "boolean",
"required": false,
"label": "Tax Exempt",
"description": "Indicates whether the customer is exempt from paying taxes on their order."
},
{
"key": "customer.addresses[0].address1",
"helpText": "Example: 123 Main Street",
"type": "string",
"required": false,
"label": "Address 1",
"description": "The customer's mailing address"
},
{
"key": "customer.addresses[0].company",
"helpText": "Example: Organization Inc",
"type": "string",
"required": false,
"label": "Company",
"description": "The customer's company"
},
{
"key": "customer.addresses[0].first_name",
"helpText": "Example: Jesse",
"type": "string",
"required": false,
"label": "First Name",
"description": "The customer's first name"
},
{
"key": "customer.addresses[0].last_name",
"helpText": "Example: Doe",
"type": "string",
"required": false,
"label": "Last Name",
"description": "The customer's last name"
},
{
"key": "customer.addresses[0].city",
"helpText": "Example: Anytown",
"type": "string",
"required": false,
"label": "City",
"description": "The customer's city"
},
{
"key": "customer.addresses[0].zip",
"helpText": "Example: 95051",
"type": "string",
"required": false,
"label": "Zip",
"description": "The customer's zip or postal code"
}
]
},
{
"modelId": "product",
"actionId": "create",
"endpoint": "/admin/products",
"method": "POST",
"helpText": "Add a new product with a default product variant",
"label": "Create Product",
"actionFields": [
{
"key": "product.title",
"helpText": "Example: Burton Custom Freestyle 151",
"type": "string",
"required": true,
"label": "Title",
"description": "The name of the product"
},
{
"key": "product.body_html",
"helpText": "Example: <strong>Good snowboard!</strong>",
"type": "text",
"required": false,
"label": "Body HTML",
"description": "The description of the product, complete with HTML formatting."
},
{
"key": "product.vendor",
"helpText": "Example: Burton",
"type": "string",
"required": false,
"label": "Vendor",
"description": "The name of the vendor of the product."
},
{
"key": "product.product_type",
"helpText": "Example: Snowboard",
"type": "string",
"required": false,
"label": "Product Type",
"description": "A categorization that a product can be tagged with, commonly used for filtering and searching."
},
{
"key": "product.tags",
"helpText": "Example: snow, snowboard",
"type": "string",
"required": false,
"label": "Tags",
"description": "A categorization that a product can be tagged with, commonly used for filtering and searching."
},
{
"key": "product.images",
"helpText": "Example: https://example.com/image.png",
"type": "object_list",
"required": false,
"label": "Images",
"description": "A list of image objects associated with the product.",
"fields": [
{
"key": "src",
"helpText": "Example: https://example.com/image.png",
"type": "url",
"required": false,
"label": "Source",
"description": "The source URL of the image."
}
]
},
{
"key": "product.variants",
"helpText": "",
"type": "object_list",
"required": false,
"label": "Variants",
"description": "A list of variant objects representing a slightly different version of the product.",
"fields": [
{
"key": "option1",
"helpText": "",
"type": "string",
"required": true,
"label": "Option 1",
"description": "The name of the option (e.g. Size, Color)"
},
{
"key": "price",
"helpText": "Example: 5.00",
"type": "string",
"required": true,
"label": "Price",
"description": "The price of the variant."
},
{
"key": "sku",
"helpText": "Example: 12345678",
"type": "string",
"required": true,
"label": "SKU",
"description": "A unique identifier for the product in the shop."
}
]
}
]
},
{
"modelId": "product",
"actionId": "find_by_title",
"endpoint": "/admin/products",
"queryParameters": "title={{urlFields.title}}&limit={{urlFields.limit}}",
"method": "GET",
"label": "Find by Title",
"helpText": "Return a product by searching for its title",
"urlFields": [
{
"key": "title",
"helpText": "Example: Burton Custom Freestyle 151",
"type": "string",
"required": true,
"label": "Title",
"description": "The name of the product"
},
{
"key": "limit",
"default": 250,
"type": "hidden",
"required": true,
"label": "Limit",
"description": "The maximum number of products to return"
}
],
"actionFields": []
},
{
"modelId": "product",
"actionId": "find_by_id",
"endpoint": "/admin/products/{{urlFields.productId}}",
"method": "GET",
"helpText": "Return a product by searching for its ID",
"label": "Find by ID",
"urlFields": [
{
"key": "productId",
"helpText": "Example: 12345678",
"type": "string",
"required": true,
"label": "Product ID",
"description": "The unique numeric identifier for the product."
}
],
"actionFields": []
},
{
"modelId": "product",
"actionId": "update",
"endpoint": "/admin/products/{{urlFields.productId}}",
"method": "PUT",
"helpText": "Update the information about a product",
"label": "Update",
"urlFields": [
{
"key": "productId",
"helpText": "Example: 123131312",
"type": "string",
"required": true,
"label": "Product ID",
"description": "The unique numeric identifier for the product."
}
],
"actionFields": [
{
"key": "product.title",
"helpText": "Example: Burton Custom Freestyle 151",
"type": "string",
"required": false,
"label": "Title",
"description": "The name of the product"
},
{
"key": "product.body_html",
"helpText": "Example: <strong>Good snowboard!</strong>",
"type": "text",
"required": false,
"label": "Body HTML",
"description": "The description of the product, complete with HTML formatting."
},
{
"key": "product.vendor",
"helpText": "Example: Burton",
"type": "string",
"required": false,
"label": "Vendor",
"description": "The name of the vendor of the product."
},
{
"key": "product.product_type",
"helpText": "Example: Snowboard",
"type": "string",
"required": false,
"label": "Product Type",
"description": "A categorization that a product can be tagged with, commonly used for filtering and searching."
},
{
"key": "product.tags",
"helpText": "Example: snow, snowboard",
"type": "string",
"required": false,
"label": "Tags",
"description": "A categorization that a product can be tagged with, commonly used for filtering and searching."
},
{
"key": "product.images",
"helpText": "Example: https://example.com/image.png",
"type": "object_list",
"required": false,
"label": "Images",
"description": "A list of image objects associated with the product.",
"fields": [
{
"key": "src",
"helpText": "Example: https://example.com/image.png",
"type": "url",
"required": false,
"label": "Source",
"description": "The source URL of the image."
}
]
},
{
"key": "product.variants",
"helpText": "",
"type": "object_list",
"required": false,
"label": "Variants",
"description": "A list of variant objects representing a slightly different version of the product.",
"fields": [
{
"key": "option1",
"helpText": "",
"type": "string",
"required": true,
"label": "Option 1",
"description": "The name of the option (e.g. Size, Color)"
},
{
"key": "price",
"helpText": "Example: 5.00",
"type": "string",
"required": true,
"label": "Price",
"description": "The price of the product variant."
},
{
"key": "sku",
"helpText": "Example: 12345678",
"type": "string",
"required": true,
"label": "SKU",
"description": "A unique identifier for the product variant in the shop."
}
]
}
]
},
{
"modelId": "order_transactions",
"actionId": "get",
"endpoint": "/admin/orders/{{urlFields.order_id}}/transactions",
"queryParameters": "fields={{urlFields.fields}}&in_shop_currency={{urlFields.in_shop_currency}}&since_id={{urlFields.since_id}}",
"method": "GET",
"helpText": "Retrieve a list of transactions from an order",
"label": "Get transactions",
"urlFields": [
{
"key": "order_id",
"helpText": "Example: 450789469",
"type": "string",
"required": true,
"label": "Order ID",
"description": "The unique numeric identifier for the order."
},
{
"key": "fields",
"helpText": "",
"type": "string",
"required": true,
"label": "Fields",
"description": "Comma-separated list of fields to include in the response."
},
{
"key": "in_shop_currency",
"type": "boolean",
"required": false,
"label": "In Shop Currency",
"description": "Whether to retrieve the transactions in the shop currency or the presentment currency."
},
{
"key": "since_id",
"helpText": "Example: 801038806",
"type": "string",
"required": true,
"label": "Since ID",
"description": "Restrict results to after the specified ID."
}
],
"actionFields": []
}
],
"testConnection": {
"endpoint": "/admin/shop"
}
}