API

Adding Data to Contacts via API

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

Official API Docs:

POST /contacts – Create a new Contact

PUT /contacts – Update an existing Contact

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

• Automatically sync customer data from a form submission, checkout, or CRM update.
• Enrich existing Contacts with additional attributes like UTM, plan, country, or consent.
• Trigger an Agent workflow right when a Contact enters your system (e.g., send welcome message, qualify contact, 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 Contact

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 Contact (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 Contact has been created successfully.
Bad Request (400) Invalid or missing data. 

2. Using PUT — Update an exiting Contact

Use this endpoint to update an existing contact 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 contact, use POST /v1/contacts instead.

3. Verify in MagicBlocks

After sending your API request:

Go to Contacts → All Contacts in your workspace

Search for the email or phone you used

You’ll see your new or updated contact appear instantly

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

4. Optional — Retrieve Contact Data

You can also fetch your contact details:

5. Example cURL Commands

Create New Contact (POST):

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

Update Existing Contact (PUT):

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

6. Quick Comparison

8. Common Use Cases

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

With the MagicBlocks Contacts API, you can seamlessly:

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

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