Read users

GET

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>'

import requests

url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users"

headers = {
    "x-organization-secret": "<x-organization-secret>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-organization-secret': '<x-organization-secret>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-organization-secret: <x-organization-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-organization-secret", "<x-organization-secret>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users")
  .header("x-organization-secret", "<x-organization-secret>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 2 users successfully",
  "code": "SUCCESS",
  "data": [
    {
      "user_id": "0b4c1a49-fea8-4922-a3da-2ca8ff8af9bd",
      "email": "darlene.cameron@example.com"
    },
    {
      "user_id": "5b048ac0-b078-4955-88d5-1c4bc5147d3b",
      "email": "john.smith@example.com"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "1-68d1b225-2a98752c7b2da3fa489267fc"
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

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 Scope (401 Unauthorized)

{
  "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:

Field	Type	Description
`user_id`	string	Parchment’s unique user identifier
`email`	string	User’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.

There is no external_user_id, partner_user_id or any other partner-side identifier in this response, and no such field is stored by Parchment. data is a flat array of objects that hold exactly user_id and email. Map user_id to your own user record when you create the user.

The response is a flat array, not an object. There is no data.users wrapper and no pagination object. The endpoint takes no limit or lastKey query parameter — it returns every user in the organization.

Common Response Fields

All responses include these standard fields:

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`statusCode`	number	HTTP status code
`message`	string	Human-readable status message
`timestamp`	string	ISO 8601 timestamp of the response
`requestId`	string	Unique identifier for debugging

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	Organization identifier

Status Codes

Code	Status	Description
`200`	OK	Users retrieved successfully (including empty list)
`400`	Bad Request	Invalid request format or missing parameters
`401`	Unauthorized	Authentication required or token invalid or scope invalid
`500`	Internal Server Error	Unexpected server error

Error Handling

Integration Notes

Store Request ID: Always log the requestId for debugging support requests
Handle Empty Results: The API returns an empty array if no users are found
Permission Requirements: Ensure your API token has the READ_USER scope
Organization Access: You can only read users from organizations you have access to
Limited Data: Only user_id and email are returned for security and performance reasons. No partner-side identifier is returned.
Detailed Information: Use the read-user endpoint (GET /users/{user_id}) to get full user details
Pagination: This endpoint returns all users in the organization. There is no pagination, and limit / lastKey query parameters are ignored.
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

Response

Users retrieved successfully

The response is of type any.

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>'

import requests

url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users"

headers = {
    "x-organization-secret": "<x-organization-secret>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-organization-secret': '<x-organization-secret>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-organization-secret: <x-organization-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-organization-secret", "<x-organization-secret>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users")
  .header("x-organization-secret", "<x-organization-secret>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 2 users successfully",
  "code": "SUCCESS",
  "data": [
    {
      "user_id": "0b4c1a49-fea8-4922-a3da-2ca8ff8af9bd",
      "email": "darlene.cameron@example.com"
    },
    {
      "user_id": "5b048ac0-b078-4955-88d5-1c4bc5147d3b",
      "email": "john.smith@example.com"
    }
  ],
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "1-68d1b225-2a98752c7b2da3fa489267fc"
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

{
  "success": false,
  "statusCode": 400,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "instance": "/patients/123",
    "validation": [
      {
        "field": "<string>",
        "message": "<string>",
        "code": "<string>"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456",
  "code": "RESOURCE_NOT_FOUND",
  "meta": {
    "apiVersion": "1.0"
  }
}

API Documentation

Authentication

Authentication Endpoints

Patient Management Endpoints

User Management Endpoints

Custom Drug Endpoints

Response Examples

Success Response (200 OK)

Empty Organization (200 OK)

Invalid Parameters (400 Bad Request)

Unauthorized (401)

Insufficient Scope (401 Unauthorized)

Response Fields

Success Response Data

Common Response Fields

Path Parameters

Status Codes

Error Handling

Integration Notes

Authorizations

Headers

Path Parameters

Response

​Response Examples

​Success Response (200 OK)

​Empty Organization (200 OK)

​Invalid Parameters (400 Bad Request)

​Unauthorized (401)

​Insufficient Scope (401 Unauthorized)

​Response Fields

​Success Response Data

​Common Response Fields

​Path Parameters

​Status Codes

​Error Handling

​Integration Notes

Authorizations

Headers

Path Parameters

Response

Response Examples

Success Response (200 OK)

Empty Organization (200 OK)

Invalid Parameters (400 Bad Request)

Unauthorized (401)

Insufficient Scope (401 Unauthorized)

Response Fields

Success Response Data

Common Response Fields

Path Parameters

Status Codes

Error Handling

Integration Notes