Working with the Connect API

The scope that looks right and isn't

Use the bare audience GUID plus /.default. The api:// prefix fails with AADSTS500011 because the app registration publishes no Application ID URI. This reads like a typo in the working version, and it is not.

Worked through on Zendesk → Authentication

Provisioning is a prerequisite, not a formality

An app-only token is accepted only once TSANet has provisioned your service principal's object ID — that provisioning is also what maps your tokens to your member company. Ask before you start building, not when auth fails.

Store secrets verbatim

Client secrets are random strings that can begin with punctuation. Trimming or "cleaning" the value breaks authentication with AADSTS7000215.

Tokens renew themselves; the credential behind them does not

It is easy to read "no static token to refresh" as "nothing to maintain". The token re-mints automatically — the client secret it re-mints from has its own expiry, and rotating it before that date is the member's responsibility. When it lapses, every call stops at once, and it presents as a sudden total auth failure rather than a gradual degradation.

Confirm the expiry date and the rotation process with TSANet at onboarding, put the date somewhere that will actually alert you, and rehearse the rotation before you need it. This is the single most predictable outage available to an otherwise healthy integration.

Fetch the form fresh, every time

Partners change their own forms. The documentId you must submit with a case comes from that fetch, so a cached form means a stale documentId and a rejected submission. Cache it for the duration of one submission flow, never longer.

SELECT options are newline-delimited

The options string on a custom field separates choices with CRLF, not commas, and the structured selections[] array is frequently empty. Splitting on commas collapses every choice into one option — a bug that renders perfectly and is wrong. Prefer selections[].value, fall back to splitting on newlines, then commas.

Worked through on Zendesk → Platform gotchas

adminNote is HTML to render, not to strip

The form's "Partner instructions" field is authored HTML with links. Escaping shows raw tags; stripping loses the links. Sanitize against a tag allowlist and render it. This is the one field that is the exception to stripping HTML.

What you send is not what you read back

The write model and the read model use different names for the same fields. You POST problemSummary and problemDescription; you GET summary and description. Your own case number goes out as internalCaseNumber and comes back as submitterCaseNumber or receiverCaseNumber depending on which side you are. Contact details go out under submitterContactDetails and come back flattened onto the case.

Nothing is wrong when this happens — it is one case with two schemas. But a mapping layer written from the POST body alone will silently fail to read anything back.

Verified against CollaborationRequestDTO (write) and CollaborationRequestStatusDTO (read) — see TSANET-2026-001

Save the token immediately — it is the primary key

A numeric id exists, but every path uses token. Persist it durably at the moment of creation, before anything else can fail. An integration that creates a case and then loses the token has orphaned it: the partner has a case nobody on your side can find.

There is no idempotency key on create

A second POST with the same internalCaseNumber creates a second case. Since a timeout or a 5xx leaves you unable to tell whether the first one landed, a naive retry is how partners receive duplicate requests. Treat ambiguous outcomes as ambiguous: park the flow, reconcile by lookup, and only then re-arm the retry.

The full outcome taxonomy is on Fin / Intercom → Submit outcomes

responded gates the SLA, not the status name

The SLA tracks the initial acknowledgment deadline only. Once responded is true, the platform stops tracking — so a countdown shown on an ACCEPTED case is a deadline nobody is measuring. Gate every SLA display and breach check on responded === false.

Only the submitting company can close

Calling /closure as the receiver returns an error. Show the action only on outbound cases. And note the asymmetry with acceptance: a case cannot be closed while still OPEN by either party, so every case that ends cleanly must pass through acceptance first.

Probed and diagrammed on Fin / Intercom → lifecycle

Cases auto-close after 30 days of inactivity

The one closure that does not come from the submitter. Reporting that assumes a manual close is wrong on every connector, and an integration that mirrors status should expect a CLOSED it never sent. It sits in tension with the probed rule that an OPEN case cannot be closed by either party; whether the inactivity close applies to cases still OPEN is unverified.

Documented on the Salesforce and Dynamics connector pages — not probed here

Approval is a commitment, not a routing step

Accepting tells the partner an engineer is engaged, and it satisfies the SLA at the same moment. Those pull in opposite directions, which is why automating acceptance is a real decision rather than a convenience: a rule that accepts something nobody will work stops the clock and leaves the partner waiting — worse for them than an honest breach, because a breach is visible.

Four shipping postures compared in Deciding what to accept automatically

Never copy summary into description

summary is required and capped at 500 characters; description is optional and capped at 5,000. The web UI renders both as separate labelled sections, so posting identical values displays the text twice. It looks like a duplication bug and it is intentional rendering. Present two fields — Subject and Details — and send description only when it has content.

Note content comes back as HTML

Both summary and description return with markup. Strip to plain text before display in a non-HTML surface. The process form's adminNote is the exception — that one renders.

Attachments are a two-party setup, and the platform stores nothing

A forward is delivered straight to the other party's registered endpoint — there is no attachment store, and no endpoint that lists files on a case. Delivery also fans out to your own registered endpoint, so an integration that only ever sends still wants one: without it every forward reports submitterStatus: CONFIG_MISSING and you keep no copy of what you sent.

Configuration is per case and readable before you act: GET …/attachments/config returns the submitter and receiver configurations, POST …/attachments/config/https/analyze proposes a normalized configuration without saving it, and PUT …/attachments/config/https registers one. Check it before offering an attachment action rather than discovering CONFIG_MISSING afterwards. Delivery attempts are not specified here: the file-sharing topic documents one attempt per destination with no automatic retry, which is documented rather than probed — so build the receiver so that a 2xx means durably stored.

Two things the platform will not do for you: it creates no case note announcing the file, and it keeps no history. Both are yours to build.

Full model in TSANET-2026-002

The reference shows description in the wrong place

On the forward call, the GitBook reference currently shows description as a query parameter. The specification puts it in the multipart/form-data body — a required field, capped at 500 characters, alongside files. A request built from the reference omits a required form field. Send it in the form.

Verified against openapi.yaml — POST /v1/collaboration-requests/{token}/attachments, requestBody

Payloads are thin — the fetch is what establishes truth

An event names a token and little else. Do not try to reconstruct state from the event body: acknowledge fast, then fetch the case and act on what you read. This also makes redelivery harmless, provided your writes are keyed on the token.

Delivery is at-least-once, so build for duplicates

Your endpoint may receive the same event more than once, and concurrent delivery workers mean events can arrive out of order. Deduplicate on the CloudEvent id (v2), or on requestToken + eventType + timestamp (v1). The pull-on-notify pattern is naturally tolerant of both, which is another reason to fetch rather than trust the payload.

4xx is permanent — it is not a "try me later"

A 4xx response is treated as a permanent failure and never retried; only 5xx responses and network timeouts trigger redelivery. So if you reject a payload you cannot route, returning 400 discards the event for good. Acknowledge with a 200 and handle the problem on your side, then let reconciliation catch anything genuinely lost.

Recovery design on Fin / Intercom → Recovery

You have 30 seconds to respond

Past that the delivery is treated as failed. Acknowledge immediately and do the real work asynchronously — every connector on this hub fast-acks and hands off to a queue for exactly this reason.