Find a contact
Looks up a single contact by exactly one of email address, phone number, or external ID and returns null when no contact matches.
POST
Looks up a single contact by exactly one of email address, phone number, or external ID and returns null when no contact matches. A phone number without + is read in the organization's default region.
apiKeyheader
x-api-key<token>application/json- body
namespaceId?|nullemail?string|nullphone?string|nullexternalId?string|nullSuccess
application/json- response
id*ContactIdMatch
^contact_[0-9a-hjkmnp-tv-z]{16,24}$namespaceId*|nullname*stringdisplayName*string|nullavatar*string|nullstatus*stringValue in
"active""paused""blocked""archived"statusReason*string|nullexternalId*string|nullidentities*array<>profile*|nullpreferences*|nulltags*array<string>metadata*|nullimportProvenance*|nullcreatedAt*stringupdatedAt*stringimport { createClient } from "samva";const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });const result = await samva.contacts.find({});Example Response
{ "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"}