importContact
Create-or-get a contact migrated from an external system.
POST/api/v1/callIMPORTidempotent · 24 hruns as the key's owner
Create-or-get a contact migrated from an external system. Keyed on (sourceSystem, externalId): replaying the same record returns the existing contact with wasCreated=false instead of duplicating. Honors historical createdAt/updatedAt (must be in the past) and suppresses live side effects: no workflow triggers, no notifications, no default assignments. The contact field takes the same shape as createContact.
curl https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer $GOLIATH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"operationId": "importContact",
"variables": {
"input": {
"contact": {
"sellerFirstName": "<String>",
"sellerLastName": "<String>"
},
"sourceSystem": "<String>",
"externalId": "<String>"
}
}
}'import { GoliathClient } from '@goliath-data/sdk'
const goliath = new GoliathClient({
apiKey: process.env.GOLIATH_API_KEY!,
baseUrl: 'https://server.goliathdata.com',
})
const result = await goliath.crmImport.importContact(
{
input: {
contact: {
sellerFirstName: '<String>',
sellerLastName: '<String>'
},
sourceSystem: '<String>',
externalId: '<String>'
}
},
{ idempotencyKey: crypto.randomUUID() },
)const res = await fetch('https://server.goliathdata.com/api/v1/call', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GOLIATH_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
operationId: 'importContact',
variables: {
input: {
contact: {
sellerFirstName: '<String>',
sellerLastName: '<String>'
},
sourceSystem: '<String>',
externalId: '<String>'
}
}
}),
})
const { data, errors } = await res.json()Variables
The example sends only what the schema requires. Some operations also need one of several optional variables (one filter or another, say); the description above says which.
inputImportContactInput!required
contactCreateContactInput!required
The contact's fields, in the same shape the ordinary createContact mutation accepts.
sourceSystemString!required
Short slug identifying the system this record came from (e.g. "resimpli", "podio"). Lowercase letters, digits, and hyphens only, at most 32 characters. Part of the idempotency key.
externalIdString!required
The record's id in the source system. At most 256 characters. Part of the idempotency key: importing the same (sourceSystem, externalId) twice returns the existing contact.
createdAtDateTime
When the record was created in the source system. Must be in the past (any time since 1970). Omitted = now.
updatedAtDateTime
When the record was last updated in the source system. Must be in the past and not before createdAt; requires createdAt to be provided as well (an omitted createdAt means "now", which would put the update before creation).
Every field, all the way down
variables
[
{
"name": "input",
"type": "ImportContactInput!",
"required": true,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "contact",
"type": "CreateContactInput!",
"required": true,
"description": "The contact's fields, in the same shape the ordinary createContact mutation accepts.",
"defaultValue": null,
"fields": [
{
"name": "address",
"type": "AddressInput",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "id",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "line1",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "line2",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "city",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "state",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "zip",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
}
]
},
{
"name": "addressString",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "type",
"type": "PipelineItemType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"LISTING",
"INVESTMENT",
"UNDETERMINED",
"BUYER"
]
},
{
"name": "sellerFirstName",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "sellerLastName",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "addMailingAddresses",
"type": "[CreateContactMailingAddressInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "addressString",
"type": "String!",
"required": true,
"description": "Raw single-line address; resolved via MailingAddressResolutionService (property → address → raw).",
"defaultValue": null
},
{
"name": "propertyElasticsearchId",
"type": "ID",
"required": false,
"description": "Instant-duplicate case: the property (Property.id / esId) the user copied this mailing address from: e.g. \"use my subject property as the mailing address\". When set, the mailing row links straight to that property (no ES search).",
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": "Display order; lower is higher (0 = primary).",
"defaultValue": null
}
]
},
{
"name": "addPhoneNumbers",
"type": "[CreateContactPhoneNumberInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "phoneNumber",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "phoneType",
"type": "PhoneType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"MOBILE",
"RESIDENTIAL",
"LANDLINE",
"UNKNOWN"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "addEmails",
"type": "[CreateContactEmailInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "email",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "addCustomFieldValues",
"type": "[CreateContactCustomFieldInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "customFieldId",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "textValue",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "calendarDate",
"type": "String",
"required": false,
"description": "Preferred DATE value as a strict calendar day (YYYY-MM-DD). Do not combine with dateValue.",
"defaultValue": null
},
{
"name": "dateValue",
"type": "DateTime",
"required": false,
"description": "Legacy DATE compatibility input. Prefer calendarDate for new clients; do not combine both forms.",
"defaultValue": null
},
{
"name": "numberValue",
"type": "Float",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "dropdownSelectedValues",
"type": "[String!]",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "subContacts",
"type": "[CreateSubContactInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "name",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "relation",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "phoneNumbers",
"type": "[CreateContactPhoneNumberInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "phoneNumber",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "phoneType",
"type": "PhoneType",
"required": false,
"description": null,
"defaultValue": null,
"enumValues": [
"MOBILE",
"RESIDENTIAL",
"LANDLINE",
"UNKNOWN"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "emails",
"type": "[CreateContactEmailInput!]",
"required": false,
"description": null,
"defaultValue": null,
"fields": [
{
"name": "email",
"type": "String!",
"required": true,
"description": null,
"defaultValue": null
},
{
"name": "verificationStatus",
"type": "VerificationStatus!",
"required": true,
"description": null,
"defaultValue": null,
"enumValues": [
"VERIFIED",
"UNVERIFIED",
"WRONG"
]
},
{
"name": "note",
"type": "String",
"required": false,
"description": null,
"defaultValue": null
},
{
"name": "ranking",
"type": "Int",
"required": false,
"description": null,
"defaultValue": null
}
]
}
]
},
{
"name": "addUserGroupIds",
"type": "[ID!]",
"required": false,
"description": null,
"defaultValue": null
}
]
},
{
"name": "sourceSystem",
"type": "String!",
"required": true,
"description": "Short slug identifying the system this record came from (e.g. \"resimpli\", \"podio\"). Lowercase letters, digits, and hyphens only, at most 32 characters. Part of the idempotency key.",
"defaultValue": null
},
{
"name": "externalId",
"type": "String!",
"required": true,
"description": "The record's id in the source system. At most 256 characters. Part of the idempotency key: importing the same (sourceSystem, externalId) twice returns the existing contact.",
"defaultValue": null
},
{
"name": "createdAt",
"type": "DateTime",
"required": false,
"description": "When the record was created in the source system. Must be in the past (any time since 1970). Omitted = now.",
"defaultValue": null
},
{
"name": "updatedAt",
"type": "DateTime",
"required": false,
"description": "When the record was last updated in the source system. Must be in the past and not before createdAt; requires createdAt to be provided as well (an omitted createdAt means \"now\", which would put the update before creation).",
"defaultValue": null
}
]
}
]Response
What comes back under data: a list shows as one entry, and a value as its type.
response shape
{
"data": {
"crmImportMutation": {
"importContact": {
"contactId": "<ID>",
"wasCreated": true
}
}
}
}Errors
400
unknown_variableA variable the operation does not declare. A typo is refused rather than silently dropped.
401
unauthorizedNo bearer header, or the key is invalid or revoked.
403
insufficient_scopeThe key lacks the scope the operation requires.
403
forbiddenA referenced record does not exist, was deleted, or is outside your organization. The gateway cannot tell those apart.
409
idempotency_conflictA request with this Idempotency-Key is still in flight.
Idempotency
Send an Idempotency-Key of 1 to 255 characters. A finished request retried with the same key replays its stored response, marked Idempotency-Replayed: true; one still in flight returns 409 idempotency_conflict. Keys expire after 24 hours. Write without fear →