> For the complete documentation index, see [llms.txt](https://tsanet.gitbook.io/connect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tsanet.gitbook.io/connect/api-reference/readme.md).

# TSANet Connect Integrations

TSANet Connect API can be used to create system connectors or implement custom integrations.

### TSANet Apps

TSANet has created connectors for the following systems. These can be downloaded and installed by system administrators.

**Salesforce**: See the [Salesforce App in Documentation](/connect/documentation/salesforce-app/demo.md)

**Microsoft Dynamics:** See [Microsoft Dynamics App in Documentation](/connect/documentation/dynamics-app/demo.md)

**Service Now:** See [Service Now App in Documentation](/connect/documentation/servicenow-app/early-access.md)

**Zendesk**: See[ Zendesk App in Documentation](/connect/documentation/zendesk-app/demo.md)

### Give TSANet Feedback on Future Apps

TSANet is gathering input from Members on the systems they use. This feedback will be used to organize additional system Apps.

[**Take the Survey**](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=M1C2WgDChU-a97fbEj6OqM9NpgFekQJPnv4B7IMqaKhUQ0NUWklaUlNTQkI2NEtHRjk5VTMxOEhRNy4u)

### Connect SDK

Build Apps and custom integrations with the TSANet Connect SDK <https://github.com/tsanetgit/Connect_SDK>

### Partner and Member Integrations

Developers use the TSANet Connect API and Connect SDK to implement system Apps or custom integrations. Contact TSANet at <membership@tsanet.org> for access to the Beta and Production environments. The base URL for each environment is:

* Beta: [https://connect2.tsanet.net](https://connect2.tsanet.net/)
* Production: [https://connect2.tsanet.org](https://connect2.tsanet.org/v1)

### Terminology

**Collaboration request** is the term the API uses for the record created when one member asks another for help. Every endpoint path, webhook event type, and payload field refers to that record.

You will also see **case** in the API, in two different senses. Keeping them apart avoids a common integration bug:

| Term                                                                                           | Refers to                                                                             |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `caseNotes`, `caseResponses`, and the Case Notes / Case Responses / Case Attachments groupings | Child records of the **TSANet collaboration request**                                 |
| `internalCaseNumber`, `submitterCaseNumber`, `receiverCaseNumber`                              | The ticket number in **your own** system, or your partner's — not a TSANet identifier |

The TSANet record is always addressed by its `token`, never by a case number.

### Authentication

Two methods are supported. Both are documented in full on the [Identity](/connect/api-reference/identity.md) reference page.

* **Bearer JWT** — obtain a token with `POST /v1/login`, then send it as `Authorization: Bearer <token>`.
* **Azure AD client credentials (M2M)** — for server-to-server integrations. Your service principal must be provisioned by TSANet before tokens are accepted; contact TSANet with your service principal OID.

### Webhooks

Webhooks remove the need for frequent polling.

* **V2** (`POST /v2/webhooks`) delivers all five event types as CloudEvents 1.0 payloads. Use this for new integrations.
* **V1** (`POST /v1/webhooks`) is a frozen legacy format covering only `collaboration-request.created` and `note.created`. It is deprecated and scheduled for removal after 2027-01-01.

Every delivery is signed with HMAC-SHA256 in the `X-Hub-Signature-256` header. See [Webhook Events](/connect/api-reference/webhook-events.md) for payload schemas, delivery headers, signature verification, and retry behaviour.

### Event delivery

Collaboration request lifecycle events — created, closed, note added, response created, and response updated — are published internally as CloudEvents 1.0 and fanned out to each integration channel separately.

Each channel consumes its own copy, so delivery is isolated: a failure or backlog affecting one integration does not delay or block another. Webhooks are the channel available to members.

### Endpoint summary

Full request and response schemas for every endpoint are generated from the OpenAPI specification and published on the reference pages listed in the sidebar.

**Outbound process**

| Endpoint                                          | Use                                         |
| ------------------------------------------------- | ------------------------------------------- |
| `POST /v1/login`                                  | Log in and obtain a bearer token            |
| `GET /v1/partners/{searchTerm}`                   | Search for a partner company or department  |
| `GET /v1/partners/search`                         | Natural-language partner search             |
| `GET /v1/forms/company/{companyId}`               | Get the collaboration form for a company    |
| `GET /v1/forms/department/{departmentId}`         | Get the collaboration form for a department |
| `POST /v1/collaboration-requests`                 | Create a collaboration request              |
| `POST /v1/collaboration-requests/{token}/closure` | Close a request (submitter only)            |

**Inbound process**

| Endpoint                                                       | Use                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------- |
| `GET /v2/collaboration-requests`                               | List requests, paginated                                |
| `GET /v2/collaboration-requests/list`                          | List requests, with date filters                        |
| `GET /v1/collaboration-requests/{token}`                       | Get a single request by token                           |
| `POST /v1/collaboration-requests/{token}/approval`             | Approve a request                                       |
| `PATCH /v1/collaboration-requests/{token}/approval`            | Update an approval (for example, reassign the engineer) |
| `POST /v1/collaboration-requests/{token}/information-request`  | Request further information before deciding             |
| `POST /v1/collaboration-requests/{token}/information-response` | Respond to an information request                       |
| `POST /v1/collaboration-requests/{token}/rejection`            | Reject a request                                        |

**Notes and attachments**

| Endpoint                                                          | Use                                                                                                        |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `POST /v1/collaboration-requests/{token}/notes`                   | Add a note to a collaboration request                                                                      |
| `GET /v1/collaboration-requests/{token}/notes`                    | Get notes, with optional date filters                                                                      |
| `GET /v1/collaboration-requests/{token}/attachments/config`       | Get a member's attachment configuration                                                                    |
| `PUT /v1/collaboration-requests/{token}/attachments/config/https` | Update HTTPS attachment configuration — how a member receives a file, for example into their AWS S3 bucket |
| `POST /v1/collaboration-requests/{token}/attachments`             | Forward an attachment directly to the partner's file storage                                               |

{% hint style="warning" %}
`GET /v1/collaboration-requests` is deprecated and will be removed after 2027-01-01. Use `GET /v2/collaboration-requests` instead.
{% endhint %}

***

The [Integration Guide](/connect/api-reference/integration-guide.md) provides an overview of the TSANet Connect API and examples of both System Connector and a Custom integration.