Managed profiles and MCP

Worked example

Import two people, follow the job, ask the account owner to review the new card, then publish it. IDs and revisions are placeholders; use the values your own responses return.

Find a card ID

You only need a card ID to update a card that was not created by your import. Open the card in the editor: the number at the end of the address, as in https://zapped.to/vcard-update/123, is its ID. Or list the account's cards with GET /api/vcards using a key that also holds the vcards:read permission; each card's ID is its id.

curl 'https://zapped.to/api/vcards/' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY'

1. Submit the import POST /imports

Send one row per person. A row without vcard_id creates a private draft card the first time its external_id is seen and updates that same card on later imports. To update a card you already have, add its vcard_id. Nothing is published.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/imports' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_key": "import-2026-09-25-a",
    "rows": [
        {
            "external_id": "person-001",
            "command": {
                "name": "Ada Example",
                "theme": "boston",
                "settings": {
                    "job_title": "Designer"
                },
                "contacts": {
                    "email": "[email protected]",
                    "phone": "+15550100100"
                },
                "photo_url": "https://photos.example.com/ada.jpg"
            }
        },
        {
            "external_id": "person-002",
            "vcard_id": 123,
            "command": {
                "settings": {
                    "job_title": "Head of Sales"
                }
            }
        }
    ]
}'

Response 202 Accepted

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "job_id": 456,
        "status": "accepted",
        "created": true
    }
}

2. Poll the import status POST /imports/status

Rows run in the background. Poll every few seconds until status is complete and pending is 0. Each row reports created, updated, unchanged, invalid, conflict, cancelled or pending, with the card ID and, when a row was not applied as sent, a detail. A row with a photo_url also reports photo: pending until the photo is fetched, then attached, or not_attached with a photo_detail. Keep polling while photos.pending is above 0 if you need the photo result.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/imports/status' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_id": 456
}'

Response 200 OK

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "job_id": 456,
        "status": "complete",
        "row_count": 2,
        "pending": 0,
        "paused": false,
        "rows": [
            {
                "external_id": "person-001",
                "outcome": "created",
                "vcard_id": 124,
                "detail": null,
                "photo": "attached",
                "photo_detail": null
            },
            {
                "external_id": "person-002",
                "outcome": "updated",
                "vcard_id": 123,
                "detail": null,
                "photo": null,
                "photo_detail": null
            }
        ],
        "photos": {
            "pending": 0,
            "attached": 1,
            "not_attached": 0
        }
    }
}

3. Read the new draft's revisions POST /profiles/open

A review names the exact revisions the owner will see, so open each card first. Send these numbers unchanged in the next steps.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/open' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 124
}'

Response 200 OK

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "vcard_id": 124,
        "draft_revision": 1,
        "published_revision": 0
    }
}

4. Request the owner's review POST /profiles/reviews

Give review_url to the account owner. Only the owner, signed in to Zapped, can approve or reject on that page; an API key cannot approve.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/reviews' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
        {
            "vcard_id": 124,
            "expected_draft_revision": 1,
            "expected_published_revision": 0
        }
    ]
}'

Response 201 Created

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "review_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
        "review_url": "https://zapped.to/managed-profile-review/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
        "expires_at": "2026-10-02 09:00:00",
        "created": true,
        "items": [
            {
                "vcard_id": 124,
                "draft_revision": 1,
                "published_revision": 0,
                "decision": "pending"
            }
        ]
    }
}

5. Poll the review POST /profiles/reviews/status

Poll now and then, for example once a minute, since every poll counts toward the key's quota. Publish only items whose decision is approved. A stale item means the draft changed after the request: open it again and request a new review.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/reviews/status' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "review_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}'

Response 200 OK

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "review_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
        "expires_at": "2026-10-02 09:00:00",
        "expired": false,
        "items": [
            {
                "vcard_id": 124,
                "draft_revision": 1,
                "published_revision": 0,
                "decision": "approved",
                "published": false,
                "result_published_revision": null
            }
        ]
    }
}

6. Publish the approved revisions POST /profiles/publish

Send the approved revisions exactly. If the response is lost or says commit_outcome_unknown, send the same request again: a publication that was saved answers with already_published set to true.

Request

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/publish' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 124,
    "expected_draft_revision": 1,
    "expected_published_revision": 0
}'

Response 200 OK

{
    "success": true,
    "api_version": "2026-09-22",
    "data": {
        "vcard_id": 124,
        "published": true,
        "published_revision": 1
    }
}

