API

Adding Data to Leads via API

You can add or update Leads automatically using MagicBlocks API. This allows your website, app, or CRM to send Lead information directly to your workspace in real time — instead of manually uploading CSV files.

Official API Docs:

POST /contacts – Create a new Lead

PUT /contacts – Update an existing Lead

When to Use the Leads API
Use the Leads API whenever you want to:

• Automatically sync customer data from a form submission, checkout, or CRM update.
• Enrich existing Leads with additional attributes like UTM, plan, country, or consent.
• Trigger an Agent workflow right when a Lead enters your system (e.g., send welcome message, qualify lead, or start journey).
• Maintain a single source of truth for customer data across all your connected platform

Authentication 

All API requests require authentication with your MagicBlocks API Key. 

Go to Settings → Channels → API Tokens to generate or copy your existing token.

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json
• Base URL: https://api.magicblocks.com/v1

1. Using POST — Create a New Lead

Use this when you want to add a brand-new contact to your MagicBlocks workspace.

Endpoint

POST https://api.magicblocks.com/v1/contacts

Headers

Sample Request – Create Lead (201)

curl -X POST "https://api.magicblocks.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": {
      "first": "Johan",
      "middle": "",
      "last": "Greg"
    },
    "emails": [
      {
        "address": "johan.greg@magicblocks.ai",
        "type": "work",
        "primary": true
      }
    ],
    "phones": [
      {
        "number": "+61412345678",
        "type": "mobile",
        "primary": true
      }
    ],
    "isTest": false,
    "userKnowledge": "Imported from Founders contact list - internal test data",
    "custom": {
      "utm_source": "founder-referral",
      "utm_campaign": "onboarding-internal",
      "role": "Co-Founder",
      "country": "Australia",
      "timezone": "AEST"
    },
    "sendMessageEvents": true,
    "flowEditorName": "Agent Welcome Flow",
    "flowEditorLink": "https://app.magicblocks.ai/flow/agent-welcome"
  }'

Sample Response

{
  "id": "con_01HRWJ0HAN8F6X9Z7",
  "firstSeen": 1730288600,
  "modifiedAt": 1730288600,
  "lastSeen": 1730288600,
  "name": {
    "first": "Johan",
    "middle": "",
    "last": "Greg"
  },
  "generatedName": {
    "first": "Johan",
    "middle": "",
    "last": "Greg"
  },
  "emails": [
    {
      "address": "johan.greg@magicblocks.ai",
      "type": "work",
      "primary": true
    }
  ],
  "primaryEmail": {
    "address": "johan.greg@magicblocks.ai",
    "type": "work",
    "primary": true
  },
  "phones": [
    {
      "number": "+61412345678",
      "type": "mobile",
      "primary": true
    }
  ],
  "primaryPhone": {
    "number": "+61412345678",
    "type": "mobile",
    "primary": true
  },
  "isTest": false,
  "sessionCount": 12,
  "userKnowledge": "Imported from Founders contact list - internal test data",
  "customFields": {
    "utm_source": "founder-referral",
    "utm_campaign": "onboarding-internal",
    "role": "Co-Founder",
    "country": "Australia",
    "timezone": "AEST"
  },
  "link": "https://app.magicblocks.ai/contacts/con_01HRWJ0HAN8F6X9Z7",
  "preview": false
}

Success (201): The Lead has been created successfully.
Bad Request (400) Invalid or missing data. 

2. Using PUT — Update an exiting Lead

Use this endpoint to update an existing lead in your workspace. The update is matched by Contact ID

Endpoint

 PUT https://api.magicblocks.com/v1/contacts/{contactId}

Headers

Same as POST:

Request Body Example

{
  "name": { "first": "Johan", "last": "Greg" },
  "emails": [
    { "address": "johan.greg@magicblocks.ai", "type": "work", "primary": true }
  ],
  "phones": [
    { "number": "+61412345678", "type": "mobile", "primary": true }
  ],
  "custom": {
    "company": "MagicBlocks Pty Ltd",
    "plan": "Enterprise"
  },
  "sendMessageEvents": true,
  "flowEditorName": "Backoffice Sync",
  "flowEditorLink": "https://internal.magicblocks.ai/tools/sync"
} 

Success response (200 OK)

{
  "id": "con_01HRW1X9F5A9QZ7",
  "firstSeen": 1730253452,
  "modifiedAt": 1730256720,
  "lastSeen": 1730256720,
  "name": { "first": "Johan", "middle": "", "last": "Greg" },
  "generatedName": { "first": "Johan", "middle": "", "last": "Greg" },
  "emails": [
    { "address": "johan.greg@magicblocks.ai", "type": "work", "primary": true }
  ],
  "primaryEmail": {
    "address": "johan.greg@magicblocks.ai",
    "type": "work",
    "primary": true
  },
  "phones": [
    { "number": "+61412345678", "type": "mobile", "primary": true }
  ],
  "primaryPhone": {
    "number": "+61412345678",
    "type": "mobile",
    "primary": true
  },
  "isTest": false,
  "sessionCount": 12,
  "userKnowledge": "Imported from Founders contact list - internal test data",
  "customFields": {
    "company": "MagicBlocks Pty Ltd",
    "plan": "Enterprise"
  },
  "link": "https://app.magicblocks.ai/contacts/con_01HRW1X9F5A9QZ7",
  "preview": false
}

Tip:

• If a contact with the provided contactId exists, MagicBlocks updates the record.
• To create a new lead, use POST /v1/contacts instead.

3. Verify in MagicBlocks

After sending your API request:

Go to Leads → All Leads in your workspace

Search for the email or phone you used

You’ll see your new or updated lead appear instantly

You can now assign it to a Goal, Agent, or Campaign

4. Optional — Retrieve Lead Data

You can also fetch your lead details:

5. Example cURL Commands

Create New Lead (POST):

curl -X POST "https://api.magicblocks.com/v1/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "email": "newlead@example.com",
  "first_name": "New",
  "last_name": "Lead",
  "tags": ["imported", "crm"]
}'

Update Existing Lead (PUT):

curl -X PUT "https://api.magicblocks.com/v1/contacts" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "email": "existinglead@example.com",
  "first_name": "Updated",
  "tags": ["vip"]
}'

6. Quick Comparison

8. Common Use Cases

• Create: Add a new lead to your workspace, for example, when a user signs up through a landing page, CRM import, or webhook.
• Update: Update details of an existing lead such as name, phone, or custom fields. Requires the contact ID.
• Get list: Retrieve a list of all leads in your workspace. Supports pagination and filters for search or segmentation.

With the MagicBlocks Contacts API, you can seamlessly:

• Create new leads
• Update existing leads
• Connect data across platforms

Your AI agent can now start “magical conversations” that drive massive conversions, powered by up-to-date lead data.