POST `/experience-connections`

Create a new Experience Connection

Creates a new Experience Connection record in the specified state (INACTIVE or ACTIVE).

The tn query parameter is required to resolve the Alianza account when the authenticated client belongs to more than one account. The resolved accountId is returned in the response and should be used for subsequent operations.

Design note: tn is a query parameter (rather than a body field) because it is used for account resolution, not as a property of the Experience Connection entity itself. See TDD for rationale.

Spec gap. A connection can be created directly in ACTIVE, but this guide treats activation as a separate step. The spec does not say whether create-as-ACTIVE and create-then-PUT-to-ACTIVE have identical side effects. Use the two-step flow until Alianza confirms equivalence.

Gap ID db519f112389

Authentication

OAuth 2.0. Required scope(s): experience-connections:manage.

Request

Path parameters

None.

Query parameters

Name	Type	Required	Description
`tn`	string (E.164)	yes	Phone number in E.164 format used to resolve the correct Alianza account. Mandatory query parameter. Used to disambiguate when the authenticated user belongs to more than one account.

Headers

None.

Spec gap. The spec does not document what happens when tn resolves to no account, or to multiple accounts the client can see. Confirm the failure modes with Alianza for multi-tenant integrations; assume 404 / 409 respectively until documented.

Gap ID 0020e2b9b0ca

Body

Required: yes

Content-Type: application/json

Schema: ExperienceConnection

Example:

{
  "experienceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "state": "INACTIVE"
}

Responses

`201` — Experience Connection created successfully. The response always includes the resolved `accountId`, which should be used for subsequent operations such as `experience-assignments`.

Content-Type: application/json

Schema: ExperienceConnection

Example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "accountName": "Acme Communications",
  "experienceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "state": "INACTIVE"
}

`400` — Bad Request - A query parameter was set with an invalid value

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "tn must be in E.164 format (e.g., +14155551234)",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`401` — Unauthorized - Missing or expired access token. Obtain a new token and retry.

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Access token is missing or has expired",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`403` — Forbidden - The authenticated user does not have authorization to create an Experience Connection

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated user does not have authorization to create an Experience Connection",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`409` — Conflict - Experience Connection already exists for this account and Experience

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Conflict",
  "status": 409,
  "detail": "An Experience Connection already exists for this account and Experience",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`422` — Unprocessable Entity - Invalid data (missing required fields, invalid values)

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "experienceId is required",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

Other notes

On 409, look up the existing connection rather than failing. A conflict means this account already has a connection to your Experience. Resolve it with:

GET {baseUrl}/experience-connections?tn=+14155551234&experienceId=<your-experience-id>

Then reuse the returned id. The same lookup resolves an ambiguous 5xx — it tells you whether the create landed.

Spec gap. The spec does not document Idempotency-Key support, so a retry after a 5xx may create a second connection. (accountId + experienceId) is the de-facto dedup key and the lookup above is the documented recovery, but that is a read-after-write check, not an idempotency guarantee. Treat this call as non-idempotent.

Gap ID 15659347b1ca

Errors

This operation may return:

400 — Bad Request - A query parameter was set with an invalid value
401 — Unauthorized - Missing or expired access token. Obtain a new token and retry.
403 — Forbidden - The authenticated user does not have authorization to create an Experience Connection
409 — Conflict - Experience Connection already exists for this account and Experience
422 — Unprocessable Entity - Invalid data (missing required fields, invalid values)

See Errors reference for the full catalogue.

Schema: ExperienceConnection
Schema: ProblemDetails