From 51b58be079e0c2888982beff033833e538190845 Mon Sep 17 00:00:00 2001 From: Anshuman Pandey <54475686+pandeymangg@users.noreply.github.com> Date: Tue, 24 Jun 2025 14:14:34 +0530 Subject: [PATCH] docs: fixes the bulk contact upload api docs and adds the email property (#6066) Co-authored-by: Johannes --- apps/web/locales/de-DE.json | 1 - apps/web/locales/en-US.json | 1 - apps/web/locales/fr-FR.json | 1 - apps/web/locales/pt-BR.json | 1 - apps/web/locales/pt-PT.json | 1 - apps/web/locales/zh-Hant-TW.json | 1 - .../management/contacts/bulk/lib/openapi.ts | 61 ++++++++++++++++++- docs/api-v2-reference/openapi.yml | 36 ++++++++++- 8 files changed, 93 insertions(+), 10 deletions(-) diff --git a/apps/web/locales/de-DE.json b/apps/web/locales/de-DE.json index ae3fd7626d..da51100a38 100644 --- a/apps/web/locales/de-DE.json +++ b/apps/web/locales/de-DE.json @@ -309,7 +309,6 @@ "project_not_found": "Projekt nicht gefunden", "project_permission_not_found": "Projekt-Berechtigung nicht gefunden", "projects": "Projekte", - "projects_limit_reached": "Projektlimit erreicht", "question": "Frage", "question_id": "Frage-ID", "questions": "Fragen", diff --git a/apps/web/locales/en-US.json b/apps/web/locales/en-US.json index a638327369..132d68b508 100644 --- a/apps/web/locales/en-US.json +++ b/apps/web/locales/en-US.json @@ -309,7 +309,6 @@ "project_not_found": "Project not found", "project_permission_not_found": "Project permission not found", "projects": "Projects", - "projects_limit_reached": "Projects limit reached", "question": "Question", "question_id": "Question ID", "questions": "Questions", diff --git a/apps/web/locales/fr-FR.json b/apps/web/locales/fr-FR.json index c4ceb082a7..109bd635a1 100644 --- a/apps/web/locales/fr-FR.json +++ b/apps/web/locales/fr-FR.json @@ -309,7 +309,6 @@ "project_not_found": "Projet non trouvé", "project_permission_not_found": "Autorisation de projet non trouvée", "projects": "Projets", - "projects_limit_reached": "Limite de projets atteinte", "question": "Question", "question_id": "ID de la question", "questions": "Questions", diff --git a/apps/web/locales/pt-BR.json b/apps/web/locales/pt-BR.json index 1cf216db52..cd8a73088a 100644 --- a/apps/web/locales/pt-BR.json +++ b/apps/web/locales/pt-BR.json @@ -309,7 +309,6 @@ "project_not_found": "Projeto não encontrado", "project_permission_not_found": "Permissão do projeto não encontrada", "projects": "Projetos", - "projects_limit_reached": "Limites de projetos atingidos", "question": "Pergunta", "question_id": "ID da Pergunta", "questions": "Perguntas", diff --git a/apps/web/locales/pt-PT.json b/apps/web/locales/pt-PT.json index ed0fdc85b7..3718817475 100644 --- a/apps/web/locales/pt-PT.json +++ b/apps/web/locales/pt-PT.json @@ -309,7 +309,6 @@ "project_not_found": "Projeto não encontrado", "project_permission_not_found": "Permissão do projeto não encontrada", "projects": "Projetos", - "projects_limit_reached": "Limite de projetos atingido", "question": "Pergunta", "question_id": "ID da pergunta", "questions": "Perguntas", diff --git a/apps/web/locales/zh-Hant-TW.json b/apps/web/locales/zh-Hant-TW.json index 7946395286..ac2ad2086f 100644 --- a/apps/web/locales/zh-Hant-TW.json +++ b/apps/web/locales/zh-Hant-TW.json @@ -309,7 +309,6 @@ "project_not_found": "找不到專案", "project_permission_not_found": "找不到專案權限", "projects": "專案", - "projects_limit_reached": "已達到專案上限", "question": "問題", "question_id": "問題 ID", "questions": "問題", diff --git a/apps/web/modules/ee/contacts/api/v2/management/contacts/bulk/lib/openapi.ts b/apps/web/modules/ee/contacts/api/v2/management/contacts/bulk/lib/openapi.ts index 0c6f06915c..bbcfec3bf2 100644 --- a/apps/web/modules/ee/contacts/api/v2/management/contacts/bulk/lib/openapi.ts +++ b/apps/web/modules/ee/contacts/api/v2/management/contacts/bulk/lib/openapi.ts @@ -6,13 +6,70 @@ import { ZodOpenApiOperationObject, ZodOpenApiPathsObject } from "zod-openapi"; const bulkContactEndpoint: ZodOpenApiOperationObject = { operationId: "uploadBulkContacts", summary: "Upload Bulk Contacts", - description: "Uploads contacts in bulk", + description: + "Uploads contacts in bulk. Each contact in the payload must have an 'email' attribute present in their attributes array. The email attribute is mandatory and must be a valid email format. Without a valid email, the contact will be skipped during processing.", requestBody: { required: true, - description: "The contacts to upload", + description: + "The contacts to upload. Each contact must include an 'email' attribute in their attributes array. The email is used as the unique identifier for the contact.", content: { "application/json": { schema: ZContactBulkUploadRequest, + example: { + environmentId: "env_01h2xce9q8p3w4x5y6z7a8b9c0", + contacts: [ + { + attributes: [ + { + attributeKey: { + key: "email", + name: "Email Address", + }, + value: "john.doe@example.com", + }, + { + attributeKey: { + key: "firstName", + name: "First Name", + }, + value: "John", + }, + { + attributeKey: { + key: "lastName", + name: "Last Name", + }, + value: "Doe", + }, + ], + }, + { + attributes: [ + { + attributeKey: { + key: "email", + name: "Email Address", + }, + value: "jane.smith@example.com", + }, + { + attributeKey: { + key: "firstName", + name: "First Name", + }, + value: "Jane", + }, + { + attributeKey: { + key: "lastName", + name: "Last Name", + }, + value: "Smith", + }, + ], + }, + ], + }, }, }, }, diff --git a/docs/api-v2-reference/openapi.yml b/docs/api-v2-reference/openapi.yml index 00bd8f5465..a8d2c646be 100644 --- a/docs/api-v2-reference/openapi.yml +++ b/docs/api-v2-reference/openapi.yml @@ -1523,12 +1523,15 @@ paths: put: operationId: uploadBulkContacts summary: Upload Bulk Contacts - description: Uploads contacts in bulk + description: Uploads contacts in bulk. Each contact in the payload must have an + 'email' attribute present in their attributes array. The email attribute + is mandatory and must be a valid email format. tags: - Management API > Contacts requestBody: required: true - description: The contacts to upload + description: The contacts to upload. Each contact **must include an 'email' + attribute** in their attributes array. content: application/json: schema: @@ -1567,6 +1570,35 @@ paths: required: - environmentId - contacts + example: + environmentId: env_01h2xce9q8p3w4x5y6z7a8b9c0 + contacts: + - attributes: + - attributeKey: + key: email + name: Email Address + value: john.doe@example.com + - attributeKey: + key: firstName + name: First Name + value: John + - attributeKey: + key: lastName + name: Last Name + value: Doe + - attributes: + - attributeKey: + key: email + name: Email Address + value: jane.smith@example.com + - attributeKey: + key: firstName + name: First Name + value: Jane + - attributeKey: + key: lastName + name: Last Name + value: Smith responses: "200": description: Contacts uploaded successfully.