Find or create a contact
Looks up exactly one identifier through `lookup: { type, value }`.
Looks up exactly one identifier through lookup: { type, value }. Returns { contact, created: false } unchanged when it exists. Otherwise creates the lookup identity (or external ID), applies create attributes, and returns { contact, created: true }. Additional addresses belong in create.identities, custom fields in create.profile.customFields; custom field keys must be defined and values must match their types. An external ID lookup cannot be contradicted by create.externalId. Creation returns HTTP 409 ConflictError if an externalId or address belongs to another contact; the conflicting field is named and no contact is created. Use the update endpoint to change an existing contact.
apiKeyx-api-key<token>application/json- body
namespaceId?|nulllookup*||create?|nullSuccess
application/json- response
contact*created*booleanimport { createClient } from "samva";const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });const result = await samva.contacts.findOrCreate({ "lookup": { "type": "email", "value": "example" }});{ "contact": { "id": "string", "namespaceId": "string", "name": "string", "displayName": "string", "avatar": "string", "status": "active", "statusReason": "string", "externalId": "string", "identities": [ { "id": "string", "type": "email", "identifier": "string", "verified": true, "channels": [ { "channel": "sms", "reachability": "unknown", "consent": { "status": "opted_in", "source": "string", "capturedAt": "string", "proof": { "property1": "string", "property2": "string" } } } ] } ], "profile": { "firstName": "string", "lastName": "string", "company": "string", "jobTitle": "string", "location": { "country": "string", "state": "string", "city": "string", "timezone": "string" }, "customFields": { "property1": "string", "property2": "string" }, "source": "api" }, "preferences": { "preferredChannels": [ "sms" ], "language": "string", "timezone": "string", "notifications": { "email": true, "sms": true, "whatsapp": true, "quiet_hours": { "start": "string", "end": "string" } } }, "tags": [ "string" ], "metadata": { "property1": "string", "property2": "string" }, "importProvenance": { "first": { "jobId": "string", "topicId": "string", "preset": "beehiiv", "importedAt": "string", "summary": { "signupAt": { "value": "string", "kind": "time" }, "sources": [ "string" ], "omittedSources": 0 }, "evidence": [ { "file": "string", "row": -9007199254740991, "declared": { "kind": "status_column" }, "suppressionFree": true, "sourceStatus": "string", "signupAt": "string", "source": "string" } ] }, "latest": { "jobId": "string", "topicId": "string", "preset": "beehiiv", "importedAt": "string", "summary": { "signupAt": { "value": "string", "kind": "time" }, "sources": [ "string" ], "omittedSources": 0 }, "evidence": [ { "file": "string", "row": -9007199254740991, "declared": { "kind": "status_column" }, "suppressionFree": true, "sourceStatus": "string", "signupAt": "string", "source": "string" } ] } }, "createdAt": "string", "updatedAt": "string" }, "created": true}