Contacts API

Shared contact directory for SMS, Email and other services. Manage contacts and groups for batch operations.

Base URL: https://api.wayscloud.services

Endpoints

Method	Path	Description
GET	/v1/contacts	List contacts
POST	/v1/contacts	Create contact
GET	/v1/contacts/{contact_id}	Get contact
PATCH	/v1/contacts/{contact_id}	Update contact
DELETE	/v1/contacts/{contact_id}	Delete contact
POST	/v1/contacts/{contact_id}/gdpr-delete	GDPR anonymize contact
GET	/v1/contacts/groups	List contact groups
POST	/v1/contacts/groups	Create contact group
GET	/v1/contacts/groups/{group_id}	Get contact group
PATCH	/v1/contacts/groups/{group_id}	Update contact group
DELETE	/v1/contacts/groups/{group_id}	Delete contact group
GET	/v1/contacts/groups/{group_id}/members	List group members
POST	/v1/contacts/groups/{group_id}/members	Add members to group
DELETE	/v1/contacts/groups/{group_id}/members/{contact_id}	Remove member from group

GET /v1/contacts

List contacts

List all contacts with optional filtering by type, search query, or tags.

Response:

Field	Type	Description
contacts	array
total	integer
page	integer
per_page	integer

Example:

curl https://api.wayscloud.services/v1/contacts \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

{
  "contacts": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "first_name": "Ola",
      "last_name": "Nordmann",
      "email": "ola@example.com",
      "phone_number": "+4799999999",
      "contact_type": "person",
      "tags": [
        "vip"
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}

---

POST /v1/contacts

Create contact

Create a new contact. Phone numbers should be in E.164 format for SMS sending.

Request Body:

Field	Type	Description
type	string	Values: person, company
name	string	Required.
company_name	string
phone_number	string	E.164 format recommended
email	string
tags	array
notes	string

Example:

{
  "type": "person",
  "name": "Ola Nordmann",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip"
  ]
}

Response:

Field	Type	Description
id	string
type	string	Values: person, company
name	string
company_name	string
phone_number	string
email	string
tags	array
notes	string
created_at	string
updated_at	string

Example:

curl -X POST https://api.wayscloud.services/v1/contacts \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "person",
  "name": "Ola Nordmann",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip"
  ]
}'

Response:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "person",
  "name": "Ola Nordmann",
  "company_name": "ACME AS",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip",
    "newsletter"
  ],
  "notes": "Key contact for project X",
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

---

GET /v1/contacts/

Get contact

Get details of a specific contact.

Response:

Field	Type	Description
id	string
type	string	Values: person, company
name	string
company_name	string
phone_number	string
email	string
tags	array
notes	string
created_at	string
updated_at	string

Example:

curl https://api.wayscloud.services/v1/contacts/{contact_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "person",
  "name": "Ola Nordmann",
  "company_name": "ACME AS",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip",
    "newsletter"
  ],
  "notes": "Key contact for project X",
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

---

PATCH /v1/contacts/

Update contact

Update an existing contact. Only provided fields are updated.

Request Body:

Field	Type	Description
type	string	Values: person, company
name	string	Required.
company_name	string
phone_number	string	E.164 format recommended
email	string
tags	array
notes	string

Example:

{
  "type": "person",
  "name": "Ola Nordmann",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip"
  ]
}

Response:

Field	Type	Description
id	string
type	string	Values: person, company
name	string
company_name	string
phone_number	string
email	string
tags	array
notes	string
created_at	string
updated_at	string

Example:

curl -X PATCH https://api.wayscloud.services/v1/contacts/{contact_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "person",
  "name": "Ola Nordmann",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip"
  ]
}'

Response:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "person",
  "name": "Ola Nordmann",
  "company_name": "ACME AS",
  "phone_number": "+4799999999",
  "email": "ola@example.com",
  "tags": [
    "vip",
    "newsletter"
  ],
  "notes": "Key contact for project X",
  "created_at": "2025-01-15T09:30:00Z",
  "updated_at": "2025-01-15T09:30:00Z"
}

---

DELETE /v1/contacts/

Delete contact

Delete a contact. This is a soft delete - the contact can be restored via GDPR endpoints.

Example:

curl -X DELETE https://api.wayscloud.services/v1/contacts/{contact_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

