API v1
v1
View as Markdown

Start an import

PUT /api/v1/imports/{accountImport}

Choose where a file that has been read goes and which of its contacts is you, then start writing it.

Name a vault of the account with vault, or a new vault with vault_name. A file holding several vaults takes neither: each of its vaults arrives as a new vault of its own, and the contact each one marks as you is added to its Me, so me_contact is ignored too.

The contact named by me_contact is added to the Me contact of the vault: its values fill only what Me leaves empty, and its relationships and life events attach to Me. Send null to import every contact as somebody else. The contacts of the file come from GET /imports/{accountImport}/contacts.

The limits of the account are compared with the whole file before anything is written. A file that would take the account past its contacts, its vaults or its storage answers 422, saying which limit, and nothing is written. So does an import that is not waiting for a decision.

An import only adds records. It never changes or removes one the vault already holds. It is written in the background: ask for the import to follow its progress.

Parameters

Sent as JSON. Anything not listed here is ignored.

accountImport uuid Required

The id of the import. One belonging to another account answers 404.

vault string Optional

A vault of the account to write the file into, named by its slug or its id. A vault of another account answers 404.

vault_name string Optional

The name of a new vault to write the file into, up to 255 characters. Required when vault is left out, unless the file holds several vaults.

me_contact string Optional

The id, in the file, of the contact who is you, or null for none. A contact the file does not hold answers 422.

Returns

The import object, writing.

data object

The import.

data.type string

Always account_import. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.

data.id string

The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.

data.attributes object

Everything the record holds.

data.attributes.status string

Where the import stands: reading, refused, read, writing, rolling_back, rolled_back, rollback_failed or completed. rollback_failed means an undo kept failing and what the import wrote is still in place. Nothing is written into a vault before the file is read and you have chosen where it goes.

data.attributes.source_format string

What the file is: monica_4 for an export of Monica 4, monica for an export of this application. Null while the file is read, and when it was refused as neither.

data.attributes.refusal string

Why the file cannot be imported, when the status is refused. Null otherwise.

data.attributes.already_imported_into array

The vaults this same file was completely imported into before. An import only adds, so importing it again into one of them writes every record a second time.

data.attributes.already_imported_into[] uuid

The id of one of those vaults.

data.attributes.progress object

How far the writing has gone.

data.attributes.progress.done integer

How many records are written.

data.attributes.progress.total integer

How many records there are to write, known once the file is read.

data.attributes.vault uuid

The id of the vault the file is written into, or null until one is chosen.

data.attributes.me_contact string

The id, in the file, of the contact who is you, or null for none. Until you choose, it is the contact the file names as its owner.

data.attributes.created_at timestamp

When the file was received, as a count of seconds since 1970.

data.attributes.ended_at timestamp

When the import completed or finished being undone, as a count of seconds since 1970, or null.

data.attributes.summary array

What the file holds, one entry per kind of record, once it is read. Null while it is read.

data.attributes.summary[] object

One kind of record in the file.

data.attributes.summary[].kind string

The kind of record, as the file names it: contacts, notes, relationships, audit_logs and so on.

data.attributes.summary[].found integer

How many the file holds.

data.attributes.summary[].left_out integer

How many will not come over, because this product keeps nothing of that kind.

data.attributes.report array

What became of the records of the file, one entry per kind, once the import has completed. Null before that, and for an import that was undone, since nothing of it stayed.

data.links object

Where to find this record.

data.links.self string

The absolute address this record is read from.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

PUT
curl https://my.monicahq.com/api/v1/imports/3f8a1c52-7d4e-4b19-9a06-c2e5b8d71f40 \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vault_name": "Dunder Mifflin",
"me_contact": "10000000-0000-4000-8000-000000000001"
}'
const response = await fetch('https://my.monicahq.com/api/v1/imports/3f8a1c52-7d4e-4b19-9a06-c2e5b8d71f40', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
vault_name: 'Dunder Mifflin',
me_contact: '10000000-0000-4000-8000-000000000001',
}),
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/imports/3f8a1c52-7d4e-4b19-9a06-c2e5b8d71f40', [
'vault_name' => 'Dunder Mifflin',
'me_contact' => '10000000-0000-4000-8000-000000000001',
]);
Response 202
{
"data": {
"type": "account_import",
"id": "3f8a1c52-7d4e-4b19-9a06-c2e5b8d71f40",
"attributes": {
"status": "writing",
"source_format": "monica_4",
"refusal": null,
"summary": [
{
"kind": "contacts",
"found": 1767,
"left_out": 0
},
{
"kind": "relationships",
"found": 94,
"left_out": 0
},
{
"kind": "audit_logs",
"found": 3327,
"left_out": 3327
}
],
"already_imported_into": [
"9b2d4f6a-1e3c-4a5b-8c7d-0f1e2d3c4b5a"
],
"progress": {
"done": 0,
"total": 4512
},
"vault": "c4e6a8b0-2d4f-4a6b-9c8d-1e3f5a7b9c0d",
"me_contact": "10000000-0000-4000-8000-000000000001",
"report": null,
"created_at": 1792310400,
"ended_at": null
},
"links": {
"self": "https://my.monicahq.com/api/v1/imports/3f8a1c52-7d4e-4b19-9a06-c2e5b8d71f40"
}
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.