Skip to main content

​
Adding Contacts Manually

  • Navigate to Your Campaign: From the main dashboard, click on the campaign you want to add contacts to.
  • Add Contacts: Click on the “Add Contacts” button located on the top right of the campaign page. In the window that will be opened, click on the “Add Manually” tab at the top.
add-contacts
  • Enter Contact Details: Start filling in the contact details as required by the variables included in the campaign, such as name, phone number, email address, and any custom fields.
  • Finalize Import: After entering all the necessary details, review the information to ensure accuracy. Click on ‘Finalize import’ located on the top right of the window.
add manually

Manually enter contacts, press Finalize Import when done

  • Wait for Processing: Wait for the platform to complete the processing of the data. This may take some time depending on the volume of contacts being added.
  • View Summary: Once the import is finalized, a summary will be displayed showing the number of contacts successfully added and the number of contacts that were not added.
  • Complete the Process: Click on the ‘Finalize import’ button located on the top right of the window again to confirm the completion of the process.
contacts example
Duplicate Handling: Note that contacts with phone numbers that are already included in the campaign will not be uploaded again to avoid duplicates.

​
Uploading Contacts via CSV

​
CSV Format

  • Header Format: Ensure your column headers follow a consistent style that matches the variable names used in your campaign. For ‘Property Address’, acceptable formats include ‘PropertyAddress’, ‘propertyAddress’, ‘Property Address’, ‘Property_address’, and ‘property address’.
    • For the name of the contact, use ‘name’ or ‘Name’.
    • For a single phone number, use ‘phone number’ or ‘phoneNumber’ in various acceptable formats.
    • For multiple phone numbers, use ‘phoneNumbers’ (see details below).
    • For the email, use ‘email’ or ‘Email’.
  • Include Country Code: Make sure that phone numbers include the country code to ensure they are recognized correctly.
  • Spaces and Symbols: It’s acceptable for phone numbers to contain spaces and symbols like dashes or parentheses. These characters will not interfere with the upload process, so feel free to include them if they are a part of your phone number formatting in the dataset.

​
Multiple Phone Numbers

You can specify multiple phone numbers for a single contact using the phoneNumbers field. The system will call these numbers sequentially until one is answered.
Important: When using the phoneNumbers field in CSV:
  • The entire field value must be wrapped in double quotes ("")
  • Multiple numbers should be separated by commas
  • Each number should include the country code
Example: ""+1 555 555 1234,+1 555 555 5678,+1 555 555 9999""
Example CSV with single phone number:
contacts.csv
name,phoneNumber,propertyAddress,email
John,+1 555 555 1234,123 Maple Street,[email protected]
Tom,+1 555 555 5678,456 Maple Street,[email protected]
Example CSV with multiple phone numbers:
contacts.csv
name,phoneNumber,phoneNumbers,propertyAddress,email
John,,"+1 555 555 1234,+1 555 555 5678",123 Maple Street,[email protected]
Tom,,"+1 555 555 9999,+1 555 555 0000,+1 555 555 1111",456 Maple Street,[email protected]
  • Navigate to Your Campaign: From the main dashboard, click on the campaign you want to add contacts to.
  • Add Contacts: Click on the “Add Contacts” button located on the top right of the campaign page. In the window that opens, click on the “Select file” button to browse and choose the CSV file from your computer.
upload contacts csv

Upload contacts with a CSV file

  • Finalize Import: After you have filled in the contacts via CSV, click on the ‘Finalize import’ button located on the top right of the window.
  • Wait for Processing: Wait for the platform to complete the processing of the data. This may take some time depending on the volume of contacts being imported.
  • View Summary: Once the import is finalized, a summary will be displayed showing the number of contacts successfully added and the number of contacts that were not added.
finalize import
  • Complete the Process: Click on the ‘Finalize import’ button located on the top right of the window again to confirm the completion of the process.
contacts example
Duplicate Handling: Note that contacts with phone numbers that are already included in the campaign will not be uploaded again to avoid duplicates.

​
API Endpoints for Adding Contacts

Callers provides two API endpoints for programmatically adding contacts to your campaigns:

​
Create a Single Contact

Use this endpoint to add one contact at a time to your campaign: 
POST https://api.callers.ai/campaigns/{campaignId}/contacts
Headers: 
Authorization: <api-key>
Content-Type: application/json
Request Body (single phone number): 
{
  "name": "John Doe",
  "phoneNumber": "+1 555 555 1234",
  "data": {
    "propertyAddress": "123 Maple Street",
    "email": "[email protected]"
  },
  "archived": false
}
Request Body (multiple phone numbers - sequential calling): 
{
  "name": "John Doe",
  "phoneNumbers": [
    "+1 555 555 1234",
    "+1 555 555 5678",
    "+1 555 555 9999"
  ],
  "data": {
    "propertyAddress": "123 Maple Street",
    "email": "[email protected]"
  },
  "archived": false
}
Query Parameters:
  • fixUSPhoneNumber (boolean, optional): Will add 1 to the phone number if it doesn’t start with 1
Response (200): 
{
  "contactId": "string",
  "created": true,
  "modified": false
}
This endpoint is ideal when you need to add contacts individually, such as from a form submission or real-time integration.

​
Create Multiple Contacts (Bulk)

Use this endpoint to add multiple contacts at once to your campaign: 
POST https://api.callers.ai/campaigns/{campaignId}/contacts/bulk
Headers: 
Authorization: <api-key>
Content-Type: application/json
Request Body: 
{
  "contacts": [
    {
      "name": "John Doe",
      "phoneNumber": "+1 555 555 1234",
      "phoneNumbers": [
        "+1 555 555 1234"
      ],
      "data": {
        "propertyAddress": "123 Maple Street",
        "email": "[email protected]"
      },
      "archived": false
    },
    {
      "name": "Jane Smith",
      "phoneNumber": "+1 555 555 5678",
      "phoneNumbers": [
        "+1 555 555 5678"
      ],
      "data": {
        "propertyAddress": "456 Oak Avenue",
        "email": "[email protected]"
      },
      "archived": false
    }
  ]
}
Query Parameters:
  • fixUSPhoneNumber (boolean, optional): Will add 1 to the phone number if it doesn’t start with 1
Response (200): 
{
  "requested": 2,
  "added": 2,
  "modified": 0,
  "contactIds": ["contact_id_1", "contact_id_2"]
}
This endpoint is perfect for batch operations when you need to upload many contacts simultaneously, offering better performance for large-scale contact imports. Important Notes:
  • The data field is an object that can contain any custom fields that match the variables in your campaign
  • The phoneNumbers array can contain multiple phone numbers for a single contact. These numbers will be called sequentially until one is answered
  • Phone numbers should include the country code (e.g., +1 for US numbers)
  • Duplicate contacts (based on phone number) will not be added again
  • You can use either phoneNumber (single) or phoneNumbers (array for multiple numbers)
For detailed API documentation and examples, please refer to our API Reference.