Read a batch of users by internal ID, or unique property values

Lire un lot d'utilisateurs par ID interne ou par valeurs de propriétés uniques

curl --request POST \
  --url https://api.hubapi.com/crm/objects/2026-09/users/batch/read \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": [
    {
      "id": "430001"
    }
  ],
  "properties": [
    "<string>"
  ],
  "propertiesWithHistory": [
    "<string>"
  ],
  "idProperty": "<string>"
}
'

import requests

url = "https://api.hubapi.com/crm/objects/2026-09/users/batch/read"

payload = {
    "inputs": [{ "id": "430001" }],
    "properties": ["<string>"],
    "propertiesWithHistory": ["<string>"],
    "idProperty": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: [{id: '430001'}],
    properties: ['<string>'],
    propertiesWithHistory: ['<string>'],
    idProperty: '<string>'
  })
};

fetch('https://api.hubapi.com/crm/objects/2026-09/users/batch/read', 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.hubapi.com/crm/objects/2026-09/users/batch/read",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'inputs' => [
        [
                'id' => '430001'
        ]
    ],
    'properties' => [
        '<string>'
    ],
    'propertiesWithHistory' => [
        '<string>'
    ],
    'idProperty' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.hubapi.com/crm/objects/2026-09/users/batch/read"

	payload := strings.NewReader("{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hubapi.com/crm/objects/2026-09/users/batch/read")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hubapi.com/crm/objects/2026-09/users/batch/read")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}"

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

{
  "completedAt": "2023-11-07T05:31:56Z",
  "results": [
    {
      "archived": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "properties": {},
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "objectWriteTraceId": "<string>",
      "propertiesWithHistory": {},
      "url": "<string>",
      "warnings": [
        {
          "category": "<string>",
          "context": {},
          "message": "<string>"
        }
      ]
    }
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "status": "CANCELED",
  "links": {},
  "requestedAt": "2023-11-07T05:31:56Z"
}

{
  "completedAt": "2023-11-07T05:31:56Z",
  "results": [
    {
      "archived": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "properties": {},
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "objectWriteTraceId": "<string>",
      "propertiesWithHistory": {},
      "url": "<string>",
      "warnings": [
        {
          "category": "<string>",
          "context": {},
          "message": "<string>"
        }
      ]
    }
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "status": "CANCELED",
  "errors": [
    {
      "category": "<string>",
      "context": {},
      "errors": [
        {
          "message": "<string>",
          "code": "<string>",
          "context": "{missingScopes=[scope1, scope2]}",
          "in": "<string>",
          "subCategory": "<string>"
        }
      ],
      "links": {},
      "message": "<string>",
      "status": "<string>",
      "id": "<string>",
      "subCategory": {}
    }
  ],
  "links": {},
  "numErrors": 123,
  "requestedAt": "2023-11-07T05:31:56Z"
}

{
  "message": "Invalid input (details will vary based on the error)",
  "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
  "category": "VALIDATION_ERROR",
  "links": {
    "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
  }
}

POST

crm

objects

2026-09

users

batch

read

Lire un lot d'utilisateurs par ID interne ou par valeurs de propriétés uniques

curl --request POST \
  --url https://api.hubapi.com/crm/objects/2026-09/users/batch/read \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": [
    {
      "id": "430001"
    }
  ],
  "properties": [
    "<string>"
  ],
  "propertiesWithHistory": [
    "<string>"
  ],
  "idProperty": "<string>"
}
'

import requests

url = "https://api.hubapi.com/crm/objects/2026-09/users/batch/read"

payload = {
    "inputs": [{ "id": "430001" }],
    "properties": ["<string>"],
    "propertiesWithHistory": ["<string>"],
    "idProperty": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: [{id: '430001'}],
    properties: ['<string>'],
    propertiesWithHistory: ['<string>'],
    idProperty: '<string>'
  })
};

