curl --request POST \
  --url https://api.heylibby.com/api/v1/campaigns/{campaignId}/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contacts": [
    {
      "firstName": "Ava",
      "lastName": "Lopez",
      "email": "[email protected]",
      "phone": "15551234567",
      "contactMetadata": {
        "source": "web_form",
        "tier": "trial"
      }
    }
  ]
}
'

{
  "message": "Processed 3 contacts successfully",
  "success": [
    {
      "phone": "15551234567",
      "email": "[email protected]",
      "action": "created"
    },
    {
      "phone": "15559876543",
      "email": "[email protected]",
      "action": "updated"
    }
  ],
  "errors": []
}

Campaigns

Manage campaign contacts

Creates or updates contacts in a campaign, or removes specific contacts when requested.

Usage scenarios

Create a new contact: Use the CreateNewContact example. Provide at least email or phone.
Update an existing contact: Use the UpdateExistingContact example. You can include any fields; unchanged fields will remain the same.
Remove a contact: Use the RemoveContact example. Set the top-level action field to "remove" and provide at least email or phone for each contact to remove.

Key fields

action: Set to "remove" to remove the contacts specified in the request. Omit this field to create or update contacts.
status: Use completed or disqualified to stop further outreach from campaigns. Other status values are allowed but won’t affect campaign behavior.
contactMetadata: Add any key:value pairs to inform your AI assistant’s behavior. For example, if you set "tier": "pro", you can configure your AI to skip contacts already in the pro tier, effectively disqualifying them from the campaign.

POST

campaigns

{campaignId}

contacts

curl --request POST \
  --url https://api.heylibby.com/api/v1/campaigns/{campaignId}/contacts \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contacts": [
    {
      "firstName": "Ava",
      "lastName": "Lopez",
      "email": "[email protected]",
      "phone": "15551234567",
      "contactMetadata": {
        "source": "web_form",
        "tier": "trial"
      }
    }
  ]
}
'

{
  "message": "Processed 3 contacts successfully",
  "success": [
    {
      "phone": "15551234567",
      "email": "[email protected]",
      "action": "created"
    },
    {
      "phone": "15559876543",
      "email": "[email protected]",
      "action": "updated"
    }
  ],
  "errors": []
}

Authorizations

x-api-key

string

header

required

Path Parameters

campaignId

string<uuid>

required

The unique ID of the campaign

Body

application/json

contacts

object[]

required

List of contacts to add or update. When action is set to "remove", these contacts are removed from the campaign.

Show child attributes

contacts.firstName

string

Contact's first name.

Example:

"Jane"

contacts.lastName

string

Contact's last name.

Example:

"Doe"

contacts.email

string<email>

At least one of email or phone is required to identify the contact.

Example:

"[email protected]"

contacts.phone

string

At least one of email or phone is required to identify the contact.

Example:

"15551234567"

contacts.status

enum<string>

Optional status field. Use completed when the contact has achieved the campaign goal (e.g., signed up for trial, made purchase). Use disqualified when the contact is not a good fit. Other values are allowed but won't affect campaign behavior.

Available options:

completed,

disqualified

Example:

"completed"

contacts.contactMetadata

object

Key:value pairs that inform your AI assistant's behavior. Use any custom data to help your AI respond differently in different scenarios. For example, set "tier": "pro" to help your AI identify and handle pro-tier contacts appropriately.

Example:

{
  "source": "import",
  "tier": "pro",
  "won": true
}

action

enum<string>

Set to "remove" to remove the contacts specified in the contacts array.

Available options:

remove

Example:

"remove"

Response

Request accepted and processed successfully.

message

string

Human-readable summary of the operation results.

Example:

"Processed 2 contacts successfully, 1 failed"

success

object[]

Contacts that were successfully created, updated, or deleted.

Show child attributes

success.phone

string

Normalized phone number (if provided).

Example:

"15551234567"

success.email

string<email>

Email address (if provided).

Example:

"[email protected]"

success.action

enum<string>

Action taken for this contact.

Available options:

created,

updated

Example:

"created"

errors

object[]

Contacts that failed to process with error details.

Show child attributes

errors.email

string<email>

Email associated with the error (if available).

Example:

"[email protected]"

errors.phone

string

Phone associated with the error (if available).

Example:

"15559876543"

errors.error

string

Reason why the contact could not be processed.

Example:

"Contact contains email and phone for two different existing contacts"

Outbound Phone Calling API

⌘I

Outbound Calling

Campaign Service API

Manage campaign contacts

Authorizations

Path Parameters

Body

Response