CRM

Bulk import records (create or update), optionally into a list

postapi.modelmatch.com/v1/crm/import

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Body application/json

createMissingListsboolean

Create lists rows name that the list owner doesn't have yet, owned by ownerUserId (else the caller).

dryRunboolean

Plan only: return what the import WOULD do (per-row created / updated / failed, lists it would find or create) without writing anything. Always synchronous.

entityTypeenum

Entity type for created rows (default per object).

Options:loagentcompanybranch

externalSourcestring

Source system the rows' externalIds belong to (e.g. "legacy-mm"). Defaults to "import".

fileNamestring

Source file name, shown in import history.

fileRowsinteger

Data rows in the source file (the client's count, including rows it rejected before sending) — the check report's file rows.

importBatchKeystring

This batch's key within its run (e.g. "2/5"). A batch resent under a key the run already recorded is refused (409).

importRunIdstring

Import history run id, minted by the client per run and sent with every batch of it — the batches become one history entry.

listIdstring | null

listStatusesobject

Status labels, in order, per list name — the status vocabulary of lists this batch creates (else the default statuses).

Show child attributes

[key: string]string[]

objectTypeenumrequired

Options:peoplecompanies

ownerUserIdstring

Default working owner (member userId) for created rows; a row's own ownerUserId overrides it. Both fall back to the caller. Assigning an owner other than the caller requires an org admin.

rowsobject[]required

Show child attributes

addressstring

citystring

companystring

Employer override for people rows; ignored on companies imports.

countystring

countyFipsstring

customValuesobject

Show child attributes

[key: string]object

Show child attributes

boolboolean | null

dateinteger | null

multistring[] | null

numnumber | null

textstring | null

emailstring

emailsstring[]

Additional emails in submitted order (first non-duplicate becomes primary via oldest-wins).

entityIdstring

Set to update an existing record; omit to create one.

externalIdstring

The record's id in the source system (unique per org + batch externalSource). A known id updates that record; an unknown one is stamped on the created record, so re-running an import never duplicates. A record holds at most one id — a different one fails the row with EXTERNAL_ID_CONFLICT.

facebookstring

instagramstring

linkobject

Match pointer; an MM-sourced link populates the entity mirror.

Show child attributes

entityIdstringrequired

mmaIdstring

nmlsIdstring

propertyIdstring

sourceenumrequired

Options:mmmanual

linkedinstring

listStatusstring

Status (id or label) within the row's first list; becomes the record's status. Fails the row when it isn't one of that list's.

listsstring[]

Lists this row's record joins, by name (case/space-insensitive), among the list owner's lists — the batch ownerUserId, else the caller. A name with no match fails the row unless the batch sets createMissingLists.

locationstring

namestring

notestring

Plain-text timeline note appended to the record's activity feed, authored by the importing user. Distinct from notes (the Description scalar).

notesstring

ownerUserIdstring

Working owner (member userId) for this CREATED record; overrides the batch-level ownerUserId. Ignored on update rows (entityId set) — import never reassigns an existing record's owner. Assigning any owner other than the caller requires an org admin.

phoneobject

Show child attributes

e164stringrequired

rawstringrequired

phonesobject[]

Additional phones in submitted order.

Show child attributes

e164stringrequired

rawstringrequired

realtorstring

rejectReasonstring

The client already failed this row (e.g. an undialable phone): it is logged as failed with this reason and never written.

sourceLineinteger

The row's line in the source file; kept in import history so the download points back at the file.

statestring

statusstring

subtitlestring

timelineNotesobject[]

Dated note history (e.g. a legacy notes export), appended as plain notes authored by the record's owner. Keyed: a note the record already has (deleted ones included) is skipped, so re-runs never double it. Distinct from note, which is append-only.

Show child attributes

bodystringrequired

keystring

Stable id from the source system; absent ⇒ a hash of date + text.

occurredAtstring

ISO date-time the note was written (the timeline backdates to it); an unreadable date fails the row.

titlestring

Role title override for people rows (the record's Title field, column and filter) — distinct from subtitle, the display line under the name. Trimmed; blank reads as absent. Overwrites on update rows. Ignored on companies imports.

websitestring

xstring

youtubestring

zillowstring

zipstring

Responses

200objectSmall batch: per-row outcomes plus the batch tally.

Show attributes

dataobjectrequired

Show child attributes

creatednumberrequired

dryRunboolean

enrichJobIdstring

failednumberrequired

listsobject[]

Lists the rows named (row lists), and which this batch created.

Show child attributes

createdbooleanrequired

listIdstringrequired

namestringrequired

resultsobject[]required

Show child attributes

codeenum

Failure reason on a failed row; drives friendly client copy. Absent on success.

Options:MISSING_NAMERECORD_NOT_FOUNDWRONG_OBJECT_TYPENO_ACCESSUNKNOWN_FIELDEXTERNAL_ID_CONFLICTINVALIDINTERNAL

entityIdstring

errorstring

outcomeenumrequired

Options:createdupdatedfailed

rownumberrequired

totalnumberrequired

updatednumberrequired

202objectLarge batch accepted for asynchronous processing; returns a job handle.

Show attributes

dataobjectrequired

Show child attributes

jobIdstringrequired

Poll GET /crm/import/{jobId} for progress + per-row errors.

400objectValidation error

401objectUnauthorized

403objectForbidden (authenticated, but missing required context — e.g. no active organization)

404objectNot found

409objectThis batch's `importBatchKey` was already recorded on the run — a resend, refused.

413objectResponse payload too large — detail endpoint capped to fit Lambda response limits

502objectAuth service unavailable (owner-assignment member lookup failed).

503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.

curl -X POST "https://api.modelmatch.com/v1/crm/import" \
  -H "x-api-key: $MODEL_MATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objectType": "people",
    "rows": [
      {}
    ],
    "entityType": "lo",
    "createMissingLists": true,
    "dryRun": true,
    "externalSource": "<string>",
    "fileName": "<string>",
    "fileRows": 123
  }'

import { createClient, Crm } from "@model-match/api";

createClient({ apiKey: process.env.MODEL_MATCH_API_KEY });

const { data, error } = await Crm.importCrmRecords({
  body: {
    objectType: "people",
    rows: [
      {}
    ],
    entityType: "lo",
    createMissingLists: true,
    dryRun: true,
    externalSource: "<string>",
    fileName: "<string>",
    fileRows: 123
  }
});

import os
import requests

res = requests.post(
    "https://api.modelmatch.com/v1/crm/import",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
    json={
        "objectType": "people",
        "rows": [
            {}
        ],
        "entityType": "lo",
        "createMissingLists": True,
        "dryRun": True,
        "externalSource": "<string>",
        "fileName": "<string>",
        "fileRows": 123
    },
)
data = res.json()

200 response

{
  "data": {
    "created": 123.45,
    "dryRun": true,
    "enrichJobId": "<string>",
    "failed": 123.45,
    "lists": [
      {
        "created": true,
        "listId": "<string>",
        "name": "<string>"
      }
    ],
    "results": [
      {
        "code": "MISSING_NAME",
        "entityId": "<string>",
        "error": "<string>",
        "outcome": "created",
        "row": 123.45
      }
    ],
    "total": 123.45,
    "updated": 123.45
  }
}