fetch('https://api.hubapi.com/crm/objects/2026-09/users/batch/read', 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.hubapi.com/crm/objects/2026-09/users/batch/read",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'inputs' => [
        [
                'id' => '430001'
        ]
    ],
    'properties' => [
        '<string>'
    ],
    'propertiesWithHistory' => [
        '<string>'
    ],
    'idProperty' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.hubapi.com/crm/objects/2026-09/users/batch/read"

	payload := strings.NewReader("{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hubapi.com/crm/objects/2026-09/users/batch/read")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hubapi.com/crm/objects/2026-09/users/batch/read")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": [\n    {\n      \"id\": \"430001\"\n    }\n  ],\n  \"properties\": [\n    \"<string>\"\n  ],\n  \"propertiesWithHistory\": [\n    \"<string>\"\n  ],\n  \"idProperty\": \"<string>\"\n}"

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

{
  "completedAt": "2023-11-07T05:31:56Z",
  "results": [
    {
      "archived": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "properties": {},
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "objectWriteTraceId": "<string>",
      "propertiesWithHistory": {},
      "url": "<string>",
      "warnings": [
        {
          "category": "<string>",
          "context": {},
          "message": "<string>"
        }
      ]
    }
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "status": "CANCELED",
  "links": {},
  "requestedAt": "2023-11-07T05:31:56Z"
}

{
  "completedAt": "2023-11-07T05:31:56Z",
  "results": [
    {
      "archived": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "properties": {},
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "objectWriteTraceId": "<string>",
      "propertiesWithHistory": {},
      "url": "<string>",
      "warnings": [
        {
          "category": "<string>",
          "context": {},
          "message": "<string>"
        }
      ]
    }
  ],
  "startedAt": "2023-11-07T05:31:56Z",
  "status": "CANCELED",
  "errors": [
    {
      "category": "<string>",
      "context": {},
      "errors": [
        {
          "message": "<string>",
          "code": "<string>",
          "context": "{missingScopes=[scope1, scope2]}",
          "in": "<string>",
          "subCategory": "<string>"
        }
      ],
      "links": {},
      "message": "<string>",
      "status": "<string>",
      "id": "<string>",
      "subCategory": {}
    }
  ],
  "links": {},
  "numErrors": 123,
  "requestedAt": "2023-11-07T05:31:56Z"
}

{
  "message": "Invalid input (details will vary based on the error)",
  "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
  "category": "VALIDATION_ERROR",
  "links": {
    "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
  }
}

Supported products

Required Scopes

Autorisations

Authorization

string

header

requis

The access token received from the authorization server in the OAuth 2.0 flow.

Paramètres de requête

archived

boolean

défaut:false

S'il faut renvoyer uniquement les résultats qui ont été archivés.

Corps

application/json

Spécifie l'entrée pour la lecture d'un lot d'objets CRM, y compris des tableaux d'ID d'objets, les noms de propriétés demandés (avec historique facultatif) et une propriété d'identification unique facultative.

inputs

object[]

requis

Un tableau d'objets SimplePublicObjectId, chacun représentant un objet à lire.

Show child attributes

properties

string[]

requis

Un tableau de chaînes de caractères spécifiant les propriétés à renvoyer dans la réponse. Si les propriétés spécifiées ne sont pas présentes sur les objets demandés, elles seront ignorées.

propertiesWithHistory

string[]

requis

Un tableau de chaînes de caractères spécifiant les propriétés à renvoyer avec l'historique de leurs valeurs précédentes. Si les propriétés spécifiées ne sont pas présentes sur les objets demandés, elles seront ignorées.

idProperty

string

Lors de l'utilisation d'une propriété à valeur unique personnalisée, pour récupérer les fiches d'informations, le nom de la propriété. Ne pas inclure ce paramètre si l'extraction se fait par l'ID de la fiche d'informations.

Réponse

successful operation

Objet de réponse de lot d'objet public

completedAt

string<date-time>

requis

La date et l'heure auxquelles l'opération de lot a été effectuée, au format ISO 8601.

results

object[]

requis

Un tableau d'éléments SimplePublicObject, représentant les résultats de l'opération par lot.

Show child attributes

startedAt

string<date-time>

requis

La date et l'heure de début de l'opération par lot, au format ISO 8601.

status

enum<string>

requis

Le statut actuel de l'opération par lot. Les valeurs valides incluent « PENDING », « PROCESSING », « CANCELED » et « COMPLETE ».

Options disponibles:

CANCELED,

COMPLETE,

PENDING,

PROCESSING

links

object

Une carte des noms de liens vers les URI associées, fournissant des informations ou des actions supplémentaires liées à l'opération de lot.

Show child attributes

requestedAt

string<date-time>

La date et l'heure auxquelles l'opération de lot a été demandée, au format ISO 8601.

Dernière modification le 6 octobre 2026

Compte et paramètres

Gestion des applications

Authentification

Automatisation

CMS

Préférences de communication

Conversations

CRM

Data Studio

Événements

Fichiers

Marketing

Rendez-vous

Chiffre d'affaires

Webhooks

Journal des webhooks

Read a batch of users by internal ID, or unique property values

Autorisations

Paramètres de requête

Corps

Réponse