Samva
DashboardAPI
ChannelsPlatformMailboxesDevelopersEmail templatesIntegrationsAPI Reference
Contacts

Create a contact

Creates a contact and returns it with a 201 status. An identity another contact already holds is a conflict.

POST
/v1/contacts

Creates a contact and returns it with a 201 status. An identity another contact already holds is a conflict.

Authorization

apiKey
headerx-api-key<token>

Request Body

application/json
  1. body
namespaceId?|null
name*string
Lengthlength <= 120
displayName?|null|null
avatar?string|null|null
identities?array<>|null
profile?|null|null
preferences?|null|null
tags?array<string>|null
status?|null
statusReason?string|null|null
externalId?string|null|null
metadata?|null|null

Response Body

Success

application/json
  1. response
id*ContactId
Match^contact_[0-9a-hjkmnp-tv-z]{16,24}$
namespaceId*|null
name*string
displayName*string|null
avatar*string|null
status*string
Value in"active""paused""blocked""archived"
statusReason*string|null
externalId*string|null
identities*array<>
profile*|null
preferences*|null
tags*array<string>
metadata*|null
importProvenance*|null
createdAt*string
updatedAt*string
Example Request
import { createClient } from "samva";const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });const result = await samva.contacts.create({  "name": "example"});
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"}

Related documentation

Bulk update contact tags

Adds, removes, or replaces tags on multiple contacts in one request, returning counts of updated and failed records. One request carries at most 1000 ids.

Export contacts

Exports contacts as JSON or CSV, returning the serialized data and a count of exported records. The ids filter takes at most 1000 ids.