Custom API endpoints

Plans and permissions:

• Add-on: AI agents, billed separately
• Add API domains and endpoints: Admin role, or a custom role with Tools and connectors set to Can edit tools and connectors settings
• Use an endpoint in a workflow: Admin, Manager, or Team Lead role, or a custom role with Workflows set to Can create, edit, and delete workflows

Use custom API endpoints to let your AI agents work with your own systems: find a customer’s recent order, check a subscription, update an account, or start a return. You set up each API once in Assembled, with its domain, authentication, and endpoints, and then call it from any workflow.

To set one up, go to Configure > Tools and connectors and select Add connector > API domain.

How custom API endpoints work

• An API domain holds the base URL and the headers every request needs, such as authentication. Each domain can have many endpoints.
• An endpoint is one request, with its method, path, and optional request body. Endpoints are stored centrally, so you can reuse them in many workflows.
• Paths, request bodies, and headers can use variables, such as {{order_id}}, which earlier workflow steps fill in.
• Workflows call endpoints in a Custom API tool step, or from a Guide step.
• Variables last for one run of a workflow. A value saved in one run, such as an access token, isn’t available in the next.

Gather your API details

Before you start, collect what you need to call each API:

• The domain and the endpoint paths.
• The authentication method and credentials.
• The HTTP method and the content type of the request body.
• The request body format, if the endpoint needs one.
• The format of the response.

Add an API domain

1. Go to Configure > Tools and connectors.
2. Select Add connector, then API domain.
3. Enter a Name and the Domain URL, the absolute base URL, such as https://api.example.com.
4. If requests need to come from Assembled’s proxy server, turn on Use proxy server.
5. Under Additional headers, add the headers that every endpoint on this domain needs, such as Authorization and Content-Type. Enter them as you would in a raw request. For example, an API that uses a bearer token needs the key Authorization and the value Bearer {token_value}.
6. Select Add domain.

Only add headers here that every endpoint needs. You can add headers for a single endpoint when you set it up. Values of security headers, such as tokens and keys, are hidden after you save.

Add an API endpoint

1. On Configure > Tools and connectors, select the API domain.
2. Select Create API endpoint.
3. Enter an Endpoint name. Workflows show the endpoint by this name.
4. Choose the Type: Read-only for lookups, or Write for requests that change data.
5. Check the Domain, and choose the Method, such as GET, POST, or DELETE.
6. Enter the Path, such as /orders/{{order_id}}. Each {{name}} is a variable. If a workflow sets order_id to 14326, the request goes to /orders/14326.
7. Optionally, add Additional headers for this endpoint only, such as a different Content-Type.
8. Optionally, enter a Request body. To send a different body from each workflow, leave it empty and set it in the workflow step instead.
9. Optionally, under Output mapping, map a JSON path in the response to a Smart field, so the value is saved for other steps.
10. Select Preview endpoint to send a test request, then select Save endpoint.

Important: Preview endpoint sends a real request. For POST and DELETE endpoints, use test data where you can.

When an endpoint is already used in workflows, its settings warn you before you change it, and list the features that use it.

Use an endpoint in a workflow

Put the steps that collect the endpoint’s variables before the API step. For example, use a Zendesk data lookup step to save the customer’s email in {{email}}, or an Analyze case step to find the order number in their message. If you haven’t built a workflow before, see Building workflows.

1. In the workflow builder, select + after the steps that set the variables, select Add step, and choose Custom API tool.
2. Optionally, enter a Step name, then choose the API endpoint.
3. Set the step’s options, such as its Type, Request body, and output variables. See Custom API tool step options.
4. Add a branch for each response status code you want to handle. Responses that don’t match a branch, and requests that time out, follow Else.
5. Select Update step.

Call an API that uses OAuth

API domains don’t have an OAuth setting. Many OAuth APIs have a token endpoint, though, that returns a short-lived access token for a POST request, and a workflow can call it first.

1. Add the API’s token endpoint, usually with the client ID and client secret in the request body.
2. In the workflow, add a Custom API tool step for the token endpoint, and save the token to an output variable, such as access_token. Set its Type to Lookup (Read), so the token request also runs when you test the workflow.
3. In the endpoints that need the token, add a header that uses the variable, such as Authorization with the value Bearer {{access_token}}.
4. Call those endpoints in later steps of the same workflow.

Keep in mind: The token is only available for that run of the workflow, so each run requests a new one.

Send form-encoded requests

Some APIs need the request body sent as application/x-www-form-urlencoded, which is common for token endpoints.

1. Add the header Content-Type with the value application/x-www-form-urlencoded.
2. Write the request body as JSON key-value pairs. When a workflow calls the endpoint, Assembled converts the JSON to the form-encoded format.

For example: to send grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}, enter:

{
  "grant_type": "client_credentials",
  "client_id": {{client_id}},
  "client_secret": {{client_secret}}
}

Keep in mind: Preview endpoint sends the JSON body without converting it, so a form-encoded endpoint can return an error there, such as a 500 response. To check it, test a workflow that calls the endpoint instead. The test results show the request and the response. See Building workflows.

Custom API tool step options

Request body

In the request body, use fixed values or variables written as {{variableName}}. Variables are sent as strings by default. To send another type, add it after a colon: {{variableName: int}}, {{variableName: float}}, {{variableName: bool}}, {{variableName: array}} for a JSON list, or {{variableName: object}} for a JSON object.

For example: this body sends a fixed name and three variables:

{
  "name": "Jordan",
  "email": {{email}},
  "inquiry": {
    "message": {{message}},
    "orderId": {{order_id: int}}
  }
}

The email, message, and order_id variables must be set earlier in the workflow, by a lookup, an Analyze case step, a Guide step, or another Custom API tool step. The fixed text “Jordan” is in quotation marks. String variables get their quotation marks automatically, so leave them as {{variable}}.

Output variables

To use the response in later steps, map parts of it to variables. Enter a variable name and the path to the value in the response.

For example: for this response:

{
  "status": "closed",
  "order_id": "5678",
  "fulfillment": {
    "tracking_number": "90322321312"
  }
}

To save the whole response as one variable, use the path .. A Guide step can then read all of it at once. To transform the data before sending it to another endpoint, see API data transformation in workflows.