> ## Documentation Index
> Fetch the complete documentation index at: https://docs.replify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound Phone Calling API (Legacy)

> Legacy API documentation for outbound phone calling — retiring July 1, 2026

<Warning>
  **This API is being retired.** If you are still using this version, you must migrate to the [Outbound Phone Calling API](/api-reference/outbound-calling/initiate-outbound-call) by **July 1, 2026**. Your account manager will help you with the transition.
</Warning>

## Pre-requisites

Plus Plan subscription

<Note>
  To access this API, please contact your account manager to request an API key. This API uses a support-issued key (you can’t generate one yourself like you can for our other APIs).
</Note>

## Overview

The Outbound Call API allows you to trigger an outbound call from your system to a specified phone number. The call can be customized with specific prompts, questions, and rules, and can include metadata about the customer. This API is useful for any situation where automated outbound calls are required.

### Endpoint

**POST** [https://phone.mylibby.ai/outbound](https://phone.mylibby.ai/outbound)

### Request Payload

The request payload should be a JSON object that looks like the following

**Option 1:** provide introNotes that will allow AI to generate the intro and voicemail messages.

```json theme={null}
{
  "name": "Chris",
  "introNotes": "We are an event planning company, Check and see if they are interested in event planning services",
  "toPhoneNumber": "+1xxxxxxxxxx",
  "fromPhoneNumber": "+1xxxxxxxxxx",
  "formInfo": [
    {"Have you had an event planner before?":"Yes"},
    {"What's your budget?": "100 per month"}
  ]
}
```

**Option 2: provide the explicit introMessage and introVoicemail**

```json theme={null}
{
  "name": "Chris",
  "introMessage": "Hi, we see that you expressed interest in our services. Can I answer any questions or schedule a demo with you?",
  "introVoicemail": "Hi, we're calling you back as we see you've expressed interest in our services. Call us back to help answer questions.",
  "toPhoneNumber": "+1xxxxxxxxxx",
  "fromPhoneNumber": "+1xxxxxxxxxx",
  "formInfo": [
    {"Have you had a photographer before?":"Yes"},
    {"What's your budget?": "100 per month"}
  ]
}
```

### Parameters

* **name** (string): The name of the person being called. This is used to personalize the conversation.
* **toPhoneNumber** (string): The phone number to call. This should be in E.164 format (e.g., "+1505XXXXXXX").
* **fromPhoneNumber** (string): The agent's phone number initiating the call. This should also be in E.164 format (e.g., "+1XXXXXXX").
* **introNotes** (string, optional): This is used to generate the introductory message or voicemail content. This will be used to start the conversation or leave a message if the recipient doesn't answer. It will not match the message, but rather be used in generating the message(s)
* **introMessage** (string, optional): Use this instead of introNotes if you want to define exactly how you want the assistant to say after the user answers the phone. If you define this, you must provide an introVoicemail as well.
* **introVoicemail** (string, optional): Use this instead of introNotes if you want to define exactly the voicemail you want the assistant to leave if the user does not answer the phone.
* **formInfo** (array of objects): Metadata about the customer. This can include any relevant information that should be referenced during the call. Each object represents a key-value pair. Usually this information is taken in and dynamically set from a form.

### Response

**200** - Call has been processed

```json theme={null}
{
    "message": "Outbound call processed"
}
```

### Common Error Responses

**403 - Forbidden**

Typically this indicates you did not add a token or the token is expired.

```json theme={null}
{
    "message": "Forbidden: Incorrect scopes"
}
```

**404 - Not Found**

There is no agent for the outgoing number.

```json theme={null}
{
    "message": "Agent not found for this number"
}
```

## Authentication

### Overview

The Cognito Token API is used to obtain an access token from Amazon Cognito by making a POST request to the OAuth2 token endpoint. This token can be used to authenticate requests to the Outbound API.

### Endpoint

**POST** [https://libby.auth.us-east-1.amazoncognito.com/oauth2/token](https://libby.auth.us-east-1.amazoncognito.com/oauth2/token)

### Request

#### Headers

* **Content-Type**: `application/x-www-form-urlencoded`

  Specifies that the request body is URL-encoded.
* **Optional Cookie**: `XSRF-TOKEN={}`

  The CSRF token for protecting against cross-site request forgery.

#### Body

The body of the request should be URL-encoded and include the following parameters:

* **grant\_type** (string): The type of grant being requested. For client credentials, use `client_credentials`.
* **client\_id** (string): The client ID for your application. This identifies your app to the authentication server.
* **client\_secret** (string): The client secret associated with the client ID. This is used to authenticate your app.
* **scope** (string): The scope of the access being requested. This should be the resource server scope, e.g., `external-api-resource-server-1/call.out`.

### Example Request

```javascript theme={null}
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Cookie", "XSRF-TOKEN=0d12bcfe-f40f-4182-8c00-aa344553747f");

const urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("client_id", "your-client-id");
urlencoded.append("client_secret", "your-client-secret");
urlencoded.append("scope", "external-api-resource-server-1/call.out");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("https://libby.auth.us-east-1.amazoncognito.com/oauth2/token", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

### Response

The response will contain an access token if the request is successful.

```json theme={null}
{
  "access_token": "eyJraWQiOiJLT...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

* **access\_token** (string): The token that can be used to authenticate requests to other services.
* **token\_type** (string): The type of token returned, typically `Bearer`.
* **expires\_in** (integer): The number of seconds until the token expires.
* **scope** (string): The scope of access granted by the token.

### Error Response

If the request fails, the response will include an error message and error code.

**400 - Bad Request**

Likely a bad client\_id or client\_secret.

```json theme={null}
{
    "error": "invalid_client"
}
```

### Notes

* **CSRF Protection**: The `Cookie` header includes a CSRF token to protect against cross-site request forgery. Ensure that this token is valid and properly handled in your application.
* **Token Storage**: Store the `access_token` securely and avoid exposing it to unauthorized parties.