Users — API Reference

GET /users List users

Returns a paginated list of all users on your account. Filter by `reference_id` to look up a specific user.

Parameter	In	Type	Required	Description
`reference_id`	query	`string`	optional	Filter by your internal user ID
`page`	query	`integer`	optional	Page number (default: 1)
`per_page`	query	`integer`	optional	Results per page (default: 20, max: 100)

Example Request

bash

curl -X GET \
  "https://api.sonarhealth.co/v1/users" \
  -H "Authorization: Bearer $TOKEN"

Response 200 Paginated user list

json

{
  "data": [
    {
      "id": "usr_abc123",
      "reference_id": "your-internal-id",
      "timezone": "America/New_York",
      "status": "active",
      "score_status": "ready",
      "last_sync_at": "2025-01-20T08:30:00Z",
      "last_score_at": "2025-01-20T08:31:00Z",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 84
  }
}

POST /users Create a user

Creates a new Sonar user linked to your account. Use `reference_id` to map to your own identity system.

Example Request

bash

curl -X POST \
  "https://api.sonarhealth.co/v1/users" \
  -H "Authorization: Bearer $TOKEN"

GET /users/{user_id} Get a user

Returns a user's profile, sync status, and score status.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID (e.g., `usr_abc123`)

Example Request

bash

curl -X GET \
  "https://api.sonarhealth.co/v1/users/:user_id" \
  -H "Authorization: Bearer $TOKEN"

Response 200 User profile

json

{
  "data": {
    "id": "usr_abc123",
    "reference_id": "your-internal-id",
    "timezone": "America/New_York",
    "status": "active",
    "score_status": "ready",
    "last_sync_at": "2025-01-20T08:30:00Z",
    "last_score_at": "2025-01-20T08:31:00Z",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Error Responses

404 User not found

json

{
  "error": "not_found",
  "message": "User 'usr_invalid' not found.",
  "details": {}
}

PATCH /users/{user_id} Update a user

Updates mutable fields for a user.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID

Example Request

bash

curl -X PATCH \
  "https://api.sonarhealth.co/v1/users/:user_id" \
  -H "Authorization: Bearer $TOKEN"

Response 200 Updated user profile

json

{
  "data": {
    "id": "usr_abc123",
    "reference_id": "your-internal-id",
    "timezone": "Europe/London",
    "status": "active",
    "score_status": "ready",
    "last_sync_at": "2025-01-20T08:30:00Z",
    "last_score_at": "2025-01-20T08:31:00Z",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

DELETE /users/{user_id} Delete a user

Permanently deletes a user, disconnects all devices, de-authorizes with providers, and removes all associated data. This action is irreversible.

Parameter	In	Type	Required	Description
`user_id`	path	`string`	required	Sonar user ID

Example Request

bash

curl -X DELETE \
  "https://api.sonarhealth.co/v1/users/:user_id" \
  -H "Authorization: Bearer $TOKEN"