Contacts API

Create, update, fetch, and delete contacts.

Endpoints

• POST /v1/contacts — upsert (create or update)
• GET /v1/contacts/{identifier} — fetch
• PATCH /v1/contacts/{identifier} — update (must exist)
• DELETE /v1/contacts/{identifier} — delete (GDPR)

Listing Contacts

Bulk contact listing is available in the dashboard. The API supports single-contact operations only.

Identifiers

{identifier} can be one of:

• UUID (550e8400-e29b-41d4-a716-446655440000)
• external_id (user_123)
• email (user@example.com)
• phone (+46701234567)

URL-encode identifiers in the path:

• user@example.com → user%40example.com
• +46701234567 → %2B46701234567

See Contacts for how identifiers are resolved.

---

POST /v1/contacts

Upsert a contact. If a contact with the provided email, phone, or external_id already exists, Sendivent updates it. Otherwise it creates a new contact. If you send multiple identifiers, Sendivent matches an existing contact by any of them.

Request body

At least one identifier is required: email, phone, or external_id.

Field	Type	Required	Description
email	string	conditional	Email address
phone	string	conditional	Phone number (E.164)
external_id	string	optional	Your user ID
name	string	optional	Full name
avatar	string	optional	Avatar URL
username	string	optional	Username
slack_id	string	optional	Slack member ID (U...)
meta	object	optional	Custom metadata

Custom fields: Prefer meta. Any unknown top-level fields are treated as metadata and stored in meta (snake_case → camelCase). If both are provided, meta is stored as-is and unknown top-level fields are merged into it.

Example

curl -X POST "https://api.sendivent.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "premium@example.com",
    "name": "Bob Smith",
    "meta": {
      "subscriptionTier": "premium",
      "accountCredits": 1000
    }
  }'

Response (200)

{
  "success": true,
  "contact": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "emailAddresses": ["premium@example.com"],
    "phoneNumbers": [],
    "name": "Bob Smith",
    "firstName": "Bob",
    "lastName": "Smith",
    "externalId": null,
    "avatar": "https://gravatar.com/avatar/...",
    "username": null,
    "slackId": null,
    "meta": {
      "subscriptionTier": "premium",
      "accountCredits": 1000
    }
  }
}

---

GET /v1/contacts/

Fetch a contact by any identifier.

Examples

Get by email:

curl -X GET "https://api.sendivent.com/v1/contacts/user%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get by phone:

curl -X GET "https://api.sendivent.com/v1/contacts/%2B46701234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get by external_id:

curl -X GET "https://api.sendivent.com/v1/contacts/user_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get by UUID:

curl -X GET "https://api.sendivent.com/v1/contacts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

PATCH /v1/contacts/

Update an existing contact. Fails if the contact does not exist.

Only provided fields are updated.

Example

curl -X PATCH "https://api.sendivent.com/v1/contacts/user%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson-Smith",
    "meta": { "accountCredits": 500 }
  }'

---

DELETE /v1/contacts/

Permanently delete a contact and associated data (GDPR).

Example

curl -X DELETE "https://api.sendivent.com/v1/contacts/user%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200)

{
  "success": true,
  "deleted": true
}

---

Errors

See Errors for status codes and error response format.

See also

• Contacts — identifiers, to formats, and metadata
• Notifications API — sending to contacts
• Templates — using contact.* and contact.meta.*