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": "ava@example.com",
      "phone": "15551234567",
      "contactMetadata": {
        "source": "web_form",
        "tier": "trial"
      }
    }
  ],
  "action": "upsert"
}
'

{
  "message": "Processed 3 contacts successfully",
  "success": [
    {
      "phone": "15551234567",
      "email": "jane.doe@example.com",
      "action": "created"
    },
    {
      "phone": "15559876543",
      "email": "john.smith@example.com",
      "action": "updated"
    }
  ],
  "errors": []
}

Campaigns

Manage campaign contacts

Creates, updates, or removes contacts in a campaign.

Usage scenarios

Upsert contacts (default): Contacts will be added if they don’t exist, or updated if they do. Contacts with a disqualified or completed status will not be added. If no action is specified, the API defaults to upsert.
Update existing contacts only: Set action to "updateOnly". Only contacts already in the campaign will be updated. Contacts not in the campaign are ignored. This is useful when your process might include contacts that aren’t in the campaign and you don’t want them added.
Remove contacts: Set action to "remove" and provide at least email or phone for each contact to remove.

External IDs (CRM routing)

Configure in Manage Assistants — Define external IDs per assistant so each one can reference CRMs outside Replify (for example HubSpot account IDs, storefront codes, or internal site codes).
Example — A key like hubspotId paired with values that distinguish Site A from Site B.
In this API — For organization-wide / multi-assistant campaigns, include optional externalIdKey and externalIdValue. Key names must match what you saved in Manage Assistants.
Where to put them — You can set externalIdKey / externalIdValue on individual contacts, at the request root, or both. See the schemas for those properties in this spec.

Key fields

action: Controls how contacts are processed. Options are "upsert" (default), "updateOnly", and "remove". This applies to all contacts in the request.
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 identify and handle pro-tier contacts appropriately.
externalIdKey / externalIdValue: Optional; supported on request root and/or per-contact as described in schema field docs.

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": "ava@example.com",
      "phone": "15551234567",
      "contactMetadata": {
        "source": "web_form",
        "tier": "trial"
      }
    }
  ],
  "action": "upsert"
}
'

{
  "message": "Processed 3 contacts successfully",
  "success": [
    {
      "phone": "15551234567",
      "email": "jane.doe@example.com",
      "action": "created"
    },
    {
      "phone": "15559876543",
      "email": "john.smith@example.com",
      "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

externalIdKey

string

Optional external ID name for this request batch (must match a key configured under Manage Assistants). Pair with externalIdValue.

Example:

"hubspotId"

externalIdValue

string

Optional external CRM value paired with root-level externalIdKey for routing in multi-assistant org-wide flows.

Example:

"1234"

action

enum<string>

Controls how contacts are processed. upsert (default) adds new contacts and updates existing ones. updateOnly updates only contacts already in the campaign and ignores others. remove removes the specified contacts.

Available options:

upsert,

updateOnly,

remove

Example:

"upsert"

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

errors

object[]

Contacts that failed to process with error details.

Show child attributes

Initiate outbound call

⌘I