POST /experience/connections

Create a new Experience Connection

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

The telephoneNumber 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: telephoneNumber 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.

Authentication

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

Request

Path parameters

None.

Query parameters

Name Type Required Description
telephoneNumber string (E.164) yes Phone number in E.164 format used to resolve the correct Alianza account. Used to disambiguate when the authenticated user belongs to more than one account. Supersedes the deprecated tn.
tn string (E.164) no Deprecated — use telephoneNumber instead. Same purpose, retained for existing integrations.

Headers

None.

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",
  "updatedAt": "2026-05-01T12:00:00Z"
}

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

Content-Type: application/problem+json

Schema: ProblemDetails

Example — Neither parameter supplied:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "one of telephoneNumber or tn is required",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

Example — Supplied number is not E.164:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "telephoneNumber must be a valid E.164 phone number (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?telephoneNumber=+14155551234&experienceId=<your-experience-id>

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

Errors

This operation may return:

  • 400 — Bad Request
  • 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.