Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.
Custom API is the most useful action type. It lets the employee call an external HTTP endpoint mid-conversation — checking an order status, looking up live stock, creating a support ticket, or updating a CRM record.
Build the action
Name it. Any language, any characters — this is for you and the employee to recognize the action, not code. “Check Order Status” is fine.
Add input parameters. Define the values the employee needs to gather before it can call the action. For each one, set:
Field
Description
Friendly name
What you and the employee call it — keep the actual parameter name code-style, no spaces.
Type
Text (open text, most common), Number, Boolean, or Date.
Description
Optional, but tell the employee what should go in it if it is not self-explanatory — a query field for a product search needs one; first_name does not.
Required
If optional and the employee lacks the data, it skips the parameter rather than blocking the whole request.
Configure the endpoint. Set the method (GET, POST, PUT, PATCH, DELETE) and the URL, plus any query parameters appended to the request and headers the target API requires, such as authentication tokens. For POST, PUT, PATCH, and DELETE, you also get a JSON request body editor.
Reference values with the insert button. Reference input parameters as input.parameter_name and contact attributes as contact.attribute_name inside the URL, headers, query parameters, or body. Use the editor’s insert button rather than typing the prefix by hand, so you do not end up with a broken reference.
Test before saving, using both modes available:
Test mode
What it does
Mock test
Simulates a response without calling the live endpoint — useful for verifying your configuration and response mapping before anything real is connected.
Live test
Runs an actual call against the real endpoint, using real values for every input parameter and contact attribute the request needs, to confirm everything works end-to-end.
Map the response. Choose which fields come back to the employee — see Response mapping below.
Input parameter names must be code-style, no spaces — they are referenced directly in the endpoint and body. If you catch yourself typing one with a space, fix it before saving.
Keep endpoints idempotent where possible, and never return sensitive data the employee should not repeat to a contact. Pair API actions with Boundaries so the employee knows when not to call an external system.
Response mapping
After you test a Custom API Call, the raw response comes back — and it usually contains more than the employee needs: internal IDs, success flags, metadata, timestamps. Response mapping is where you trim that down.
Why it matters
None of that extra data helps answer the contact, and all of it adds noise the employee has to sift through every time the action runs. Response mapping lets you select only the fields that matter — an order status, a price, a stock count — and drop everything else.
How to use it
Select the fields you want to keep. If the response includes an id or success flag you do not need, leave it unmapped — you are choosing what reaches the employee, not editing the API itself.
Rename fields for clarity, if needed. Some APIs return vague or technical names. If a value comes back as val_1 or stat_cd, give it a friendlier output name so both the employee and your team understand what it represents.
Response mapping earns its keep on APIs that return a large or deeply nested response — a full order object with shipping details, line items, and internal metadata benefits from mapping just the two or three fields your guideline actually references. A simple lookup that returns three fields probably needs little trimming.
If a guideline references a specific value from an action’s response, make sure that field is actually mapped. A field the employee cannot see is a field it cannot use, no matter how clearly the guideline describes it.
Example: live stock instead of a crawled page
A crawled page cannot reliably answer “is the medium blue hoodie in stock?” — the count it saw during the crawl may already be wrong. A Custom API Call can:
Be named something like Check Product Stock.
Take an input parameter, product_name or sku, so the employee knows what to look up.
Point at your store’s product API, using input.product_name in the request.
Map the response to just in_stock, quantity, and price — not the raw JSON your store returns.
See Add your website for why crawled links are the wrong tool for data like this in the first place.
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Heyy Help Center","colors":{"primary":"#FE3265","light":"#FE3265","dark":"#FE3265"},"logo":{"light":"https://mintcdn.com/heyy-c8bd5c9e/cOuWPkt81GyZiNr6/assets/logo.svg?fit=max\u0026auto=format\u0026n=cOuWPkt81GyZiNr6\u0026q=85\u0026s=15d8f051f3dbe3cb5e5d0241b7a50372","dark":"https://mintcdn.com/heyy-c8bd5c9e/cOuWPkt81GyZiNr6/assets/logo.svg?fit=max\u0026auto=format\u0026n=cOuWPkt81GyZiNr6\u0026q=85\u0026s=15d8f051f3dbe3cb5e5d0241b7a50372","href":"https://app.heyy.io"},"favicon":"https://mintcdn.com/heyy-c8bd5c9e/yDd_iArPMYbdrfO5/favicon.svg?fit=max\u0026auto=format\u0026n=yDd_iArPMYbdrfO5\u0026q=85\u0026s=c04875889f1d50bf2447289aa0b31f4f","api":{"playground":{"display":"interactive"}},"navbar":{"links":[{"href":"https://wa.me/16504570123","label":"Contact support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.heyy.io"}},"footer":{"socials":{"instagram":"https://www.instagram.com/heyy_hq","linkedin":"https://www.linkedin.com/company/heyyio","x":"https://x.com/Heyy_hq","website":"https://app.heyy.io"}},"seo":{"indexing":"all"},"fonts":{"heading":{"family":"Satoshi","weight":700,"source":"fonts/Satoshi-Variable.woff2","format":"woff2"}},"icons":{"library":"lucide"},"integrations":{"telemetry":{"enabled":true}},"contextual":{"options":["copy","view","chatgpt","claude","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"heyy-c8bd5c9e","hasAudioNarration":false,"actualSubdomain":"heyy-c8bd5c9e","customDomains":["docs.heyy.io"],"gitSource":{"type":"github","owner":"heyy-io","repo":"heyy-docs","deployBranch":"master","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6ac63f1943f8b0b9e9831153","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Help Center","count":124},{"language":"default","tag":"API Reference","count":115},{"language":"default","tag":"HEYY API","count":101},{"language":"default","tag":"AI EMPLOYEES","count":33},{"language":"default","tag":"AUTOMATIONS","count":32},{"language":"default","tag":"Chat","count":20},{"language":"default","tag":"MANAGING YOUR INBOX","count":18},{"language":"default","tag":"Contact","count":18},{"language":"default","tag":"MESSAGING CHANNELS","count":17},{"language":"default","tag":"Triggers","count":15}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":".changelog-month-header{position:relative;padding-block:40px}.changelog-month-bg{position:absolute;top:0;left:50%;width:100vw;height:100%;transform:translateX(-50%);margin-inline:0;z-index:1;background-color:rgb(var(--gray-50) / 0.5);mask-image:linear-gradient(0deg, #fff, rgba(255, 255, 255, 0.6));background-image:url(\"data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32' width='32' height='32' fill='none' stroke='rgb(229 229 229 / 0.2)'%3e%3cpath d='M0 .5H31.5V32'/%3e%3c/svg%3e\");border-top:1px solid rgb(0 0 0/0.05);border-bottom:1px solid rgb(0 0 0/0.05)}.dark .changelog-month-bg{background-color:rgb(var(--gray-800) / 0.25);mask-image:linear-gradient(\n 0deg,\n rgba(255, 255, 255, 0.3),\n rgba(255, 255, 255, 0.8)\n );background-image:url(\"data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32' width='32' height='32' fill='none' stroke='rgb(255 255 255 / 0.05)'%3e%3cpath d='M0 .5H31.5V32'/%3e%3c/svg%3e\");border-top:1px solid rgb(255 255 255/0.05);border-bottom:1px solid rgb(255 255 255/0.05)}.changelog-month-content{position:relative;z-index:2}.changelog-month-kicker{font-size:11px;letter-spacing:0.14em;text-transform:uppercase;opacity:0.6;margin-bottom:8px;font-weight:500}"}]}
{"page":{"pagePath":"help/ai-employees/capabilities/call-an-external-api","slug":"/help/ai-employees/capabilities/call-an-external-api","pageMetadata":{"title":"Call an external API","description":"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.","href":"/help/ai-employees/capabilities/call-an-external-api"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{Frame,Heading,OptimizedImage,Table,Tip,Warning}=_components;if(!Frame)_missingMdxReference(`Frame`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!OptimizedImage)_missingMdxReference(`OptimizedImage`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Custom API`}),` is the most useful `,_jsx(_components.a,{href:`/help/ai-employees/capabilities/actions-overview`,children:`action`}),` type. It lets the employee call an external HTTP endpoint mid-conversation — checking an order status, looking up live stock, creating a support ticket, or updating a CRM record.`]}),`\n`,_jsx(Heading,{level:`2`,id:`build-the-action`,children:`Build the action`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Name it.`}),` Any language, any characters — this is for you and the employee to recognize the action, not code. `,_jsx(_components.em,{children:`“Check Order Status”`}),` is fine.`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Add input parameters.`}),` Define the values the employee needs to gather before it can call the action. For each one, set:`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Field`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Friendly name`})}),_jsx(_components.td,{children:`What you and the employee call it — keep the actual parameter name code-style, no spaces.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Type`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`Text`}),` (open text, most common), `,_jsx(_components.code,{children:`Number`}),`, `,_jsx(_components.code,{children:`Boolean`}),`, or `,_jsx(_components.code,{children:`Date`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Description`})}),_jsxs(_components.td,{children:[`Optional, but tell the employee what should go in it if it is not self-explanatory — a `,_jsx(_components.code,{children:`query`}),` field for a product search needs one; `,_jsx(_components.code,{children:`first_name`}),` does not.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Required`})}),_jsx(_components.td,{children:`If optional and the employee lacks the data, it skips the parameter rather than blocking the whole request.`})]})]})]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Configure the endpoint.`}),` Set the method (`,_jsx(_components.code,{children:`GET`}),`, `,_jsx(_components.code,{children:`POST`}),`, `,_jsx(_components.code,{children:`PUT`}),`, `,_jsx(_components.code,{children:`PATCH`}),`, `,_jsx(_components.code,{children:`DELETE`}),`) and the URL, plus any `,_jsx(_components.strong,{children:`query parameters`}),` appended to the request and `,_jsx(_components.strong,{children:`headers`}),` the target API requires, such as authentication tokens. For `,_jsx(_components.code,{children:`POST`}),`, `,_jsx(_components.code,{children:`PUT`}),`, `,_jsx(_components.code,{children:`PATCH`}),`, and `,_jsx(_components.code,{children:`DELETE`}),`, you also get a JSON request body editor.`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Reference values with the insert button.`}),` Reference input parameters as `,_jsx(_components.code,{children:`input.parameter_name`}),` and contact attributes as `,_jsx(_components.code,{children:`contact.attribute_name`}),` inside the URL, headers, query parameters, or body. Use the editor’s insert button rather than typing the prefix by hand, so you do not end up with a broken reference.`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Test before saving`}),`, using both modes available:`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Test mode`}),_jsx(_components.th,{children:`What it does`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Mock test`})}),_jsx(_components.td,{children:`Simulates a response without calling the live endpoint — useful for verifying your configuration and response mapping before anything real is connected.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Live test`})}),_jsx(_components.td,{children:`Runs an actual call against the real endpoint, using real values for every input parameter and contact attribute the request needs, to confirm everything works end-to-end.`})]})]})]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Map the response.`}),` Choose which fields come back to the employee — see `,_jsx(_components.a,{href:`#response-mapping`,children:`Response mapping`}),` below.`]}),`\n`]}),`\n`]}),`\n`,_jsx(Frame,{children:_jsx(OptimizedImage,{src:`https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=40f84d72318640698fbf3c1789b4fba9`,alt:`Custom API action builder`,\"data-og-width\":`1365`,width:`1365`,\"data-og-height\":`631`,height:`631`,\"data-path\":`assets/ai-employees-actions-api-builder.png`,\"data-optimize\":`true`,\"data-opv\":`3`,srcset:`https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=280\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=9949eb766539a22f1a56c9da97314f0f 280w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=560\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=98fe4cb5bc76cf093dd662080b323d92 560w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=840\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=068042fcf9b2cb330f9e92f87a1fb0ae 840w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=1100\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=9f5c775d4d927508f96fcfdc5ee48072 1100w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=1650\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=dec8f6aa1fc3b629bd3376f9b0dee161 1650w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-api-builder.png?w=2500\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=ee1c22c7210b325d62431aaef49986cb 2500w`})}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Input parameter names must be code-style, no spaces — they are referenced directly in the endpoint and body. If you catch yourself typing one with a space, fix it before saving.`})}),`\n`,_jsxs(_components.p,{children:[`Keep endpoints idempotent where possible, and never return sensitive data the employee should not repeat to a contact. Pair API actions with `,_jsx(_components.a,{href:`/help/ai-employees/identity-and-guidelines/boundaries`,children:`Boundaries`}),` so the employee knows when `,_jsx(_components.em,{children:`not`}),` to call an external system.`]}),`\n`,_jsx(Heading,{level:`2`,id:`response-mapping`,children:`Response mapping`}),`\n`,_jsx(_components.p,{children:`After you test a Custom API Call, the raw response comes back — and it usually contains more than the employee needs: internal IDs, success flags, metadata, timestamps. Response mapping is where you trim that down.`}),`\n`,_jsx(Heading,{level:`3`,id:`why-it-matters`,children:`Why it matters`}),`\n`,_jsx(_components.p,{children:`None of that extra data helps answer the contact, and all of it adds noise the employee has to sift through every time the action runs. Response mapping lets you select only the fields that matter — an order status, a price, a stock count — and drop everything else.`}),`\n`,_jsx(Heading,{level:`3`,id:`how-to-use-it`,children:`How to use it`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Select the fields you want to keep.`}),` If the response includes an `,_jsx(_components.code,{children:`id`}),` or `,_jsx(_components.code,{children:`success`}),` flag you do not need, leave it unmapped — you are choosing what reaches the employee, not editing the API itself.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Rename fields for clarity, if needed.`}),` Some APIs return vague or technical names. If a value comes back as `,_jsx(_components.code,{children:`val_1`}),` or `,_jsx(_components.code,{children:`stat_cd`}),`, give it a friendlier output name so both the employee and your team understand what it represents.`]}),`\n`]}),`\n`,_jsx(Frame,{children:_jsx(OptimizedImage,{src:`https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=97a649b13116bf8ebacd2deb10a8f200`,alt:`Response mapping table with API response fields selected and renamed for the employee to use`,\"data-og-width\":`1578`,width:`1578`,\"data-og-height\":`844`,height:`844`,\"data-path\":`assets/ai-employees-actions-response-mapping.png`,\"data-optimize\":`true`,\"data-opv\":`3`,srcset:`https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=280\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=30d24305e74fe391295eebf0db2d4f76 280w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=560\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=6c14e71e21e6072166c3379f7701c0ac 560w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=840\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=70bb43a4f495a3d0364a29edc474dea3 840w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=1100\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=42e918764d0477539241687d903f3868 1100w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=1650\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=3234f583ecb839f98e1dfdeb77b48b4f 1650w, https://mintcdn.com/heyy-c8bd5c9e/1coCVJUJuVs6SA9x/assets/ai-employees-actions-response-mapping.png?w=2500\u0026fit=max\u0026auto=format\u0026n=1coCVJUJuVs6SA9x\u0026q=85\u0026s=a067fc4d8126e3c08c40ed91144ce4c2 2500w`})}),`\n`,_jsx(_components.p,{children:`Response mapping earns its keep on APIs that return a large or deeply nested response — a full order object with shipping details, line items, and internal metadata benefits from mapping just the two or three fields your guideline actually references. A simple lookup that returns three fields probably needs little trimming.`}),`\n`,_jsx(Tip,{children:_jsx(_components.p,{children:`If a guideline references a specific value from an action’s response, make sure that field is actually mapped. A field the employee cannot see is a field it cannot use, no matter how clearly the guideline describes it.`})}),`\n`,_jsx(Heading,{level:`2`,id:`example-live-stock-instead-of-a-crawled-page`,children:`Example: live stock instead of a crawled page`}),`\n`,_jsx(_components.p,{children:`A crawled page cannot reliably answer “is the medium blue hoodie in stock?” — the count it saw during the crawl may already be wrong. A Custom API Call can:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Be named something like `,_jsx(_components.em,{children:`Check Product Stock`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Take an input parameter, `,_jsx(_components.code,{children:`product_name`}),` or `,_jsx(_components.code,{children:`sku`}),`, so the employee knows what to look up.`]}),`\n`,_jsxs(_components.li,{children:[`Point at your store’s product API, using `,_jsx(_components.code,{children:`input.product_name`}),` in the request.`]}),`\n`,_jsxs(_components.li,{children:[`Map the response to just `,_jsx(_components.code,{children:`in_stock`}),`, `,_jsx(_components.code,{children:`quantity`}),`, and `,_jsx(_components.code,{children:`price`}),` — not the raw JSON your store returns.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`See `,_jsx(_components.a,{href:`/help/ai-employees/content/add-your-website#do-not-crawl-store-data-shopify-woocommerce`,children:`Add your website`}),` for why crawled links are the wrong tool for data like this in the first place.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Call an external API","description":"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.","href":"/help/ai-employees/capabilities/call-an-external-api"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Build the action","slug":"build-the-action","depth":2,"children":[]},{"title":"Response mapping","slug":"response-mapping","depth":2,"children":[{"title":"Why it matters","slug":"why-it-matters","depth":3,"children":[]},{"title":"How to use it","slug":"how-to-use-it","depth":3,"children":[]}]},{"title":"Example: live stock instead of a crawled page","slug":"example-live-stock-instead-of-a-crawled-page","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"heyy-c8bd5c9e","siteName":"Heyy Help Center","title":"Call an external API - Heyy Help Center","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-09T13:02:42.608Z","originalFileLocation":"help/ai-employees/capabilities/call-an-external-api.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Heyy Help Center\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Call an external API - Heyy Help Center\">\u003cmeta data-mint-head property=\"og:description\" content=\"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Heyy Help Center\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://heyy-c8bd5c9e.mintlify.site/_mintlify/api/og/v2?division=Capabilities\u0026amp;title=Call+an+external+API\u0026amp;description=Set+up+a+Custom+API+action+so+your+employee+can+look+up+data+or+trigger+work%2C+not+just+reply+with+text.\u0026amp;theme=41f3b93a9f128cd12ffab71e\u0026amp;signature=a116c8e9a63582162962b7a4605584182abf34ba57c346a16d6fa518aa6e2dfc\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Call an external API - Heyy Help Center\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://heyy-c8bd5c9e.mintlify.site/_mintlify/api/og/v2?division=Capabilities\u0026amp;title=Call+an+external+API\u0026amp;description=Set+up+a+Custom+API+action+so+your+employee+can+look+up+data+or+trigger+work%2C+not+just+reply+with+text.\u0026amp;theme=41f3b93a9f128cd12ffab71e\u0026amp;signature=a116c8e9a63582162962b7a4605584182abf34ba57c346a16d6fa518aa6e2dfc\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/heyy-c8bd5c9e/2DDPHeItlA7vAAJv/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Heyy Help Center\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FE3265\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/help/ai-employees/capabilities/call-an-external-api.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.heyy.io/#organization\",\"name\":\"Heyy Help Center\",\"url\":\"https://docs.heyy.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/heyy-c8bd5c9e/cOuWPkt81GyZiNr6/assets/logo.svg?fit=max\u0026auto=format\u0026n=cOuWPkt81GyZiNr6\u0026q=85\u0026s=15d8f051f3dbe3cb5e5d0241b7a50372\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.heyy.io#website\",\"name\":\"Heyy Help Center\",\"url\":\"https://docs.heyy.io\",\"publisher\":{\"@id\":\"https://docs.heyy.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api#webpage\",\"url\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api\",\"name\":\"Call an external API\",\"description\":\"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\",\"dateModified\":\"2026-09-09T13:02:42.608Z\",\"isPartOf\":{\"@id\":\"https://docs.heyy.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"AI EMPLOYEES\",\"item\":\"https://docs.heyy.io/help/ai-employees\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Capabilities\",\"item\":\"https://docs.heyy.io/help/ai-employees/capabilities/choose-attributes-to-expose\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Call an external API\",\"item\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api#article\",\"headline\":\"Call an external API\",\"name\":\"Call an external API\",\"description\":\"Set up a Custom API action so your employee can look up data or trigger work, not just reply with text.\",\"url\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api\",\"mainEntityOfPage\":{\"@id\":\"https://docs.heyy.io/help/ai-employees/capabilities/call-an-external-api#webpage\"},\"dateModified\":\"2026-09-09T13:02:42.608Z\",\"publisher\":{\"@id\":\"https://docs.heyy.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.heyy.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Heyy Help Center\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Heyy Help Center\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/help/ai-employees/capabilities/call-an-external-api.md","siteName":"Heyy Help Center","nav":{"global":null,"tabs":[{"tab":"Help Center","icon":"life-buoy","groups":[{"group":"QUICK START","pages":[{"title":"Heyy Help Center","href":"/help"}]},{"group":"AI EMPLOYEES","pages":[{"title":"Introduction","href":"/help/ai-employees/index"},{"group":"Getting started","pages":[{"title":"Hire an AI employee","href":"/help/ai-employees/getting-started/hire-an-ai-employee"},{"title":"Run your first test conversation","href":"/help/ai-employees/getting-started/run-your-first-test-conversation"},{"title":"Connect to real customer traffic","href":"/help/ai-employees/getting-started/connect-to-real-customer-traffic"}]},{"group":"Identity \u0026 guidelines","pages":[{"title":"Identity setup","href":"/help/ai-employees/identity-and-guidelines/identity-setup"},{"title":"Write your guidelines","href":"/help/ai-employees/identity-and-guidelines/write-your-guidelines"},{"title":"Identity \u0026 style","href":"/help/ai-employees/identity-and-guidelines/identity-and-style"},{"title":"Conversation flow \u0026 objectives","href":"/help/ai-employees/identity-and-guidelines/conversation-flow-and-objectives"},{"title":"Boundaries","href":"/help/ai-employees/identity-and-guidelines/boundaries"},{"title":"Other","href":"/help/ai-employees/identity-and-guidelines/other"}]},{"group":"Content","pages":[{"title":"Add your website","href":"/help/ai-employees/content/add-your-website"},{"title":"Upload documents","href":"/help/ai-employees/content/upload-documents"},{"title":"Add plain text knowledge","href":"/help/ai-employees/content/add-plain-text-knowledge"},{"title":"Build a Q\u0026A knowledge base","href":"/help/ai-employees/content/build-qa-knowledge-base"},{"title":"Keep knowledge accurate","href":"/help/ai-employees/content/keep-knowledge-accurate"}]},{"group":"Capabilities","pages":[{"title":"Choose which attributes to expose","href":"/help/ai-employees/capabilities/choose-attributes-to-expose"},{"title":"Let your employee read contact fields","href":"/help/ai-employees/capabilities/read-contact-fields"},{"title":"Let your employee update contact fields","href":"/help/ai-employees/capabilities/update-contact-fields"},{"title":"Share files in chat","href":"/help/ai-employees/capabilities/share-files-in-chat"},{"title":"Reference assets in guidelines","href":"/help/ai-employees/capabilities/reference-assets-in-guidelines"},{"title":"Actions overview","description":"Functions your employee can invoke during a conversation, not just knowledge it retrieves passively.","href":"/help/ai-employees/capabilities/actions-overview"},{"title":"Call an external API","href":"/help/ai-employees/capabilities/call-an-external-api"},{"title":"Trigger an automation","description":"Let your employee start another automation for the contact, with input parameters.","href":"/help/ai-employees/capabilities/trigger-an-automation"},{"title":"Create exit points","href":"/help/ai-employees/capabilities/create-exit-points"},{"title":"Configure employee settings","href":"/help/ai-employees/capabilities/employee-settings"}]},{"group":"Going live","pages":[{"title":"How AI employees work in automations","href":"/help/ai-employees/going-live/how-ai-employees-work-in-automations"},{"title":"Test in the playground","href":"/help/ai-employees/going-live/test-in-playground"},{"title":"Add an AI employee to an automation","href":"/help/ai-employees/going-live/add-to-automation"},{"title":"Choose channel and extra guidelines for the step","href":"/help/ai-employees/going-live/channel-and-context"},{"title":"Use exit points in automations","href":"/help/ai-employees/going-live/use-exit-points-in-automations"},{"title":"Hand off to a human teammate","href":"/help/ai-employees/going-live/hand-off-to-human"},{"title":"Set reply timeouts","href":"/help/ai-employees/going-live/reply-timeouts"},{"title":"Override guidelines inside an automation","href":"/help/ai-employees/going-live/automation-guideline-overrides"}]}]},{"group":"MANAGING YOUR INBOX","pages":[{"group":"Inbox","pages":[{"title":"Inbox tour","href":"/help/inbox/inbox-tour"},{"title":"Start a new chat","href":"/help/inbox/start-a-new-chat"},{"title":"Send a message","href":"/help/inbox/send-a-message"},{"title":"Use quick replies","href":"/help/inbox/use-quick-replies"},{"title":"Message actions","href":"/help/inbox/message-actions"},{"title":"Chat actions","href":"/help/inbox/chat-actions"},{"title":"Contact card","href":"/help/inbox/contact-card"}]},{"group":"Find \u0026 organize chats","pages":[{"title":"Global search","href":"/help/inbox/find-and-organize/global-search"},{"title":"Advanced filters","href":"/help/inbox/find-and-organize/advanced-filters"},{"title":"Saved inbox views","href":"/help/inbox/find-and-organize/saved-inbox-views"},{"title":"Team \u0026 user inboxes","href":"/help/inbox/find-and-organize/team-and-user-inboxes"},{"title":"Search \u0026 filter chats","href":"/help/inbox/find-and-organize/search-and-filter-chats"},{"title":"Quick actions","href":"/help/inbox/find-and-organize/quick-actions"},{"title":"Bulk actions","href":"/help/inbox/find-and-organize/bulk-actions"}]},{"group":"Chat fundamentals","pages":[{"title":"Chat lifecycle","href":"/help/inbox/chat-fundamentals/chat-lifecycle"},{"title":"Contact subscription","href":"/help/inbox/chat-fundamentals/contact-subscription"},{"title":"Conversation window","href":"/help/inbox/chat-fundamentals/conversation-window"},{"title":"Sensitive chats","href":"/help/inbox/chat-fundamentals/sensitive-chats"}]}]},{"group":"MESSAGING CHANNELS","pages":[{"title":"Messaging channels","href":"/help/messaging-channels/index"},{"group":"WhatsApp","pages":[{"title":"Getting started","href":"/help/messaging-channels/whatsapp/getting-started"},{"title":"WhatsApp templates","href":"/help/messaging-channels/whatsapp/whatsapp-templates"},{"title":"Guides","href":"/help/messaging-channels/whatsapp/guides"},{"title":"Common issues","href":"/help/messaging-channels/whatsapp/common-issues"}]},{"group":"Instagram","pages":[{"title":"Getting started","href":"/help/messaging-channels/instagram/getting-started"},{"title":"Common issues","href":"/help/messaging-channels/instagram/common-issues"},{"title":"Message errors","href":"/help/messaging-channels/instagram/message-errors"}]},{"group":"Facebook Messenger","pages":[{"title":"Getting started","href":"/help/messaging-channels/facebook-messenger/getting-started"},{"title":"Common issues","href":"/help/messaging-channels/facebook-messenger/common-issues"},{"title":"Message errors","href":"/help/messaging-channels/facebook-messenger/message-errors"}]},{"group":"Live chat","pages":[{"title":"Getting started","href":"/help/messaging-channels/live-chat/getting-started"},{"title":"Common issues","href":"/help/messaging-channels/live-chat/common-issues"},{"title":"Message errors","href":"/help/messaging-channels/live-chat/message-errors"}]},{"group":"SMS","pages":[{"title":"Getting started","href":"/help/messaging-channels/sms/getting-started"},{"title":"Common issues","href":"/help/messaging-channels/sms/common-issues"},{"title":"Message errors","href":"/help/messaging-channels/sms/message-errors"}]}]},{"group":"CONTACTS","pages":[{"group":"Mini-CRM","pages":[{"title":"Contacts tour","href":"/help/contacts/mini-crm/contacts-tour"},{"title":"Column order \u0026 visible fields","href":"/help/contacts/mini-crm/column-order-and-visible-fields"},{"title":"Custom attributes (columns)","href":"/help/contacts/mini-crm/custom-attributes-as-columns"},{"title":"Labels","href":"/help/contacts/mini-crm/labels"}]},{"group":"Search \u0026 filters","pages":[{"title":"Search contacts","href":"/help/contacts/search-and-filters/search-contacts"},{"title":"Advanced filters","href":"/help/contacts/search-and-filters/advanced-filters"},{"title":"Saved contact views","href":"/help/contacts/search-and-filters/saved-contact-views"},{"title":"Bulk actions","href":"/help/contacts/search-and-filters/bulk-actions"}]},{"group":"The contact","pages":[{"title":"What is a contact?","href":"/help/contacts/the-contact/what-is-a-contact"},{"title":"Contacts and channels","href":"/help/contacts/the-contact/contacts-and-channels"},{"title":"Contact subscription","href":"/help/contacts/the-contact/contact-subscription"},{"title":"Contacts across Heyy","href":"/help/contacts/the-contact/contacts-across-heyy"}]}]},{"group":"AUTOMATIONS","pages":[{"title":"Introduction","href":"/help/automations/index"},{"group":"Triggers","pages":[{"title":"Triggers overview","href":"/help/automations/triggers/overview"},{"group":"Chat","pages":[{"title":"New incoming chat","href":"/help/automations/triggers/new-incoming-chat"},{"title":"Reopened chat","href":"/help/automations/triggers/reopened-chat"},{"title":"New \u0026 reopened chat","href":"/help/automations/triggers/new-and-reopened-chat"},{"title":"New incoming message","href":"/help/automations/triggers/new-incoming-message"},{"title":"Chat closed","href":"/help/automations/triggers/chat-closed"},{"title":"Chat assigned","href":"/help/automations/triggers/chat-assigned"},{"title":"Chat moved","href":"/help/automations/triggers/chat-moved"}]},{"group":"Contacts \u0026 labels","pages":[{"title":"Contact created","href":"/help/automations/triggers/contact-created"},{"title":"Contact attribute updated","href":"/help/automations/triggers/contact-attribute-updated"},{"title":"Label added","href":"/help/automations/triggers/label-added"},{"title":"Label removed","href":"/help/automations/triggers/label-removed"}]},{"group":"External \u0026 manual","pages":[{"title":"New Instagram comment","href":"/help/automations/triggers/new-instagram-comment"},{"title":"Webhook received","href":"/help/automations/triggers/webhook-received"},{"title":"Manual trigger","href":"/help/automations/triggers/manual-trigger"}]}]},{"group":"Actions","expanded":false,"pages":[{"title":"Live Chat Actions","sidebarTitle":"Live Chat Actions","href":"/help/automations/live-chat-actions"},{"title":"WhatsApp Actions","sidebarTitle":"WhatsApp Actions","href":"/help/automations/whatsapp-actions"},{"title":"Instagram Actions","sidebarTitle":"Instagram Actions","href":"/help/automations/instagram-actions"},{"title":"Facebook Actions","sidebarTitle":"Facebook Actions","href":"/help/automations/facebook-actions"},{"title":"AI Actions","sidebarTitle":"AI Actions","href":"/help/automations/ai-actions"},{"title":"Logic Actions","sidebarTitle":"Logic Actions","href":"/help/automations/logic-actions"},{"title":"Contacts Actions","sidebarTitle":"Contacts Actions","href":"/help/automations/contacts-actions"},{"title":"Chats Actions","sidebarTitle":"Chats Actions","href":"/help/automations/chats-actions"},{"title":"Notifications Actions","sidebarTitle":"Notifications Actions","href":"/help/automations/notifications-actions"},{"title":"Campaigns Actions","sidebarTitle":"Campaigns Actions","href":"/help/automations/campaigns-actions"},{"title":"Apps Actions","sidebarTitle":"Apps Actions","href":"/help/automations/apps-actions"}]},{"group":"Journeys","pages":[{"title":"What is a journey?","href":"/help/automations/journeys/what-is-a-journey"},{"title":"Build a journey","href":"/help/automations/journeys/build-a-journey"}]},{"group":"Activity log","pages":[{"title":"Activity log overview","href":"/help/automations/activity-log/overview"},{"title":"View runs \u0026 debug","href":"/help/automations/activity-log/view-runs-and-debug"}]},{"group":"Use cases","pages":[{"title":"Use cases","href":"/help/automations/use-cases/coming-soon"}]}]},{"group":"CAMPAIGNS \u0026 OUTREACH","pages":[{"group":"Build a campaign","pages":[{"title":"Campaigns tour","href":"/help/campaigns-and-outreach/build/campaigns-tour"},{"title":"Audience \u0026 recipients","href":"/help/campaigns-and-outreach/build/audience-and-recipients"},{"title":"Message \u0026 templates","href":"/help/campaigns-and-outreach/build/message-and-templates"}]},{"group":"Run \u0026 results","pages":[{"title":"Start \u0026 monitor a campaign","href":"/help/campaigns-and-outreach/run/start-and-monitor"},{"title":"Delivery \u0026 failures","href":"/help/campaigns-and-outreach/run/delivery-and-failures"},{"title":"Export \u0026 bulk actions","href":"/help/campaigns-and-outreach/run/export-and-bulk-actions"}]}]},{"group":"WORKSPACE \u0026 PROFILE","pages":[{"group":"Your profile","pages":[{"title":"Profile","href":"/help/managing-your-profile/profile"},{"title":"Security","href":"/help/managing-your-profile/security"}]},{"group":"Workspace members","pages":[{"title":"How to invite teammates","href":"/help/managing-your-workspace/workspace-members/how-to-invite-teammates"},{"title":"How to invite partners","href":"/help/managing-your-workspace/workspace-members/how-to-invite-partners"},{"title":"Workspace roles","href":"/help/managing-your-workspace/workspace-roles"}]}]}]},{"tab":"API Reference","icon":"code","versions":[{"version":"Version 3","tag":"Latest","groups":[{"group":"GETTING STARTED","pages":[{"title":"Heyy API Documentation - REST API Reference \u0026 Guides","sidebarTitle":"Overview","href":"/api-reference/v3/overview"},{"title":"Authentication","href":"/api-reference/v3/authentication"},{"title":"Versioning","href":"/api-reference/v3/versioning"},{"title":"Query","href":"/api-reference/v3/query"},{"title":"Sort By","href":"/api-reference/v3/sort-by"},{"title":"Search","href":"/api-reference/v3/search"},{"title":"Pagination","href":"/api-reference/v3/pagination"},{"title":"Rate Limiting","href":"/api-reference/v3/rate-limiting"},{"title":"Error Handling","href":"/api-reference/v3/error-handling"}]},{"group":"HEYY API","pages":[{"group":"Attribute","expanded":false,"pages":[{"title":"Search attributes","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /attributes/search","href":"/api-reference/search-attributes"},{"title":"Create attribute","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /attributes","href":"/api-reference/create-attribute"},{"title":"Update attribute","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /attributes/{attributeId}","href":"/api-reference/update-attribute"},{"title":"Get attribute","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /attributes/{attributeId}","href":"/api-reference/get-attribute"},{"title":"Delete attribute","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /attributes/{attributeId}","href":"/api-reference/delete-attribute"}]},{"group":"Automation","expanded":false,"pages":[{"title":"Search automations","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /automations/search","href":"/api-reference/search-automations"},{"title":"Get automation","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /automations/{automationId}","href":"/api-reference/get-automation"},{"title":"Pause automation","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /automations/{automationId}/pause","href":"/api-reference/pause-automation"},{"title":"Unpause automation","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /automations/{automationId}/unpause","href":"/api-reference/unpause-automation"},{"title":"Trigger automation","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /automations/{automationId}/trigger","href":"/api-reference/trigger-automation"}]},{"group":"Campaign","expanded":false,"pages":[{"title":"Search campaigns","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /campaigns/search","href":"/api-reference/search-campaigns"},{"title":"Create campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /campaigns","href":"/api-reference/create-campaign"},{"title":"Update campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /campaigns/{campaignId}","href":"/api-reference/update-campaign"},{"title":"Get campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /campaigns/{campaignId}","href":"/api-reference/get-campaign"},{"title":"Delete campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /campaigns/{campaignId}","href":"/api-reference/delete-campaign"},{"title":"Add recipients","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /campaigns/{campaignId}/recipients","href":"/api-reference/add-recipients"},{"title":"Remove recipients","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /campaigns/{campaignId}/recipients","href":"/api-reference/remove-recipients"},{"title":"Start campaign","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /campaigns/{campaignId}/start","href":"/api-reference/start-campaign"}]},{"group":"Channel","expanded":false,"pages":[{"title":"Search channels","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /channels/search","href":"/api-reference/search-channels"},{"title":"Get channel","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /channels/{channelId}","href":"/api-reference/get-channel"}]},{"group":"Chat","expanded":false,"pages":[{"title":"Search chats","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/search","href":"/api-reference/search-chats"},{"title":"Get chat","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /chats/{chatId}","href":"/api-reference/get-chat"},{"title":"Delete chat","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /chats/{chatId}","href":"/api-reference/delete-chat"},{"title":"Change chat status","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/status","href":"/api-reference/change-chat-status"},{"title":"Assign chat to team","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/assign_team","href":"/api-reference/assign-chat-to-team"},{"title":"Assign chat to user","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/assign_user","href":"/api-reference/assign-chat-to-user"},{"title":"Mark chat as sensitive","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/mark_as_sensitive","href":"/api-reference/mark-chat-as-sensitive"},{"title":"Mark chat as not sensitive","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/mark_as_not_sensitive","href":"/api-reference/mark-chat-as-not-sensitive"},{"title":"Mark chat as read","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/mark_as_read","href":"/api-reference/mark-chat-as-read"},{"title":"Mark chat as unread","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /chats/{chatId}/mark_as_unread","href":"/api-reference/mark-chat-as-unread"}]},{"group":"Contact","expanded":false,"pages":[{"title":"Search contacts","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/search","href":"/api-reference/search-contacts"},{"title":"Create contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts","href":"/api-reference/create-contact"},{"title":"Upsert contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/upsert","href":"/api-reference/upsert-contact"},{"title":"Update contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /contacts/{contactId}","href":"/api-reference/update-contact"},{"title":"Get contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /contacts/{contactId}","href":"/api-reference/get-contact"},{"title":"Delete contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /contacts/{contactId}","href":"/api-reference/delete-contact"},{"title":"Add labels to contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/{contactId}/labels","href":"/api-reference/add-labels-to-contact"},{"title":"Remove labels from contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /contacts/{contactId}/labels","href":"/api-reference/remove-labels-from-contact"},{"title":"Subscribe contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/{contactId}/subscribe","href":"/api-reference/subscribe-contact"},{"title":"Unsubscribe contact","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/{contactId}/unsubscribe","href":"/api-reference/unsubscribe-contact"},{"title":"Bulk upsert contacts","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /contacts/bulk","href":"/api-reference/bulk-upsert-contacts"}]},{"group":"File","expanded":false,"pages":[{"title":"Upload file","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /files","href":"/api-reference/upload-file"},{"title":"Get file","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /files/{fileId}","href":"/api-reference/get-file"},{"title":"Get public file URL","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /files/{fileId}/public_url","href":"/api-reference/get-public-file-url"}]},{"group":"Journey","expanded":false,"pages":[{"title":"Search journeys","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /journeys/search","href":"/api-reference/search-journeys"},{"title":"Get journey","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /journeys/{journeyId}","href":"/api-reference/get-journey"},{"title":"Subscribe contacts to journey","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /journeys/{journeyId}/subscribe","href":"/api-reference/subscribe-contacts-to-journey"},{"title":"Unsubscribe contacts from journey","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /journeys/{journeyId}/unsubscribe","href":"/api-reference/unsubscribe-contacts-from-journey"}]},{"group":"Label","expanded":false,"pages":[{"title":"Search labels","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /labels/search","href":"/api-reference/search-labels"},{"title":"Create label","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /labels","href":"/api-reference/create-label"},{"title":"Update label","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /labels/{labelId}","href":"/api-reference/update-label"},{"title":"Get label","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /labels/{labelId}","href":"/api-reference/get-label"},{"title":"Delete label","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /labels/{labelId}","href":"/api-reference/delete-label"}]},{"group":"Message","expanded":false,"pages":[{"title":"Send message","openapi":"api-reference/openapi-v3.json POST /messages/send","href":"/api-reference/send-message"},{"title":"Send template message","openapi":"api-reference/openapi-v3.json POST /messages/send_template","href":"/api-reference/send-template-message"}]},{"group":"Message Template","expanded":false,"pages":[{"title":"Search message templates","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /message_templates/search","href":"/api-reference/search-message-templates"},{"title":"Create message template","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /message_templates","href":"/api-reference/create-message-template"},{"title":"Update message template","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /message_templates/{messageTemplateId}","href":"/api-reference/update-message-template"},{"title":"Get message template","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /message_templates/{messageTemplateId}","href":"/api-reference/get-message-template"},{"title":"Delete message template","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /message_templates/{messageTemplateId}","href":"/api-reference/delete-message-template"}]},{"group":"Team","expanded":false,"pages":[{"title":"Search teams","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /teams/search","href":"/api-reference/search-teams"},{"title":"Create team","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json post /teams","href":"/api-reference/create-team"},{"title":"Update team","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json put /teams/{teamId}","href":"/api-reference/update-team"},{"title":"Get team","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /teams/{teamId}","href":"/api-reference/get-team"},{"title":"Delete team","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json delete /teams/{teamId}","href":"/api-reference/delete-team"}]},{"group":"User","expanded":false,"pages":[{"title":"Get users","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /users","href":"/api-reference/get-users"},{"title":"Get user","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /users/{userId}","href":"/api-reference/get-user"}]},{"group":"Workspace","expanded":false,"pages":[{"title":"Get workspace","deprecated":null,"version":null,"openapi":"/api-reference/openapi-v3.json get /workspace","href":"/api-reference/get-workspace"}]}]}]},{"version":"Version 2","tag":"Sunset Oct 1, 2026","pages":[{"title":"Version 2","href":"/api-reference/v2/overview"}]}]},{"tab":"Webhooks","icon":"webhook","pages":[{"title":"Webhooks","href":"/webhooks/overview"}]},{"tab":"Changelog","icon":"megaphone","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Call an external API - Heyy Help Center","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["07c022d89b","a74be98ba7"],"chunks":["Frame-D0FT0qQs.js","DynamicMarkdown-CQM9Bhbv.js","zoom-image-lightbox-BQ4tbj_9.js","lightbox-handle-r17bVUz3.js"]}