# 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-docs.conversion.ai/import/external-api-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.