---

POST /v1/contacts/{contact_id}/gdpr-delete

GDPR anonymize contact

Permanently anonymize contact data for GDPR compliance. This is irreversible.

Request Body:

Field	Type	Description
reason	string	Required. Reason for GDPR deletion

Example:

curl -X POST https://api.wayscloud.services/v1/contacts/{contact_id}/gdpr-delete \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer requested data deletion per GDPR Article 17"
}'

---

GET /v1/contacts/groups

List contact groups

List all contact groups with member counts.

Response:

Field	Type	Description
groups	array

Example:

curl https://api.wayscloud.services/v1/contacts/groups \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

{
  "groups": [
    {
      "id": "a1b2c3d4-1234-5678-9abc-def012345678",
      "name": "Newsletter Subscribers",
      "member_count": 150,
      "created_at": "2025-01-15T09:30:00Z"
    }
  ]
}

---

POST /v1/contacts/groups

Create contact group

Create a new contact group for organizing contacts.

Request Body:

Field	Type	Description
name	string	Required.
description	string

Example:

{
  "name": "VIP Customers",
  "description": "High-value customers for priority support"
}

Response:

Field	Type	Description
id	string
name	string
description	string
member_count	integer
created_at	string

Example:

curl -X POST https://api.wayscloud.services/v1/contacts/groups \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP Customers",
  "description": "High-value customers for priority support"
}'

Response:

{
  "id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "name": "Newsletter Subscribers",
  "description": "Customers who opted in for newsletter",
  "member_count": 150,
  "created_at": "2025-01-15T09:30:00Z"
}

---

GET /v1/contacts/groups/

Get contact group

Get details of a specific contact group including member list.

Response:

Field	Type	Description
id	string
name	string
description	string
member_count	integer
created_at	string

Example:

curl https://api.wayscloud.services/v1/contacts/groups/{group_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

{
  "id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "name": "Newsletter Subscribers",
  "description": "Customers who opted in for newsletter",
  "member_count": 150,
  "created_at": "2025-01-15T09:30:00Z"
}

---

PATCH /v1/contacts/groups/

Update contact group

Update group name or description.

Request Body:

Field	Type	Description
name	string	Required.
description	string

Example:

{
  "name": "VIP Customers",
  "description": "High-value customers for priority support"
}

Response:

Field	Type	Description
id	string
name	string
description	string
member_count	integer
created_at	string

Example:

curl -X PATCH https://api.wayscloud.services/v1/contacts/groups/{group_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP Customers",
  "description": "High-value customers for priority support"
}'

Response:

{
  "id": "a1b2c3d4-1234-5678-9abc-def012345678",
  "name": "Newsletter Subscribers",
  "description": "Customers who opted in for newsletter",
  "member_count": 150,
  "created_at": "2025-01-15T09:30:00Z"
}

---

DELETE /v1/contacts/groups/

Delete contact group

Delete a contact group. Contacts in the group are not deleted.

Example:

curl -X DELETE https://api.wayscloud.services/v1/contacts/groups/{group_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

---

GET /v1/contacts/groups/{group_id}/members

List group members

List all contacts in a group.

Response:

Field	Type	Description
members	array

Example:

curl https://api.wayscloud.services/v1/contacts/groups/{group_id}/members \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

{
  "members": [
    {
      "id": "b2c3d4e5-6789-0abc-def1-234567890abc",
      "first_name": "Ola",
      "last_name": "Nordmann",
      "phone_number": "+4799999999"
    }
  ]
}

---

POST /v1/contacts/groups/{group_id}/members

Add members to group

Add one or more contacts to a group.

Request Body:

Field	Type	Description
contact_ids	array	Required.

Response:

Field	Type	Description
added	integer

Example:

curl -X POST https://api.wayscloud.services/v1/contacts/groups/{group_id}/members \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_ids": [
    "a1b2c3d4-5678-9abc-def0-123456789abc",
    "b2c3d4e5-6789-0abc-def1-234567890abc"
  ]
}'

Response:

{
  "added": 3
}

---

DELETE /v1/contacts/groups/{group_id}/members/

Remove member from group

Remove a contact from a group.

Example:

curl -X DELETE https://api.wayscloud.services/v1/contacts/groups/{group_id}/members/{contact_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

---