> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tangoanalytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mac comment inbound

# Tango MAC Comment Inbound API

> Generated from `Tango MAC Comment Inbound API Integration Design Specification V0.8.docx` in SharePoint folder `03 Space Integrations`.
> OAS spec: [`mac-comment-inbound.yaml`](./mac-comment-inbound.yaml)

## Overview

Async REST API: client adds comments (Internal Notes / External Notes) to MAC requests in Tango. Create-only by default; updates existing comments when `tango_comment_id` is provided. Cannot delete comments.

**Owner:** Tango Analytics
**Spec version:** 0.8
**Status:** Draft (auto-generated — needs review)

## Endpoints

| Method | Path | Summary |
| - | - | - |
| PUT | `/v1/common/batch/comments` | Submit MAC comments (async). |
| GET | `/v1/batch/status?gu_id=...` | Poll status. |

## Authentication

Headers `x-client` + `x-api-key`.

## Integration logic

* New comment → no `tango_comment_id`.
* Update existing comment → include `tango_comment_id`.
* Comments cannot be deleted via this integration.

## Data model (required ✅)

| Field | Type | Req | Notes |
| - | - | - | - |
| `entity_number` | VARCHAR | one-of | MAC Number; one of entity\_number / ext\_entity\_number required |
| `ext_entity_number` | VARCHAR | ✅ | Client Integration ID |
| `tango_comment_id` | NUMBER | – | Provide to update an existing comment |
| `comments_category` | VARCHAR | – | Sample: `Notes` |
| `comment_type` | VARCHAR | – | Lookup |
| `subject` | VARCHAR | – | |
| `comments` | VARCHAR | ✅ | The comment body |
| `entity_type` | VARCHAR | ✅ | `MACINTERNAL` / `MACEXTERNAL` |

## Validations

1. `comments` NULL → `Comments is missing`
2. `ext_entity_number` NULL → `Client Integration Id is missing`

## Open Questions / Assumptions

* [ ] **`entity_type` casing** — source describes as "MAC Internal or MAC External" but sample value is `MACEXTERNAL` (single token, all caps). Schema uses the single-token form.
* [ ] **`comment_type` lookup values** are `<TBD>`.
* [ ] **`record_key` type** in error response sample shows both unquoted number (`027533`) and quoted string (`"027369"`); modelled as oneOf.

## Changelog (compressed)

| Ver | Date | Description | Author |
| - | - | - | - |
| 0.1–0.7 | 2022-2023 | (see source doc) | Various |
| 0.8 | 04/22/2026 | Updated API architecture diagram | Alpna Bansal |