API Reference

The ContactList API is a RESTful API that allows you to programmatically interact with your contacts, forms, data collections, and email campaigns.

Base URL

All API requests should be made to:

https://api.contactlist.io/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can create API keys in your dashboard under Settings → API Keys. API keys can be workspace-level or collection-level for additional security.

API Endpoints

Submit Data

Submit data to a collection via REST API.

Endpoint: POST https://api.contactlist.io/api/v1/submit

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "collectionId": "collection_id_here",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

Response:

{
  "success": true,
  "dataId": "data_entry_id",
  "message": "Data submitted successfully"
}

Form Submission

Submit data through a form endpoint.

Endpoint: POST https://form.contactlist.io/forms/{formId}/submit

Body: Form data matching form fields

Response:

{
  "success": true,
  "submissionId": "submission_id",
  "message": "Form submitted successfully"
}

Get All Contacts

GET /contacts

Response:
{
  "data": [
    {
      "id": "123",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890"
    }
  ],
  "total": 1
}

Get Contact by ID

GET /contacts/:id

Response:
{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "createdAt": "2024-01-01T00:00:00Z"
}

Create Contact

POST /contacts

Request Body:
{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890"
}

Response:
{
  "id": "124",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "createdAt": "2024-01-01T00:00:00Z"
}

Update Contact

PUT /contacts/:id

Request Body:
{
  "name": "Jane Smith",
  "email": "jane.smith@example.com"
}

Response:
{
  "id": "124",
  "name": "Jane Smith",
  "email": "jane.smith@example.com",
  "phone": "+1234567890",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Delete Contact

DELETE /contacts/:id

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

API Key Management

ContactList supports both workspace-level and collection-level API keys:

• Workspace-Level Keys: Access to all collections in a workspace
• Collection-Level Keys: Access to a specific collection only

API keys are hashed and never stored in plain text for security.

Data Validation

When submitting data, validation rules defined in your collection schema are automatically applied. Invalid data will return an error response with details about what failed validation.

Webhooks

Get notified when data changes by setting up webhooks:

• Navigate to Settings → Webhooks
• Click "Add Webhook"
• Enter your webhook URL
• Select events to listen for (create, update, delete)
• Save configuration

Webhook payloads will be sent as POST requests to your URL with the event data.

Error Responses

The API uses standard HTTP status codes. Error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Rate Limits

API requests are limited to 1000 requests per hour per API key. Rate limit headers are included in all responses:

• X-RateLimit-Limit: Maximum requests per hour
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Time when the limit resets

Security Best Practices

• Store API keys securely (environment variables, secret managers)
• Never commit keys to version control
• Use different keys for different environments
• Rotate keys regularly
• Revoke unused or compromised keys immediately

Need Help?

For more information, check out our Guides, Authentication Guide, or contact our support team.