Saasco logoSaasco logo
Saasco logoSaasco logo

Introduction

Quick StartWhat is Saasco?

Analytics

CRM

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

Email Marketing

Knowledge

Support

Projects

Contacts

Upsert Contact

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.

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

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
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
$idstring | null
$lastSeenstring | null
$lastIdentifiedAtstring | null
$processedAtstring | null
$unsubscribedboolean | string | null
$subscribedboolean | string | null
$unsubscribeReasonstring | null
$unsubscribeSourcestring | null
$emailValidatedboolean | string | null
$lastEmailValidatedAtstring | null
$emailValidationResultstring | null
$emailScorenumber | null
$stripeCustomerIdstring | null
$osstring | null
$browserstring | null
$browserVersionstring | null
$screenHeightnumber | null
$screenWidthnumber | null
$screenDpinumber | null
$devicestring | null
$userAgentstring | null
$ipstring | null
$timezonestring | null
$citystring | null
$countrystring | null
$countryCodestring | null
$continentstring | null
$regionstring | null
$localestring | null
$latitudenumber | null
$longitudenumber | null
$referrerstring | null
$referringDomainstring | null
$initialReferrerstring | null
$initialReferringDomainstring | null
$utmSourcestring | null
$utmMediumstring | null
$utmCampaignstring | null
$utmTermstring | null
$utmContentstring | null
$initialUtmSourcestring | null
$initialUtmMediumstring | null
$initialUtmCampaignstring | null
$initialUtmTermstring | null
$initialUtmContentstring | null
$_toDeleteboolean | string | null
$_emailScoreActionsstring | 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://www.saasco.com/api/v2/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"
  }
}
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}
{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}
{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}

List Related

Lists the other contacts sharing this contact's email address. An address can be held by more than one contact — most often because the same person was identified under two IDs, for example after the customer migrated auth providers — and they are surfaced as related rather than merged. Returns an empty list when the contact has no email or no siblings.

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.