Contacts API

Create, update, fetch, and delete contacts.

Endpoints

• GET /v1/contacts — list with pagination
• 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)

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.

---

GET /v1/contacts

List contacts with pagination and optional search.

Query parameters

Parameter	Type	Default	Description
limit	integer	50	Results per page (max 100)
offset	integer	0	Number of results to skip
search	string	—	Search across name, email, phone, external_id

Response (200)

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": 1,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Jane Doe",
        "email": "jane@example.com",
        "phone": "+46701234567",
        "meta": { "plan": "premium" }
      }
    ],
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}

Example

curl "https://api.sendivent.com/v1/contacts?limit=20&search=jane" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

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	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,
    "slack": 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.*