Skip to main content

​
POST /api/v1/partner/contacts

Creates a new contact or updates an existing one. A contact represents a person — a customer, client, patient, or borrower — that you intend to send a review request to. Contacts are matched for upsert in this order:
  1. external_id (if provided) — your own stable identifier for the record.
  2. email — if no external_id match is found, the API looks up by email address.
If neither matches an existing contact, a new one is created.

​
Authentication

x-api-key header — see Authentication.

​
Request body

FieldTypeRequiredDescription
emailstringYesContact’s email address. Used for review request delivery and as a fallback upsert key.
namestringNoContact’s full name. Used to personalize review request messages.
professional_idUUIDNoThe eEndorsements professional this contact worked with. Scopes the review request to that professional.
external_idstringNoYour own stable identifier for this contact (e.g. a CRM record ID). Used for idempotent upserts — safe to call repeatedly with the same value.

​
Example request

curl -X POST https://app.eendorsements.com/api/v1/partner/contacts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex.johnson@example.com",
    "name": "Alex Johnson",
    "professional_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "cust_001"
  }'

​
Example response

{
  "id": "7c3e1a2b-4d5f-6789-bcde-f01234567890",
  "email": "alex.johnson@example.com",
  "name": "Alex Johnson",
  "professional_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "cust_001",
  "created_at": "2026-04-27T14:30:00.000Z"
}

​
Contact object

FieldTypeDescription
idUUIDUnique eEndorsements contact identifier. Use this as contact_id when firing events.
emailstringContact’s email address.
namestring | nullContact’s full name.
professional_idUUID | nullThe professional associated with this contact, if set.
external_idstring | nullYour own identifier for this contact, if provided.
created_atISO 8601Timestamp when the contact was first created. Not updated on subsequent upserts.

​
Idempotency

Passing a consistent external_id makes this endpoint safe to call multiple times — for example, on every sync from your CRM. If the contact already exists, the response returns the existing record with any updated fields applied. The created_at timestamp always reflects the original creation time.