--- title: "API" url: "https://help.magicblocks.ai/en/article/leads-api" language: "en" last_updated: "2026-03-18T08:55:28.211Z" --- # 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](https://api.magicblocks.com/v1/api/documentation#tag/Contacts/operation/post_CreateContact) [PUT /contacts – Update an existing Contact](https://api.magicblocks.com/v1/api/documentation#tag/Contacts/operation/put_UpdateContact) **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**](https://app.magicblocks.com/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](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](https://magicblocks.ai/hc) workspace. ### **Endpoint** ``` POST https://api.magicblocks.com/v1/contacts ``` ### **Headers** | Key | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer YOUR_API_KEY` | ### **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: | Key | Value | | --- | --- | | `Content-Type` | `application/json` | | `Authorization` | `Bearer YOUR_API_KEY` | ### **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**](https://magicblocks.ai/hc) 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: | Action | Method | Endpoint | | --- | --- | --- | | Get all contact | `GET` | `/contacts` | | Get contact by ID | `GET` | `/contacts/{contactId}` | | Get contact by email | `GET` | `/contacts/email/{email}` | | Get contact by phone | `GET` | `/contacts/phone/{phone}` | ## **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** | Action | Method | Use Case | | --- | --- | --- | | `POST /contacts` | Create a new contact only | | | `PUT /contacts` | Update an existing contact | | | `GET /contacts` | Retrieve contact details | | ## **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.