Over MCP the same steps are the tools submit_import, get_import_job, open_profile, request_review, get_review and publish_approved, with the request fields above as arguments. get_import_job reports each row by its position in the import instead of its external_id.

Endpoints

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/open' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 123
}'

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/autosave' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 123,
    "expected_draft_revision": 4,
    "expected_published_revision": 2,
    "payload": {
        "name": "Ada Example",
        "settings": {
            "job_title": "Designer"
        }
    }
}'

curl -X POST 'https://zapped.to/api/managed-profiles/imports/preview' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "headers": [
        "id",
        "name",
        "job_title"
    ],
    "mapping": {
        "external_id": 0,
        "name": 1,
        "job_title": 2
    },
    "csv": "id,name,job_title\nperson-001,Ada Example,Designer\n"
}'

curl -X POST 'https://zapped.to/api/managed-profiles/imports' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_key": "import-2026-09-24",
    "rows": [
        {
            "external_id": "person-001",
            "command": {
                "name": "Ada Example"
            }
        }
    ]
}'

curl -X POST 'https://zapped.to/api/managed-profiles/imports/status' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_id": 456
}'

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/media' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -F vcard_id=123 -F role=avatar \
  -F expected_draft_revision=4 -F expected_published_revision=2 \
  -F [email protected]

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/blocks' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 123,
    "expected_draft_revision": 5,
    "expected_published_revision": 2,
    "operation": "create",
    "type": "email",
    "client_key": "work-email",
    "name": "Email",
    "value": "[email protected]"
}'

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/reviews' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
        {
            "vcard_id": 123,
            "expected_draft_revision": 6,
            "expected_published_revision": 2
        }
    ]
}'

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/reviews/status' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "review_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}'

curl -X POST 'https://zapped.to/api/managed-profiles/profiles/publish' \
  -H 'Authorization: Bearer YOUR_INTEGRATION_KEY' \
  -H 'Zapped-Api-Version: 2026-09-22' \
  -H 'Content-Type: application/json' \
  -d '{
    "vcard_id": 123,
    "expected_draft_revision": 6,
    "expected_published_revision": 2
}'

Status codes

Error codes

A failed request answers success: false with error.code, one of the codes below, and a readable error.message. Codes are stable; messages may change. Over MCP, unauthenticated, insufficient_scope, every 429 and every 503 arrive as JSON-RPC errors with the code in data.code, unknown_tool is JSON-RPC error -32602, and every other code is a tool result with isError set and the code in structuredContent.code.

An import row that is not applied is not an error: the import succeeds and imports/status reports the row as invalid or conflict with a detail. A publication that was saved but deferred its follow-up work still answers 200 with published set to true.

MCP tools

The same workflow is available to AI assistants over MCP (Streamable HTTP, protocol 2025-11-25), with the API key as a bearer header. A tool whose permission the key lacks is listed as unavailable.

MCP address

Connect an assistant

Pick your tool. Create a key on the API keys page, then use it in place of YOUR_INTEGRATION_KEY.

• Claude Code
• Codex
• Cursor and others
• VS Code
• OpenCode

claude mcp add --transport http --scope user zapped 'https://zapped.to/mcp' \
  --header 'Authorization: Bearer YOUR_INTEGRATION_KEY'

export ZAPPED_KEY='YOUR_INTEGRATION_KEY'
codex mcp add zapped --url 'https://zapped.to/mcp' \
  --bearer-token-env-var ZAPPED_KEY

{
    "mcpServers": {
        "zapped": {
            "url": "https://zapped.to/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_INTEGRATION_KEY"
            }
        }
    }
}

{
    "servers": {
        "zapped": {
            "type": "http",
            "url": "https://zapped.to/mcp",
            "headers": {
                "Authorization": "Bearer ${input:zapped-key}"
            }
        }
    },
    "inputs": [
        {
            "type": "promptString",
            "id": "zapped-key",
            "description": "Zapped integration key",
            "password": true
        }
    ]
}

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "zapped": {
            "type": "remote",
            "url": "https://zapped.to/mcp",
            "headers": {
                "Authorization": "Bearer {env:ZAPPED_KEY}"
            }
        }
    }
}

Theme keys

Use a key from this list in the Theme column of a CSV import, in the theme field of profiles/autosave and of import commands, and in the MCP tools. Keys are case sensitive and must match exactly. Leave the theme out, or the CSV cell blank, to keep the card's current theme; a new card gets the default theme.