Contacts
POST Upsert contact
Create or update a contact matched by email, phone, or externalId.
Endpoint
POST https://api.strideops.ai/v1/contacts/upsertLooks up an existing contact by the chosen match key. Updates it if found, creates it otherwise. Idempotent - safe to retry.
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
matchOn | enum | yes | "email" | "phone" | "externalId". |
email | string | conditional | Required when matchOn: "email". |
phone | string | conditional | Required when matchOn: "phone". |
externalId | string | conditional | Required when matchOn: "externalId". |
All Create contact fields | no | Merged into the existing record (or used for create). |
Merge semantics
- Scalar fields (
firstName,lastName, etc.): the supplied value wins. tags: union of existing + supplied (no duplicates).customFields: shallow merge - supplied keys overwrite existing.nullvalues clear the field.
Response
Returns the upserted contact in the same shape as Create contact. The response includes a created boolean - true if a new record was inserted, false if an existing record was updated.
{
"id": "ctc_…",
"created": false,
"email": "jane@example.com",
"firstName": "Jane",
...
}Example
curl -X POST https://api.strideops.ai/v1/contacts/upsert \
-H "Authorization: Bearer $STRIDE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"matchOn": "email",
"email": "jane@example.com",
"firstName": "Jane",
"tags": ["webinar-2026-q2"]
}'