Datenobjekt-Endpunkte
Verwenden Sie diese Endpunkte, um Datenobjekttypen aufzulisten, Datenobjektdatensätze zu verwalten und Objekt- sowie Nutzer:innenbeziehungen zu verwalten.

Datenobjekte sind allgemein verfügbar, Ihr Workspace muss jedoch für Accounts freigeschaltet sein, bevor Sie diese Endpunkte verwenden können. Um die Freischaltung anzufordern, gehen Sie zu Dateneinstellungen > Accounts und füllen Sie den Fragebogen aus. Nach Abschluss der Freischaltung werden die API-Schlüssel-Berechtigungen für Datenobjekte unter Einstellungen > API-Schlüssel angezeigt. Weitere Informationen finden Sie unter Accounts aktivieren.
Typ-Endpunkte
Objekt-Endpunkte
Objektbeziehungs-Endpunkte
Nutzer:innenbeziehungs-Endpunkte
Basis-URL und Authentifizierung
Verwenden Sie den REST-Endpunkt Ihres Workspace und senden Sie Authorization: Bearer YOUR_REST_API_KEY. In diesem Abschnitt erfahren Sie, wo die Endpunkte für Datenobjekte gehostet werden und wie Anfragen authentifiziert werden.
- Informationen zu den Endpunkt-Hosts finden Sie in der Braze API-Übersicht.
- Alle Anfrage- und Antwort-Payloads sind im JSON-Format.
- Anfragen gelten nur für den Workspace, dem der API-Schlüssel gehört.
- Wenn für den Schlüssel eine IP-Allowlist eingerichtet ist, geben Anfragen von nicht freigegebenen IP-Adressen
403zurück.
API-Schlüssel-Berechtigungen
In diesem Abschnitt wird jedem Endpunkt die erforderliche Berechtigung zugeordnet, damit Sie den Geltungsbereich von API-Schlüsseln sicher festlegen können.
| Berechtigung | Endpunktgruppe |
|---|---|
data_objects.read |
Lesen von Typen und Objekten sowie Lesen von Objektbeziehungen |
data_objects.create |
Objekt erstellen |
data_objects.update |
Objekt ersetzen und aktualisieren |
data_objects.delete |
Objekt löschen |
data_objects.user_relationships.read |
Lesen von Nutzerbeziehungen |
data_objects.user_relationships.create |
Nutzerbeziehung erstellen |
data_objects.user_relationships.update |
Nutzerbeziehung ersetzen und aktualisieren |
data_objects.user_relationships.delete |
Nutzerbeziehung löschen |
data_objects.object_relationships.create |
Objektbeziehung erstellen |
data_objects.object_relationships.update |
Objektbeziehung ersetzen und aktualisieren |
data_objects.object_relationships.delete |
Objektbeziehung löschen |
data_objects.bulk_upsert |
Objekte stapelweise erstellen oder ersetzen |
data_objects.bulk_delete |
Objekte stapelweise löschen |
data_objects.object_relationships.bulk_upsert |
Objektbeziehungen stapelweise erstellen oder ersetzen |
data_objects.object_relationships.bulk_delete |
Objektbeziehungen stapelweise löschen |
data_objects.user_relationships.bulk_upsert |
Nutzerbeziehungen stapelweise erstellen oder ersetzen |
data_objects.user_relationships.bulk_delete |
Nutzerbeziehungen stapelweise löschen |

