> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Request
> Send an HTTP request and use the response in later blocks.
Use **API Request** to read from or send data to an external service. The block can look up account information, create or update a record, or trigger another operation through an HTTP endpoint.
API Request supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
## Choose where it runs
Place the block at the stage when the request should run and after any variables it needs become available.
| Stage | Use it when |
| :------------ | :----------------------------------------------------------------------------- |
| **Pre-call** | The result is needed before the call starts |
| **Live call** | The result affects the active conversation or its routing |
| **Post-call** | The request should run after a call that reached the connected live-call block |
A request can use only variables available before it runs. For example, place a request that needs information collected during the conversation after the Talk or Collect block that collects it.
If the request is needed only after the call, place it in post-call so the caller does not wait for the external service.
## Configure the request
Select the HTTP method and enter the endpoint in **URL**. Use a publicly reachable HTTPS URL; local addresses and private network endpoints are blocked.
| Field | Purpose |
| :------------------- | :--------------------------------------------------------------------------- |
| **Headers** | Send values required by the endpoint, such as authentication or content type |
| **Query Parameters** | Add values to the URL as separate key-value pairs |
### Configure a request body
For `POST`, `PUT`, and `PATCH`, choose a body type:
| Body type | Use it when |
| :------------------------ | :----------------------------------- |
| **None** | The endpoint does not expect a body |
| **x-www-form-urlencoded** | The endpoint expects form fields |
| **JSON** | The endpoint expects structured JSON |
`GET` and `DELETE` do not include a request body.
For a JSON body, choose **Manual** to add typed fields or **Code** to edit the raw JSON. Manual fields support strings, numbers, booleans, arrays, objects, and nested values.
Follow the endpoint's documentation for its required field names, formats, and authentication.
### Import a cURL command
Select **Import from cURL** beside the URL to populate the supported method, URL, headers, query parameters, and body from a cURL command.
Import fills only the fields that the editor supports. Review the result, replace sample values with fixed values or variables, and confirm that the request matches the API documentation before testing.
## Use variables in the request
Focus a URL, header, query parameter, form, or JSON field, then select a value from **Available Variables**. The list includes only variables available before the block runs.
Variables inserted into the URL, headers, query parameters, and form fields are sent as text. In a JSON body, they can retain a number, boolean, object, or array type.
Use a [Custom Variable](/flow-editor/variables#use-custom-variables) for a fixed value reused across requests, such as an API key or account ID. Keep credentials out of examples, screenshots, and Ask AI prompts.
## Test and create response variables
Run **Send test request** before using the response in another block. The test sends a real request to the configured endpoint.
1. Enter safe sample values for the variables used by the request.
2. For a JSON-body variable, choose the same data type it will have when the flow runs.
3. Select **Show request** to inspect the resolved URL, headers, parameters, and body.
4. Send the request and inspect the response.
A successful test with a `2xx` JSON response creates variables under the block's name. For example:
```json theme={null}
{
"customer": {
"id": "cus_123",
"active": true
}
}
```
This creates `response` for the complete object, plus `customer`, `customer.id`, and `customer.active`. If the response is a top-level array, its items are available under `output`.
Later blocks can select these values from **Available Variables**. If the response structure changes, test the request again and review downstream fields that reference its variables.
Use a JSON response when later blocks need individual response fields. At runtime, a non-JSON response is stored as text in `response`.
A block test can create, update, send, charge, or delete real data. Use a test endpoint or records that are safe to change.
## Configure runtime behavior
Expand **Advanced Settings** to configure timeout, retries, and other options available for the block's stage.
### Timeout duration
**Timeout Duration** controls how long Phonely waits for the endpoint:
* Pre-call: 1 to 5 seconds
* Live call and post-call: 1 to 30 seconds
Keep live-call requests short. If the request regularly needs more time and can run after the call, move it to post-call.
### Retry on failure
Enable **Retry on Failure** when another attempt may succeed, then set **Max Attempts** from 1 to 10.
Retries can repeat the endpoint's side effects. Before enabling retry for a request that creates a booking, payment, ticket, message, or other record, confirm that the endpoint can safely prevent duplicates.
### Other advanced settings
Pre-call and live-call API Request blocks also support interim messages, error routes, and call outcome tagging. See [Common Block Settings](/blocks/common-settings) for how these options affect the caller, connections, and reporting.
Post-call API Request blocks provide timeout and retry settings, but not interim messages, error routes, or call outcome tagging.
## Verify the complete behavior
After the block test succeeds:
1. Confirm that request variables resolve to the intended values.
2. Test each flow route that can reach the block and confirm a successful response.
3. If **Error Handling** is enabled, test a controlled failure and its recovery route.
4. Confirm that downstream blocks receive the expected response fields.
5. Complete an end-to-end flow test before relying on the request.
During a Web Chat test, expand API Request in the action trace. After a phone call, open **Call Details**, select **Blocks**, and expand API Request. Review its status, request, response, and stored variables.
## Troubleshooting
Use a valid, publicly reachable HTTPS URL. For a block test, enter a sample value for every variable used by the request, then inspect **Show request** for an unresolved or malformed value.
Compare the resolved headers, parameters, and body with the endpoint's current documentation. Confirm that credentials are valid and that each field uses the required name, format, and data type.
API Request treats only `2xx` HTTP status codes as successful. Check the returned status code. If the failure is expected and **Error Handling** is available and enabled, connect the **Error** route; otherwise correct the request or endpoint behavior.
Run a successful test with a representative JSON response. If the response shape changed, test again and replace downstream references that no longer exist.
In the manual JSON body, choose the intended field type. For variables used in the JSON body test, select a matching test type. Values outside the JSON body are sent as text.
Reduce **Timeout Duration**, use a concise interim message, or move the request to post-call when it is needed only after the call.
Disable **Retry on Failure** until the endpoint can safely reject or deduplicate repeated requests. Retest with non-production data.