Get started with the Well Core API

​
How it works

1

Create API Key

Start by creating an API key using POST /v1/api-key to authenticate your requests. You’ll need to provide your organization ID and a name for the key.
const response = await fetch('https://api.well.com/v1/api-key', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_AUTH_TOKEN'
  },
  body: JSON.stringify({
    data: {
      type: 'api-key',
      attributes: {
        name: 'Production API Key',
        organisation: {
          id: 'your-org-uuid'
        }
      }
    }
  })
});

const { data } = await response.json();
const apiKey = data.attributes.value;
2

Manage Companies

Create and manage companies using the /v1/companies endpoint. Companies are core entities that can have associated emails, social links, and documents.
// Create a company
const createCompany = await fetch('https://api.well.com/v1/companies', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    data: {
      type: 'company',
      attributes: {
        name: 'Acme Corp',
        description: 'Leading technology company',
        partner_id: 'partner-uuid'
      }
    }
  })
});

// Get company details
const getCompany = await fetch(`https://api.well.com/v1/companies/${companyId}`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

// Update company
const updateCompany = await fetch(`https://api.well.com/v1/companies/${companyId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    data: {
      type: 'company',
      attributes: {
        name: 'Updated Acme Corp',
        description: 'Updated description'
      }
    }
  })
});
3

AI-Powered Data Processing

Leverage AI capabilities for data extraction and processing using the /v1/ai endpoint. Process HTML content with different AI modes for various data extraction tasks.
// AI data extraction
const aiResponse = await fetch('https://api.well.com/v1/ai', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${firebaseToken}` // Note: AI endpoint uses Firebase auth
  },
  body: JSON.stringify({
    data: {
      type: 'ai-request',
      attributes: {
        html: '<html>...</html>',
        mode: 'EXTRACT_COMPANY_INFO',
        flow: 'CONTRIBUTION',
        flow_id: 'contribution-uuid',
        arg1: 'additional-parameter'
      }
    }
  })
});

const result = await aiResponse.json();
4

Document & Email Management

Upload and manage documents, handle email operations, and set up webhooks for real-time notifications.
// Upload document
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('data', JSON.stringify({
  type: 'document',
  attributes: {
    name: 'Important Document',
    description: 'Document description'
  }
}));

const documentResponse = await fetch('https://api.well.com/v1/documents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
});

// Create email
const emailResponse = await fetch('https://api.well.com/v1/emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    data: {
      type: 'email',
      attributes: {
        email: 'contact@acmecorp.com'
      }
    }
  })
});

// Create webhook
const webhookResponse = await fetch('https://api.well.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    data: {
      type: 'webhook',
      attributes: {
        url: 'https://your-app.com/webhook',
        events: ['company.created', 'document.uploaded']
      }
    }
  })
});

​
Core Resources

The Well Core API provides several key resources:

API Keys

Manage authentication keys for your organization

Companies

Create, read, update and manage company records

Documents

Upload and manage documents with metadata

AI Processing

Leverage AI for data extraction and processing

Emails

Manage email addresses and communications

Webhooks

Set up real-time event notifications

​
Authentication

The Well Core API uses multiple authentication methods depending on the endpoint:
  • API Key Authentication: For most endpoints, use your API key in the Authorization header
  • Firebase Authentication: For AI and contribution endpoints, use Firebase tokens
  • Organization-based: Most resources are scoped to your organization

​
Response Format

All API responses follow the JSON:API specification: 
{
  "data": {
    "type": "company",
    "id": "company-uuid",
    "attributes": {
      "name": "Acme Corp",
      "description": "Leading technology company",
      "partner_id": "partner-uuid",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }
}

​
Next Steps

Create your first API Key

Start by creating an API key for authentication