Skip to main content
GET
/
v1
/
organizations
/
{organization_id}
/
users
cURL
curl --request GET \
  --url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users \
  --header 'Authorization: Bearer <token>' \
  --header 'x-organization-secret: <x-organization-secret>'
{
  "success": true,
  "statusCode": 200,
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "user_id": "usr_abc123def456",
        "external_user_id": "PARTNER#USER_12345",
        "full_name": "John Doe",
        "access_roles": [
          "provider",
          "admin"
        ]
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "lastKey": null
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

​
Response Examples

​
Success Response (200 OK)

{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 3 users successfully",
  "data": [
    {
      "user_id": "usr_abc123def456",
      "email": "darlene.cameron@example.com"
    },
    {
      "user_id": "usr_def456ghi789",
      "email": "john.smith@example.com"
    },
    {
      "user_id": "usr_ghi789jkl012",
      "email": "sarah.jones@example.com"
    }
  ],
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_abc123"
}

​
Empty Organization (200 OK)

{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 0 users successfully",
  "data": [],
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_def456"
}

​
Invalid Parameters (400 Bad Request)

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/bad-request",
    "title": "Bad Request",
    "detail": "Organization ID is required"
  },
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_ghi789"
}

​
Unauthorized (401)

{
  "success": false,
  "statusCode": 401,
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Valid authentication token is required"
  },
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_jkl012"
}

​
Insufficient Permissions (403 Forbidden)

{
  "success": false,
  "statusCode": 401,
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Insufficient scope"
  },
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_mno345"
}

​
Response Fields

​
Success Response Data

The response returns an array of user objects, where each user contains:
FieldTypeDescription
user_idstringParchment’s unique user identifier
emailstringUser’s email address
Note: This endpoint only returns basic user identification fields (user_id and email) for security and performance reasons. Use the read-user endpoint to get detailed information about a specific user.

​
Common Response Fields

All responses include these standard fields:
FieldTypeDescription
successbooleanIndicates if the request was successful
statusCodenumberHTTP status code
messagestringHuman-readable status message
timestampstringISO 8601 timestamp of the response
requestIdstringUnique identifier for debugging

​
Path Parameters

ParameterTypeRequiredDescription
organization_idstringYesOrganization identifier

​
Status Codes

CodeStatusDescription
200OKUsers retrieved successfully (including empty list)
400Bad RequestInvalid request format or missing parameters
401UnauthorizedAuthentication required or token invalid or scope invalid
500Internal Server ErrorUnexpected server error

​
Error Handling

​
Integration Notes

  1. Store Request ID: Always log the requestId for debugging support requests
  2. Handle Empty Results: The API returns an empty array if no users are found
  3. Permission Requirements: Ensure your API token has the READ_USER scope
  4. Organization Access: You can only read users from organizations you have access to
  5. Limited Data: Only user_id and email are returned for security and performance reasons
  6. Detailed Information: Use the read-user endpoint (GET /users/{user_id}) to get full user details
  7. Pagination: This endpoint returns all users in the organization (no pagination currently)
  8. Caching: Consider caching user lists with appropriate TTL to reduce API calls

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-organization-secret
string
required

Organization secret for authentication - provided by Parchment

Path Parameters

​
organization_id
string<uuid>
required

Organization ID

Query Parameters

​
limit
integer
default:20

Maximum number of users to return (1-100)

Required range: 1 <= x <= 100
​
lastKey
string

Pagination key for retrieving the next set of results

Response

Users retrieved successfully