External API Documentation

Overview

This API allows external companies to upload and manage contacts, companies, and engagement data in our system. All endpoints require proper authentication and follow RESTful conventions.

Base URL

https://pub-api.conversion.ai/api/v1

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

---

Contacts API

Batch Upsert Contacts

Create or update multiple contacts in a single request.

Endpoint: POST /contacts/batch

Request Body:

{
  "contacts": [
    {
      "email": "[email protected]",
      "variables": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "[phone]",
        "company_name": "Acme Corp"
      },
    }
  ]
}

Response:

{
  "success": true,
  "data": [
    {
      "email": "[email protected]",
      "contactId": "uuid-contact-id-123",
      "operation": "created"
    }
  ]
}

Field Requirements:

• email (required): Valid email address

• variables (optional): Key-value pairs for custom contact fields

• externalContact (optional): Your system's reference data

Get Contact by Email

Retrieve a contact using their email address.

Endpoint: GET /contacts/by-email/{email}

Response:

{
  "success": true,
  "data": {
    "id": "uuid-contact-id",
    "businessId": "uuid-business-id",
    "email": "[email protected]",
    "variables": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "[phone]"
    },
    "subscriptionStatus": "SUBSCRIBED",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Delete Contact by Email

Remove a contact from the system using their email address.

Endpoint: DELETE /contacts/by-email/{email}

Response:

{
  "success": true,
  "message": "Contact deleted successfully"
}

Batch Update Subscription Status

Update subscription status for multiple contacts.

Endpoint: POST /contacts/batch-subscription

Request Body:

{
  "updates": [
    {
      "email": "[email protected]",
      "subscriptionStatus": "UNSUBSCRIBED"
    },
    {
      "email": "[email protected]", 
      "subscriptionStatus": "SUBSCRIBED"
    }
  ]
}

Subscription Status Values:

• SUBSCRIBED

• UNSUBSCRIBED

• PENDING

Response:

{
  "success": true,
  "data": {
    "updated": 2,
    "failed": 0,
    "results": {
      "[email protected]": "success",
      "[email protected]": "success"
    }
  }
}

Track Custom Engagement

Record custom engagement activities for contacts.

Endpoint: POST /contacts/engagements

Request Body:

{
  "contactEmail": "[email protected]",
  "type": "ACTIVITY",
  "name": "Product Demo Completed",
  "description": "Customer completed full product demonstration session",
  "data": {
    "duration_minutes": 45,
    "demo_type": "interactive",
    "products_shown": ["product_a", "product_b"],
    "interest_level": "high",
    "next_steps": "follow_up_meeting"
  }
}

Field Requirements:

• contactEmail (required): Email of the contact

• type (required): Must be "ACTIVITY"

• name (required): Brief name for the engagement

• description (required): Detailed description of what happened

• data (optional): Additional JSON data with custom fields

Response:

{
  "success": true,
  "data": {
    "engagementId": "uuid-engagement-id",
    "contactEmail": "email"
  }
}

---

Companies API

Batch Upsert Companies

Create or update multiple companies in a single request.

Endpoint: POST /companies/batch

Request Body:

{
  "companies": [
    {
      "id": "your_company_id_123",
      "baseDomain": "acmecorp.com",
      "variables": {
        "company_name": "Acme Corporation",
        "industry": "Technology",
        "size": "501-1000",
        "annual_revenue": "10000000",
        "location": "San Francisco, CA"
      }
    }
  ]
}

Field Requirements:

• id (required): Your unique identifier for this company

• baseDomain (recommended): Company's primary domain

• variables (optional): Key-value pairs for custom company fields

Response:

{
  "success": true,
  "data": [
    {
      "id": "your_company_id_123",
      "companyId": "uuid-company-id-456",
      "operation": "created"
    }
  ]
}

Get Company by ID

Retrieve a company using your system's ID.

Endpoint: GET /companies/by-external-id/{id}

Response:

{
  "success": true,
  "data": {
    "id": "uuid-company-id",
    "businessId": "uuid-business-id",
    "baseDomain": "acmecorp.com",
    "externalId": "providedId",
    "variables": {
      "company_name": "Acme Corporation",
      "industry": "Technology",
      "size": "501-1000"
    }
    "createdAt": "2024-01-15T09:00:00Z"
  }
}

Delete Company by ID

Remove a company from the system using your system's ID.

Endpoint: DELETE /companies/by-external-id/{id}

Response:

{
  "success": true,
  "message": "Company deleted successfully"
}

---

Response Format

All API responses follow this standard format:

Success Response:

{
  "success": true,
  "data": { /* response data */ }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "field": "email",
      "value": null
    }
  }
}

Error Codes

Code	Description
VALIDATION_ERROR	Request data validation failed
NOT_FOUND	Requested resource not found
DUPLICATE_ERROR	Resource already exists
RATE_LIMIT_EXCEEDED	Too many requests
UNAUTHORIZED	Invalid or missing API key
INTERNAL_ERROR	Server error

Data Types and Validation

Contact Variables

Common variable names (use these keys for best integration):

• first_name: Contact's first name

• last_name: Contact's last name

• phone: Phone number

• company_name: Company name

• title: Job title

• linkedin_url: LinkedIn profile URL

Company Variables

Common variable names:

• company_name: Full company name

• industry: Industry classification

• size: Employee count range (e.g., "1-10", "11-50", "51-200")

• annual_revenue: Annual revenue in USD

• location: Primary business location

• website: Company website URL

Custom Engagement Data

The data field in engagement tracking accepts any JSON structure. Common fields:

• duration_minutes: Length of interaction

• outcome: Result of the engagement

• next_steps: Planned follow-up actions

• priority: Engagement priority level

• tags: Array of tags for categorization

Best Practices

1. Batch Operations: Use batch endpoints when uploading multiple records to reduce API calls

2. Error Handling: Always check the success field before processing response data

3. Data Consistency: Use consistent external IDs across all API calls

4. Validation: Validate email formats and required fields before sending requests

5. Monitoring: Monitor API response times and error rates for optimal performance