Skip to content

Import Contacts

POST
/imports/{import_id}/contacts

Import the file’s rows as contacts into a list. THIS WRITES REAL RECORDS.

Two separate authorisations, both resolved for the key’s principal and both required - neither implies the other:

  • may this caller CREATE contacts at all (enforce_object_create);
  • may they WRITE to this particular list (verify_list_access).

update_policy defaults to override: a row matching an existing contact REPLACES that contact’s fields rather than only filling blanks. Send autofill if the file should not win over what is already there.

Authorizations

Parameters

Path Parameters

import_id
required

Id returned by the upload.

string

Id returned by the upload.

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Import a previously uploaded file’s rows as contacts into one list.

object
column_mapping

Source column -> graph8 field. An EMPTY mapping is legal and means the importer falls back to its own header matching, which is why this is not required - but an unmapped column the importer cannot recognise is dropped silently, so preview first.

object
key
additional properties
string
enrich_from_graph8

Match imported rows against the graph8 index and fill missing fields - contacts by work email or LinkedIn URL, companies by domain. Off by default because it is extra work the caller may not want on a file they already trust.

boolean
list_id
required

Audience list the contacts land in. REQUIRED - an import with no destination has nowhere to put the rows, and the caller needs WRITE access to this list, not just read.

integer
update_policy

What happens when a row matches an existing contact. override replaces the field; autofill only fills one that is currently EMPTY. The default is override, matching the app - so an import run without thinking about this WILL overwrite existing data.

string
default: override
Allowed values: autofill override

Responses

200

Successful Response

object
data
required

What the import actually did.

object
failed
Any of:
integer
imported
Any of:
integer
list_id
Any of:
integer
skipped
Any of:
integer
updated
Any of:
integer
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string