Für das Lesen von Objektbeziehungen wird data_objects.read verwendet. Eine Berechtigung data_objects.object_relationships.read gibt es nicht.
Die Bulk-Endpunkte verwenden eigene Berechtigungen, wobei Upsert und Löschen separate Berechtigungen sind. Die Berechtigungen für einzelne Datensätze, wie data_objects.create, gewähren keinen Zugriff auf die Bulk-Endpunkte.
Rate-Limits
In diesem Abschnitt werden die Standardkontingente für Anfragen und die Antwort-Header für Lese- und Schreibzugriffe erläutert.
| Bucket | Standardlimit |
|---|---|
| Lesezugriffe auf Datenobjekte | 1.000 Anfragen pro Minute |
| Schreibzugriffe auf Datenobjekte | 1.000 Anfragen pro Minute |
| Bulk-Schreibzugriffe auf Datenobjekte | 1.000 Anfragen pro Minute, gemeinsam genutzt von den sechs Bulk-Endpunkten und den Synchronisierungen von Datenobjekten über Cloud Data Ingestion |
Das Limit für Bulk-Schreibzugriffe gilt pro Workspace und ist unabhängig vom Schreiblimit für einzelne Datensätze.
Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.
Bei gedrosselten Anfragen gibt Braze 429 und einen Fehler-Payload mit id und message zurück.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
Produktlimits
In diesem Abschnitt finden Sie die Limits, die Braze für Datenobjekte durchsetzt, und was Sie erwartet, wenn Sie ein Limit erreichen. Wie diese Limits für Account-Datensätze gelten, erfahren Sie unter Limits für Account-Objekte.
Mengenlimits
Sofern nicht anders angegeben, gelten diese Limits für Ihr gesamtes Unternehmen. Es handelt sich um Anfangskapazitäten. Wenn Sie mehr Datensätze oder ein höheres Limit benötigen, wenden Sie sich an Ihr Braze-Account-Team, um eine Erhöhung anzufordern.
| Limit | Standardwert |
|---|---|
| Datenobjekt-Datensätze pro Unternehmen (über alle Workspaces hinweg) | 50.000 |
| Felder pro Datenobjekttyp | 500 |
| Mit einem:einer Nutzer:in verknüpfte Datenobjekte | 1.000 |
| Mit einem Datenobjekt verknüpfte Nutzer:innen | 10.000 |
| Objektbeziehungen für ein Datenobjekt | 1.000 |
Feld- und Wertlimits
Diese Limits sind für alle Unternehmen fest vorgegeben.
| Limit | Wert |
|---|---|
| Felder pro Beziehungstyp (Nutzerbeziehungen und Objektbeziehungen) | 25. Beziehungsfelder werden nicht auf das Limit für Felder pro Datenobjekttyp angerechnet. |
| Länge von Attributwerten | 255 Zeichen |
| Datumsfelder | RFC 3339-Datums-/Zeit-Strings mit Uhrzeit und Zeitzone, zum Beispiel 2026-11-03T00:00:00Z. Braze lehnt reine Datumswerte wie 2026-11-03 ab. Weitere Informationen finden Sie unter Datumsfeldformat. |
Länge und Format von object_id |
250 Zeichen. Nur Buchstaben, Zahlen, Bindestriche und Unterstriche. |
| Länge und Format von Feldnamen | 250 Zeichen. Nur Buchstaben, Zahlen und Unterstriche; darf nicht mit einem Unterstrich beginnen. |
| Reservierte Feldnamen | id, external_id, object_id und display_name können nicht als angepasste Feldnamen verwendet werden. |
Datumsfeldformat
Datumsfelder akzeptieren nur RFC 3339-Datums-/Zeit-Strings, die sowohl eine Uhrzeit als auch eine Zeitzone enthalten. Braze benötigt den vollständigen Wert, damit nie eine Uhrzeit oder Zeitzone geraten werden muss. Wenn Ihre Quelle reine Datumswerte speichert, etwa Verlängerungs- oder Vertragsdaten in Ihrem Data Warehouse, konvertieren Sie diese vor dem Senden, zum Beispiel in Ihrer Warehouse-Transformation.
| Wert | Ergebnis |
|---|---|
2026-11-03T00:00:00Z |
Akzeptiert |
2026-11-03T00:00:00-05:00 |
Akzeptiert |
2026-11-03 |
Abgelehnt, da Uhrzeit und Zeitzone fehlen |
2026-11-03T00:00:00 |
Abgelehnt, da die Zeitzone fehlt |
Dieses Format gilt für Datumsfelder in Datenobjekten, Nutzerbeziehungen und Objektbeziehungen. Wie Braze einen abgelehnten Wert meldet, hängt davon ab, wie Sie ihn senden:
- Die Endpunkte zum Erstellen, Ersetzen und Aktualisieren einzelner Datensätze geben
400zurück. Sind mehrere Attribute ungültig, nennt der Fehler nur das erste. - Die Bulk-Upsert-Endpunkte nehmen die Anfrage mit
202an und erfassen dann für den Datensatz einen Verarbeitungsfehlerdata-object-schema-mismatch, zum Beispielattributes: renewal_date is not valid for its field. - Cloud Data Ingestion-Synchronisierungen verwenden dieselbe Verarbeitung wie die Bulk-Endpunkte. Braze übernimmt daher keine Zeile mit einem reinen Datumswert, und der Fehler erscheint in den Synchronisierungsprotokollen.
Eine Anfrage für einen einzelnen Datensatz, die zum Beispiel 2026-11-03 für ein Datumsfeld renewal_date sendet, gibt diese 400-Antwort zurück:
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
Was passiert, wenn Sie ein Limit erreichen
Eine Anfrage, die ein Mengenlimit überschreiten würde, gibt 422 mit einer Fehler-id zurück, die das Limit identifiziert:
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| Limit | Fehler-id |
|---|---|
| Datenobjekt-Datensätze pro Unternehmen | data-object-record-limit-exceeded |
| Felder pro Datenobjekttyp | data-object-field-limit-exceeded |
| Felder pro Beziehungstyp | data-object-field-limit-exceeded |
| Mit einem:einer Nutzer:in verknüpfte Datenobjekte | data-objects-per-user-limit-exceeded |
| Mit einem Datenobjekt verknüpfte Nutzer:innen | users-per-data-object-limit-exceeded |
| Objektbeziehungen für ein Datenobjekt | data-object-relationship-limit-exceeded |
Ihre vorhandenen Datensätze und Beziehungen bleiben bestehen – nur die Anfrage, die das Limit überschreiten würde, wird abgelehnt. Um unter einem Limit wieder Platz zu schaffen, löschen Sie nicht mehr benötigte Datensätze oder entfernen Sie nicht mehr verwendete Beziehungen. Um ein Mengenlimit zu erhöhen, wenden Sie sich an Ihr Braze-Account-Team.
Anfragen, die die Validierung nicht bestehen, etwa weil eine object_id oder ein Attributwert zu lang ist, geben 400 zurück. Anfragen, die das Rate-Limit überschreiten, geben 429 zurück.
Kernkonzepte
In diesem Abschnitt werden die wichtigsten Bezeichner definiert, die in allen Endpunkten für Datenobjekte verwendet werden.
type_name: Der Maschinenname des Datenobjekttyps, eindeutig innerhalb eines Workspace.object_id: Ihr Objekt-Bezeichner, eindeutig innerhalb eines Typs.user: Die Nutzer:in in einer Schreibanfrage für eine Nutzerbeziehung, identifiziert durch genau einen der Werteexternal_id,braze_id,alias,emailoderphone.attributes: Objekt- oder Beziehungsdaten mit Feldnamen als Schlüsseln, die anhand des konfigurierten Schemas validiert werden.
So funktionieren Beziehungen
In diesem Abschnitt lernen Sie Beziehungstypen, Beziehungskanten und das Verhalten von anchor kennen, bevor Sie die Referenzseiten der Endpunkte verwenden.
Beziehungsmodell im Überblick
Das folgende Diagramm zeigt, wie Typen, Datensätze und Beziehungen zusammenhängen und was Sie in Braze damit erreichen, wenn Sie sie miteinander verknüpfen. Die Typen definieren Sie im Dashboard. Die Datensätze und die Verknüpfungen zwischen ihnen schreiben Sie anschließend über diese Endpunkte.
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
Typen und Kanten sind getrennt
- Beziehungstypen legen fest, welche Verknüpfungen gültig sind, und werden im Dashboard verwaltet.
- Beziehungskanten sind die tatsächlichen Verknüpfungen zwischen Datensätzen. Sie werden über diese API-Endpunkte erstellt, aktualisiert und gelöscht.
- Bevor Sie Beziehungen schreiben, rufen Sie die gültigen
rel_kind-Werte mit folgenden Endpunkten ab:GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
Warum Objektbeziehungen related_type_name erfordern
rel_kindist nicht über alle Paare von Objekttypen hinweg eindeutig. Beispielsweise kannrel_kindfür ein Paar von Objekttypensubaccountund für ein anderespartner_accountlauten.- Schreibvorgänge für Objektbeziehungen erfordern daher sowohl
rel_kindals auchrelated_type_name, um den gewünschten Beziehungstyp zusammen mit dem anderen Objekttyp in der Verknüpfung zu bestimmen. - Wenn
related_type_namenicht zum Beziehungstyp für diesesrel_kindpasst, gibt die Anfrage400zurück.
anchor steuert die Richtung der Beziehung
Objektbeziehungen sind gerichtet. Das Objekt in der URL wird abhängig von anchor interpretiert.
anchor |
Rolle des URL-Objekts | Schlüssel des verknüpften Objekts in Antworten |
|---|---|---|
source (Standard) |
Ausgangsseite (ausgehende Kante) | to_data_object |
target |
Zielseite (eingehende Kante) | from_data_object |
Wenn Sie dieselbe Kante aus der entgegengesetzten anchor-Perspektive erstellen, betrifft dies dennoch nur eine zugrunde liegende Beziehung. Ein zweiter Erstellungsaufruf für dieselbe Kante gibt 409 (duplicate-object-relationship) zurück.
Unterschiedliche Pfade für Nutzerbeziehungen
Lese- und Schreibvorgänge für Nutzerbeziehungen verwenden bewusst unterschiedliche Endpunktpfade:
- Lesen:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - Schreiben:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
Beziehungsattribute sind von Objektattributen getrennt
- Beziehungsendpunkte geben Attribute auf Kantenebene im übergeordneten Feld
attributeszurück. - Objektattribute bleiben unter
to_data_objectoderfrom_data_objectverschachtelt. PUTersetzt dieattributesder Beziehung,PATCHführt dieattributesder Beziehung zusammen.
Praxisbeispiel
Dieses Beispiel zeigt einen typischen Account-Workflow:
- Erstellen Sie
account/acct-123. - Erstellen Sie
account/acct-456als untergeordneten Account. - Verknüpfen Sie eine:n Nutzer:in mit
acct-123überrel_kind: account_user. - Verknüpfen Sie
acct-123mitacct-456überrel_kind: subaccount.
So lesen Sie die Verknüpfungen wieder aus:
GET /data_objects/objects/account/acct-123/user_relationshipsfür verknüpfte Nutzer:innenGET /data_objects/objects/account/acct-123/object_relationshipsfür ausgehende ObjektverknüpfungenGET /data_objects/objects/account/acct-456/object_relationships?anchor=targetfür eingehende Objektverknüpfungen

