---
title: "Add contacts"
slug: "docs-add-contacts"
updated: 2024-10-25T14:42:49Z
published: 2024-10-25T14:42:49Z
canonical: "docs.voiso.com/docs-add-contacts"
---

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

# Add contacts

The **Add Contacts** API is part of Voiso's Campaigns APIs. Use it to add new contacts/leads to an existing live [Dialer campaign](https://docs.voiso.com/docs/outbound-dialer-campaign-launching-your-campaign#live-campaign). The API endpoint description is [here](/v1-api/apidocs/add-contacts).

## Prerequisites

- The [Dialer campaign](https://docs.voiso.com/docs/outbound-dialer-campaign-launching-your-campaign#live-campaign) must have the **Live campaign** setting enabled.
- The campaign ID, which can be obtained by using [List Campaigns](/v1-api/apidocs/docs-list-campaigns) API request or from the **Outbound > Campaigns** page.
- A source for contacts/leads, such as a CRM or Helpdesk, and a list of one or more contacts to be added to the campaign.
- A valid phone number for each contact in [E.164 format](https://www.itu.int/rec/T-REC-E.164) without the preceding '+'. For example: `441234567890`.

## Making requests

The **Add contacts** API requires the [base URL](/v1-api/apidocs/base-endpoint) (cluster_id) and the [contact center API key](/v1-api/apidocs/authentication).

It uses the following parameters to add a contact list:

| Parameter | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| key | The [contact center API key](/v1-api/apidocs/authentication) for authentication. | string | Required | Must be included in the request URL. |
| campaign_id | The identification number associated with the campaign to which the contacts are to be added. | string | Required | Must be included in the request URL. It can be obtained by using the [List Campaigns](/v1-api/apidocs/docs-list-campaigns) API request or from the **Outbound > Campaigns** page. |
| contacts | An array of phone numbers and contact information to be added to a Dialer campaign. | array | Required | Must be included in the request Body. |

### Contacts array

| Parameter | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| phoneNumber | The recipient's phone number. | string | Required | The number must be specified in [E.164 format](https://www.itu.int/rec/T-REC-E.164) without the preceding '+'. For example: 447414992548 |
| contactName | The name of the contact. | string | Required |  |
| contactSource | The name of the source of the contact information, such as a trade show, CRM, and so on. | string | Optional |  |
| contactURL | The URL of a CRM or other integrated application where the contact’s record can be screen popped. | string | Optional | For more information about Voiso support for CRM screen pop, refer to [CRM integration overview](https://docs.voiso.com/docs/crm-integration-overview). |
| priority | A value assigned to the contact to determine the calling order for Dialer. | string | Optional | The range is from 0 to 1000, where 0 is the highest priority. |
| isActive | An indicator of whether the contact should be dialed as part of the campaign. | number | Optional | Valid values are 0 and 1. 0 means the contact should not be called. 1 means the contact should be called. |

With these parameters, you can make a POST request:

```
{
  "method": "POST",
  "url": "https://cluster1.voiso.com/api/v1/ab7a556b6...bb00cc6c3/campaigns/25735/contacts",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "contacts": [
      {
        "phoneNumber": "4407414992548",
        "contactName": "Bill Bringy",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "1"
      },
      {
        "phoneNumber": "4407415552548",
        "contactName": "Alicia Gonzales",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "2"
      }
    ]
  }
}
```

          Note

          

You may have multiple `contacts` parameters.

## Response

The following table describes the elements of the response.

| Element | Description | Type | Notes |
| --- | --- | --- | --- |
| duplicate_numbers | Phone numbers that already exist in the campaign or that you are trying to add more than once. | array | An array of strings. |
| invalid_numbers | Phone numbers that are not in the E.164 format. | array | An array of strings. |
| contacts | Phone numbers successfully added to the campaign. | array | An array of strings. |

### Response sample

```
{
  "duplicate_numbers": [
    “525555013275”,
    "541160905555"
  ],
  "invalid_numbers": [
    “525742360”,
    “1170347521”
  ],
  "contacts": [
    "541123654789",
    “541160908475”,
    “525552489136”
  ]
}
```

## Troubleshooting

The following issues are sometimes encountered:

### Invalid Key

The **Add Contacts** API requires the user API key to validate the request. If you see this error, `"error": "Invalid Key"`, check that you are using the correct user API key. For more information about API keys, refer to [Authentication](/v1-api/apidocs/authentication).

### Campaign not found

If you see this error, `"error": "Campaign not found"`, the campaign ID that you specified in the request URL does not exist in your contact center or is not accessible to the user.

To verify the campaign ID, use the [List Campaigns](/v1-api/apidocs/docs-list-campaigns) API to request it, or from the **Outbound > Campaigns** page, find the campaign ID in the **Campaigns** table.

To verify that the user has access to the specified campaign, check the [user profile](https://docs.voiso.com/docs/users-users) associated with the API request. The **Edit all campaigns** or **Edit own campaigns** [permissions](https://docs.voiso.com/v1/docs/administration-security-access-groups#outbound) must be assigned to the user's profile.

### Campaign type should be live

If you see this error, `"error": "Campaign type should be live"`, the **Live campaign** option is not enabled for the specified campaign. To set this option, from the Voiso main menu bar, navigate to **Outbound > Dialer campaigns** and select the campaign. On the **Edit campaign** page, select **Live campaign** and save the campaign.

### Maximum limit of 1000 contacts for each request

If you see this error, `"error": "Maximum limit of 1000 contacts for each request"`, your POST request is attempting to add more than 1000 contacts to the campaign. To add more than 1000 contacts, make multiple requests of up to 1000 contacts each.

### Required contact field missing

If you see this error, `"error": "Required contact field missing - phoneNumber"`, there is no phone number available for one or more of the contacts you are trying to add to the campaign. Please ensure that you have a phone number for every contact you add to the campaign.