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

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

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.

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
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 (no pagination currently)
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

Update userUpdates a user in Parchment

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

{
  "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 Permissions (403 Forbidden)

Response Fields

Success Response Data

Common Response Fields

Path Parameters

Status Codes

Error Handling

Integration Notes

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Response Examples

​Success Response (200 OK)

​Empty Organization (200 OK)

​Invalid Parameters (400 Bad Request)

​Unauthorized (401)

​Insufficient Permissions (403 Forbidden)

​Response Fields

​Success Response Data

​Common Response Fields

​Path Parameters

​Status Codes

​Error Handling

​Integration Notes

Authorizations

Headers

Path Parameters

Query Parameters

Response

Response Examples

Success Response (200 OK)

Empty Organization (200 OK)

Invalid Parameters (400 Bad Request)

Unauthorized (401)

Insufficient Permissions (403 Forbidden)

Response Fields

Success Response Data

Common Response Fields

Path Parameters

Status Codes

Error Handling

Integration Notes