> For the complete documentation index, see [llms.txt](https://api-docs.conversion.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.conversion.ai/import/external-api-documentation.md). # 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:** ```json { "contacts": [ { "email": "john@example.com", "variables": { "first_name": "John", "last_name": "Doe", "phone": "+1234567890", "company_name": "Acme Corp" }, } ] } ``` **Response:** ```json { "success": true, "data": [ { "email": "john@example.com", "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:** ```json { "success": true, "data": { "id": "uuid-contact-id", "businessId": "uuid-business-id", "email": "john@example.com", "variables": { "first_name": "John", "last_name": "Doe", "phone": "+1234567890" }, "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:** ```json { "success": true, "message": "Contact deleted successfully" } ``` ### Batch Update Subscription Status Update subscription status for multiple contacts. **Endpoint:** `POST /contacts/batch-subscription` **Request Body:** ```json { "updates": [ { "email": "john@example.com", "subscriptionStatus": "UNSUBSCRIBED" }, { "email": "jane@example.com", "subscriptionStatus": "SUBSCRIBED" } ] } ``` **Subscription Status Values:** * `SUBSCRIBED` * `UNSUBSCRIBED` * `PENDING` **Response:** ```json { "success": true, "data": { "updated": 2, "failed": 0, "results": { "john@example.com": "success", "jane@example.com": "success" } } } ``` ### Track Custom Engagement Record custom engagement activities for contacts. **Endpoint:** `POST /contacts/engagements` **Request Body:** ```json { "contactEmail": "john@example.com", "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "success": true, "message": "Company deleted successfully" } ``` *** ## Response Format All API responses follow this standard format: **Success Response:** ```json { "success": true, "data": { /* response data */ } } ``` **Error Response:** ```json { "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