Saasco logoSaasco logo
Saasco logoSaasco logo

Introduction

OverviewGetting startedAgent setupWhat is Saasco?

SDK

Quick startTrackingIdentifyConfigurationWidgetsProperties

MCP

Quick startHow it worksAuthorizationTool reference
Skills for agents

REST API

Quick start
postList ContactsgetGet ContactgetGet By EmailgetList RelatedpostUpsert ContactpatchUpdate ContactdelDelete ContactpostGet PropertiespostCount SubscribedpostMigrate Distinct Id
CRMContacts

Upsert Contact

View as MarkdownAgent setup

Creates a contact, or updates it if one already exists with the same distinct ID. Properties are merged rather than replaced, so omitting a property leaves its current value alone. Send an explicit null to clear one. Omitting distinctId generates one with a soft_ prefix, which is what you want for a contact you only know by email. A new hard distinct ID whose email is already on another contact creates a second, related contact rather than failing. New signups become contacts when the app calls identify() with the user id and email. Use this to import people who already exist. Do not invent people.

POST
/projects/{projectId}/crm/contacts

Authorization

Authorization
AuthorizationBearer <token>

In: header

Path Parameters

projectIdrequiredstring

ID of the project that owns the contact.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

distinctIdstring

A database level unique identifier for the contact. If not provided, one will be automatically generated with a soft_ prefix.

emailstring | null
toDeleteboolean

Marks the contact for deletion instead of writing properties. Prefer the Delete Contact endpoint.

propertiesrequiredobject

Properties to merge. Custom keys are allowed; omitted keys are left unchanged.

agenumber | null
avatarstring | null
birthdaystring | null
createdAtstring | null
descriptionstring | null
displayNamestring | null
emailstring | string | null
firstNamestring | null
genderstring | null
idstring | null
lastNamestring | null
namestring | null
phonestring | null
titlestring | null
usernamestring | null
websitestring | null
anonymousIdstring

Anonymous ID of the browser session this write came from, used to stitch pre-identify events to the contact. Generated when omitted.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/projects/string/crm/contacts" \  -H "Content-Type: application/json" \  -d '{    "properties": {      "property1": "string",      "property2": "string"    }  }'
{  "id": "string",  "createdAt": "string",  "updatedAt": "string",  "projectId": "string",  "distinctId": "string",  "email": "string",  "toDelete": true,  "properties": {    "age": 0,    "avatar": "http://example.com",    "birthday": "string",    "createdAt": "string",    "description": "string",    "displayName": "string",    "email": "user@example.com",    "firstName": "string",    "gender": "string",    "id": "string",    "lastName": "string",    "name": "string",    "phone": "string",    "title": "string",    "username": "string",    "website": "string",    "$id": "string",    "$lastSeen": "string",    "$lastIdentifiedAt": "string",    "$processedAt": "string",    "$unsubscribed": true,    "$subscribed": true,    "$unsubscribeReason": "manual",    "$unsubscribeSource": "string",    "$emailValidated": true,    "$lastEmailValidatedAt": "string",    "$emailValidationResult": "string",    "$emailScore": 0,    "$stripeCustomerId": "string",    "$os": "string",    "$browser": "string",    "$browserVersion": "string",    "$screenHeight": 0,    "$screenWidth": 0,    "$screenDpi": 0,    "$device": "string",    "$userAgent": "string",    "$ip": "string",    "$timezone": "string",    "$city": "string",    "$country": "string",    "$countryCode": "string",    "$continent": "string",    "$region": "string",    "$locale": "string",    "$latitude": 0,    "$longitude": 0,    "$referrer": "string",    "$referringDomain": "string",    "$initialReferrer": "string",    "$initialReferringDomain": "string",    "$utmSource": "string",    "$utmMedium": "string",    "$utmCampaign": "string",    "$utmTerm": "string",    "$utmContent": "string",    "$initialUtmSource": "string",    "$initialUtmMedium": "string",    "$initialUtmCampaign": "string",    "$initialUtmTerm": "string",    "$initialUtmContent": "string",    "$_toDelete": true,    "$_emailScoreActions": "string",    "property1": "string",    "property2": "string"  }}

List Related

Lists other contacts for the same person: contacts sharing this email, contacts on the same Stripe customer, and contacts Stripe relates by a shared card number (the Dashboard Related customers list). Card matches come from charge search on the card fingerprint. Returns an empty list when nothing matches.

Update Contact

Updates a contact's properties. Properties are merged, so omitted ones keep their current values. Functionally the same as Upsert Contact for a contact that already exists; use this when you want the call to be explicitly an update.