You can update hundreds or thousands of contacts in a single request through the Inrō API or MCP Server, changing their status, contact details, language, folder assignments, and custom properties all at once. Each contact can get its own values.

This is the way to sync contact data from an external CRM, update a property across a whole segment, or reassign contacts to folders at scale. Updates run in the background, so your request returns instantly no matter how many contacts you send.

Before you start

You'll need a Pro or Trial account and your API token or an MCP connection. See The Inrō Private API: Getting Started for auth.

How it works

When you send a bulk update, Inrō:

Resolves your contacts right away. It matches each identifier (ID, username, or email) and returns any that don't match, so you get instant feedback on what couldn't be found.
Processes the updates in the background. The actual writes happen asynchronously, so your request returns immediately even for thousands of contacts.
Returns a batch task ID. Use it to track progress in real time.

Update via the API

Send a PUT request to /api/v1/contacts/bulk. Each entry in the contacts array has exactly one identifier (id, username, or email) and a contact object with the fields to change:

PUT /api/v1/contacts/bulk{  "contacts": [    { "id": 123, "contact": { "phone": "+15550000001", "folder_ids": [10] } },    { "username": "jane_doe", "contact": { "custom_properties": { "plan": "pro" } } },    { "email": "[email protected]", "contact": { "status": "optout" } }  ]}

The response (202 Accepted) confirms what was queued:

{  "batch_task_id": "abc123",  "status": "pending",  "accepted_count": 2,  "not_found_count": 1,  "not_found": [{ "email": "[email protected]" }]}

Unmatched identifiers come back in not_found right away. The matched contacts are updated in the background.

Track progress

Use the batch task endpoints to follow the update:

GET /api/v1/batch_tasks lists all your batch tasks.
GET /api/v1/batch_tasks/:id returns progress_percentage and estimated_completion_time for one task.

Over MCP, use the list_batch_tasks and get_batch_task tools.

Update via your AI agent (MCP)

If you've connected Claude or ChatGPT, you can ask your agent to bulk-update contacts straight from a conversation. The bulk_update_contacts tool runs the request and returns the batch task ID, which you can check with get_batch_task.

Example: "Update all contacts in my 'March Leads' folder: add them to the 'Hot Prospects' folder."

The MCP tool wraps each contact's changes in an updates object, where the REST endpoint uses contact. The fields are otherwise the same.

What you can update

Per contact, you can set:

status (one of auto, optout, or spam)
email, phone, language
folder assignments (folder_ids)
custom properties

Over MCP, you can also update the contact's name.

⚠️ For status, the API only accepts auto, optout, or spam. Use auto to let Inrō recompute a contact's status. (You don't set statuses like "active" or "inactive" directly; Inrō derives those.)

🐾 Netsuke's Tips

The limit is 1,000 contacts per request. For a larger sync, split it into batches of 1,000 and track each batch task separately.
Partial success is fine: if some identifiers don't match, the update still runs for the ones that do. The unmatched ones are returned in not_found.
Need to set up the custom properties you're writing to? See Managing Contact Properties via API & MCP first.