Die DELETE-Endpunkte für Objektbeziehungen und Nutzerbeziehungen erfordern einen JSON-Anfragetext.
Bulk-Endpunkte
Verwenden Sie die Bulk-Endpunkte, um Datenobjekte, Objektbeziehungen und Nutzerbeziehungen stapelweise aus Ihren eigenen Systemen zu synchronisieren. Jede Anfrage erstellt, ersetzt oder löscht bis zu 50 Datensätze, und Braze verarbeitet den Batch im Hintergrund.
| Methode | Endpunkt | Zweck |
|---|---|---|
PUT |
/data_objects/objects |
Bis zu 50 Datenobjekte beliebiger Typen erstellen oder ersetzen |
DELETE |
/data_objects/objects |
Bis zu 50 Datenobjekte beliebiger Typen löschen |
PUT |
/data_objects/object_relationships |
Bis zu 50 Objekt-zu-Objekt-Beziehungen erstellen oder ersetzen |
DELETE |
/data_objects/object_relationships |
Bis zu 50 Objekt-zu-Objekt-Beziehungen löschen |
PUT |
/data_objects/user_relationships |
Bis zu 50 Nutzer-zu-Objekt-Beziehungen erstellen oder ersetzen |
DELETE |
/data_objects/user_relationships |
Bis zu 50 Nutzer-zu-Objekt-Beziehungen löschen |
Wann Sie die Bulk-Endpunkte verwenden sollten
Verwenden Sie die Bulk-Endpunkte, wenn Sie viele Datensätze aus Ihren eigenen Systemen synchronisieren und nicht jede Änderung angewendet sein muss, bevor die Antwort zurückkommt. Verwenden Sie die Einzeldatensatz-Endpunkte, wenn die Änderung sofort sichtbar sein soll, wenn Sie Datensätze lesen müssen oder wenn Sie mit PATCH nur einige Attribute eines Datensatzes aktualisieren möchten.
Die Bulk-Endpunkte unterscheiden sich von den Einzeldatensatz-Endpunkten in folgenden Punkten:
- Die Verarbeitung erfolgt asynchron. Eine
202-Antwort bedeutet, dass Braze den Batch angenommen und in die Warteschlange gestellt hat, nicht dass die Datensätze bereits angewendet wurden. Erst bei der Verarbeitung des Batches prüft Braze, ob Typen, Beziehungstypen, Objekte und Nutzer:innen existieren und ob die Attribute den Feldern des Typs entsprechen. Eine Anfrage, die202zurückgibt, kann daher später noch Fehler für einzelne Datensätze verursachen. - Die Validierung erfolgt nach dem Alles-oder-nichts-Prinzip. Wenn ein Datensatz in einer Anfrage die Validierung nicht besteht, lehnt Braze die gesamte Anfrage mit
400ab, speichert nichts und listet alle Fehler auf. - Datensätze werden nach Eingangszeit sortiert. Braze versieht jeden Datensatz mit dem Zeitpunkt, zu dem die Anfrage eingegangen ist. Senden Sie daher kein
updated_at. Wenn zwei Anfragen denselben Datensatz ändern, setzt sich die Anfrage durch, die Braze später erhalten hat. - Datensätze können auf Abhängigkeiten warten. Das Löschen eines Objekts oder einer Beziehung, die noch nicht existiert, sowie eine Beziehung, deren Objekt oder Nutzer:in noch nicht existiert, wartet, statt sofort fehlzuschlagen. Braze wiederholt den Vorgang etwa 40 Stunden lang (10 Versuche). Ein Objekt-Upsert wartet nie.
- Die Bulk-Endpunkte verwenden eigene API-Schlüssel-Berechtigungen und teilen sich ein Rate-Limit von 1.000 Anfragen pro Minute und Workspace.
- Die Bulk-Endpunkte erstellen niemals Datenobjekttypen. Jeder
type_namemuss bereits existieren.
Die Produktlimits gelten für die Bulk-Endpunkte auf dieselbe Weise wie für die Einzeldatensatz-Endpunkte.
Paginierung und Datenaktualität
Dieser Abschnitt beschreibt, wie die Paginierung bei Listen funktioniert und wann geschriebene Daten voraussichtlich sichtbar sind.
- Listen-Endpunkte unterstützen
limitundoffset. limitist standardmäßig100und wird auf einen Wert zwischen1und250begrenzt.offsetist standardmäßig0. Negative Werte werden auf0angehoben.- Schreibvorgänge für einzelne Datensätze sind sofort für Lesevorgänge und die Liquid-Personalisierung sichtbar. Bulk-Schreibvorgänge werden angewendet, sobald Braze den Batch aus der Warteschlange verarbeitet.
- Die Segment-Mitgliedschaft auf Basis von Datenobjekten kann bis zu einer Stunde verzögert sein, da berechnete Filter stündlich aktualisiert werden.
Fehlerverhalten
Dieser Abschnitt fasst die Status- und Fehlerantwortmuster zusammen, die bei allen Endpunkten für Datenobjekte verwendet werden.
404,409,422und429geben einerrors-Array mitidundmessagezurück.400,401und403geben einen einzelnenerror-String zurück.- Die Bulk-Endpunkte geben
400- und500-Fehler alserrors-Array mitidundmessagezurück. Ein400-Fehler enthält zusätzlich den fehlerhaftenparameter, sofern vorhanden, und bei Fehlern auf Datensatzebene denindexdes Datensatzes. 422bedeutet, dass die Anfrage ein Produktlimit überschreiten würde. Die Standardwerte der Limits variieren je nach Vertrag Ihres Unternehmens.