Synupv1
Schlüssel erstellen
v1Ressourcen/Custom Fields

Custom Fields

Definieren und Verwalten des benutzerdefinierten Feldschemas für Standorte und Kunden in Ihrer Agentur, sowie Lesen oder Schreiben der für eine bestimmte Entität gespeicherten Werte. Das Feldschema selbst ist agenturweit; Werte je Entität bleiben weiterhin auf die Kunden beschränkt, für die ein eingeschränkter Schlüssel autorisiert ist.

Liefert das für den angegebenen Entitätstyp (location oder client) definierte benutzerdefinierte Feldschema, in der Reihenfolge, in der es in der Benutzeroberfläche angezeigt wird.

Benutzerdefinierte Feld-Definitionen auflisten

get/api/v1/custom-fields/definitions
custom-fields:read
Query-Parameter
entityTypestring (location | client)erforderlich
Für welchen Entitätstyp das Schema aufgelistet werden soll: "location" oder "client".
Antwort
dataarray of objectoptional
idstringoptional
Eindeutige Kennung der benutzerdefinierten Feld-Definition.
entityTypestring (location | client)optional
Der Entitätstyp, für den diese Definition gilt: "location" oder "client".
keystringoptional
Unveränderlicher Slug, der dieses Feld identifiziert, abgeleitet von seinem label bei der Erstellung. Verwenden Sie dies, um das Feld beim Setzen von Werten zu referenzieren.
labelstringoptional
Das Anzeigelabel des benutzerdefinierten Feldes.
typestring (text | number | date | single_select | multi_select)optional
Der Werttyp des Feldes.
requiredbooleanoptional
Ob das Feld als erforderlich markiert ist. Dies wird von der API nicht erzwungen — es ist nur ein Hinweis für die Benutzeroberfläche.
optionsarray of stringoptional
Die auswählbaren Optionen des Feldes, für Felder des Typs single_select und multi_select. Null für andere Typen.
createdBystringoptional
Wer diese Feld-Definition erstellt hat: "user" oder "agent".
ordernumberoptional
Die Anzeigereihenfolge des Feldes relativ zu anderen Definitionen desselben Entitätstyps, niedrigste zuerst.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
get/api/v1/custom-fields/definitions
Ihr API-Schlüssel
entityType *
{
  "data": [
    {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": false,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  ]
}
v1Ressourcen/Custom Fields/postBenutzerdefinierte Feld-Definition erstellen

Fügt dem Schema für den angegebenen Entitätstyp ein neues benutzerdefiniertes Feld hinzu. Der key des Feldes wird von seinem label abgeleitet und ist danach unveränderlich; Felder des Typs select benötigen mindestens eine Option.

Benutzerdefinierte Feld-Definition erstellen

post/api/v1/custom-fields/definitions
custom-fields:write
Anfragetext
entityTypestring (location | client)erforderlich
Der Entitätstyp, für den dieses Feld gilt: "location" oder "client".
labelstringerforderlich
Das Anzeigelabel des benutzerdefinierten Feldes.
typestring (text | number | date | single_select | multi_select)erforderlich
Der Werttyp des Feldes: text, number, date, single_select oder multi_select.
requiredbooleanoptional
Ob das Feld als erforderlich markiert werden soll. Optional; Standardmäßig false.
optionsarray of stringoptional
Die auswählbaren Optionen des Feldes. Erforderlich (mindestens eine) für Felder des Typs single_select und multi_select; wird für andere Typen ignoriert.
Antwort
dataobjectoptional
definitionobjectoptional
idstringoptional
Eindeutige Kennung der benutzerdefinierten Feld-Definition.
entityTypestring (location | client)optional
Der Entitätstyp, für den diese Definition gilt: "location" oder "client".
keystringoptional
Unveränderlicher Slug, der dieses Feld identifiziert, abgeleitet von seinem label bei der Erstellung. Verwenden Sie dies, um das Feld beim Setzen von Werten zu referenzieren.
labelstringoptional
Das Anzeigelabel des benutzerdefinierten Feldes.
typestring (text | number | date | single_select | multi_select)optional
Der Werttyp des Feldes.
requiredbooleanoptional
Ob das Feld als erforderlich markiert ist. Dies wird von der API nicht erzwungen — es ist nur ein Hinweis für die Benutzeroberfläche.
optionsarray of stringoptional
Die auswählbaren Optionen des Feldes, für Felder des Typs single_select und multi_select. Null für andere Typen.
createdBystringoptional
Wer diese Feld-Definition erstellt hat: "user" oder "agent".
ordernumberoptional
Die Anzeigereihenfolge des Feldes relativ zu anderen Definitionen desselben Entitätstyps, niedrigste zuerst.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
422Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
post/api/v1/custom-fields/definitions
Ihr API-Schlüssel
Anfragetext*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": false,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Ressourcen/Custom Fields/patchBenutzerdefinierte Feld-Definition aktualisieren

Bearbeitet das label, das required-Flag, die options oder die Anzeigereihenfolge einer benutzerdefinierten Feld-Definition. Der Typ und der key des Feldes können nach der Erstellung nicht mehr geändert werden.

Benutzerdefinierte Feld-Definition aktualisieren

patch/api/v1/custom-fields/definitions
custom-fields:write
Anfragetext
definitionIdstringerforderlich
ID der zu aktualisierenden benutzerdefinierten Feld-Definition.
labelstringoptional
Das Anzeigelabel des benutzerdefinierten Feldes.
requiredbooleanoptional
Ob das Feld als erforderlich markiert werden soll. Optional; Standardmäßig false.
optionsarray of stringoptional
Die auswählbaren Optionen des Feldes. Erforderlich (mindestens eine) für Felder des Typs single_select und multi_select; wird für andere Typen ignoriert.
ordernumberoptional
Neue Anzeigereihenfolge für diese Definition relativ zu anderen desselben Entitätstyps.
Antwort
dataobjectoptional
definitionobjectoptional
idstringoptional
Eindeutige Kennung der benutzerdefinierten Feld-Definition.
entityTypestring (location | client)optional
Der Entitätstyp, für den diese Definition gilt: "location" oder "client".
keystringoptional
Unveränderlicher Slug, der dieses Feld identifiziert, abgeleitet von seinem label bei der Erstellung. Verwenden Sie dies, um das Feld beim Setzen von Werten zu referenzieren.
labelstringoptional
Das Anzeigelabel des benutzerdefinierten Feldes.
typestring (text | number | date | single_select | multi_select)optional
Der Werttyp des Feldes.
requiredbooleanoptional
Ob das Feld als erforderlich markiert ist. Dies wird von der API nicht erzwungen — es ist nur ein Hinweis für die Benutzeroberfläche.
optionsarray of stringoptional
Die auswählbaren Optionen des Feldes, für Felder des Typs single_select und multi_select. Null für andere Typen.
createdBystringoptional
Wer diese Feld-Definition erstellt hat: "user" oder "agent".
ordernumberoptional
Die Anzeigereihenfolge des Feldes relativ zu anderen Definitionen desselben Entitätstyps, niedrigste zuerst.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
404Die Ressource wurde nicht gefunden oder gehört nicht zu Ihrer Agentur.
422Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
patch/api/v1/custom-fields/definitions
Ihr API-Schlüssel
Anfragetext*
{
  "data": {
    "definition": {
      "id": "cm_def_abc123",
      "entityType": "location",
      "key": "parking_notes",
      "label": "Parking notes",
      "type": "text",
      "required": true,
      "options": null,
      "createdBy": "user",
      "order": 0
    }
  }
}
v1Ressourcen/Custom Fields/deleteBenutzerdefinierte Feld-Definition archivieren

Archiviert eine benutzerdefinierte Feld-Definition, sodass sie nicht mehr im Schema erscheint und keine neuen Werte mehr akzeptiert. Bereits unter ihrem key gespeicherte Werte bleiben unberührt. Eine unbekannte oder bereits archivierte definitionId führt zu keiner Aktion (kein Fehler).

Benutzerdefinierte Feld-Definition archivieren

delete/api/v1/custom-fields/definitions
custom-fields:write
Query-Parameter
definitionIdstringerforderlich
ID der zu archivierenden benutzerdefinierten Feld-Definition.
Antwort
dataobjectoptional
archivedbooleanoptional
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
delete/api/v1/custom-fields/definitions
Ihr API-Schlüssel
definitionId *
{
  "data": {
    "archived": true
  }
}
v1Ressourcen/Custom Fields/getBenutzerdefinierte Feldwerte einer Entität abrufen

Liefert die für einen Standort oder Kunden gespeicherten benutzerdefinierten Feldwerte, indiziert nach Feld-Key.

Benutzerdefinierte Feldwerte einer Entität abrufen

get/api/v1/custom-fields/values
custom-fields:read
Query-Parameter
entityTypestring (location | client)erforderlich
Der Typ der Entität: "location" oder "client".
entityIdstringerforderlich
ID des Standorts oder Kunden, für den Werte gelesen werden sollen.
Antwort
dataobjectoptional
valuesobjectoptional
Die benutzerdefinierten Feldwerte der Entität, indiziert nach Feld-Key. Ein Wert ist eine Zeichenfolge, eine Zahl, ein Array von Zeichenfolgen (bei multi_select) oder nicht vorhanden, wenn nicht gesetzt.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
404Die Ressource wurde nicht gefunden oder gehört nicht zu Ihrer Agentur.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
get/api/v1/custom-fields/values
Ihr API-Schlüssel
entityType *
entityId *
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}
v1Ressourcen/Custom Fields/putBenutzerdefinierten Feldwert setzen

Setzt einen benutzerdefinierten Feldwert auf einem Standort oder Kunden. Übergeben Sie null (oder einen leeren Wert), um das Feld zu leeren. Der Wert wird gegen die Definition des Feldes validiert — bei einem select-Feld muss der Wert beispielsweise eine seiner definierten Optionen sein.

Benutzerdefinierten Feldwert setzen

put/api/v1/custom-fields/values
custom-fields:write
Anfragetext
entityTypestring (location | client)erforderlich
Der Entitätstyp, für den dieses Feld gilt: "location" oder "client".
entityIdstringerforderlich
ID des Standorts oder Kunden, auf dem der Wert gesetzt werden soll.
keystringerforderlich
Key der zu setzenden benutzerdefinierten Feld-Definition, wie in ihrer key-Eigenschaft zurückgegeben.
valueobjecterforderlich
Der zu speichernde Wert. Muss im Anfragetext vorhanden sein, kann aber null oder leer sein, um das Feld zu leeren. Wird gegen den Typ und die Optionen des Feldes validiert.
Antwort
dataobjectoptional
valuesobjectoptional
Die benutzerdefinierten Feldwerte der Entität, indiziert nach Feld-Key. Ein Wert ist eine Zeichenfolge, eine Zahl, ein Array von Zeichenfolgen (bei multi_select) oder nicht vorhanden, wenn nicht gesetzt.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
404Die Ressource wurde nicht gefunden oder gehört nicht zu Ihrer Agentur.
422Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
put/api/v1/custom-fields/values
Ihr API-Schlüssel
Anfragetext*
{
  "data": {
    "values": {
      "parking_notes": "Free lot behind the building."
    }
  }
}