Accept Collaboration Codes

Purpose

Accepting collaboration codes addresses the need to programmatically join shared surveys on Qualtrics without manual intervention. When a survey owner shares a survey via a collaboration code, the recipient typically must enter this code through the Qualtrics web interface to gain access. This subtopic automates that acceptance process, enabling bulk or automated joining of shared surveys as part of broader collaboration management workflows.

Functionality

The core functionality centers around the `enter_collaboration_code` method, which submits a collaboration code to Qualtrics’ collaboration API endpoint. This process involves:

• Constructing an HTTP POST request with the collaboration token embedded in a JSON payload.

• Adding appropriate headers, such as content type and authentication tokens, to mimic a legitimate browser/API client request.

• Sending the request using an authenticated session previously established via the login workflow.

• Receiving and returning the server’s response, which indicates whether the collaboration code was successfully accepted.

This method abstracts away the complexity of direct web UI interaction, relying instead on API communication facilitated by session cookies and headers synced from the Selenium-driven login.

Key Method Snippet

def enter_collaboration_code(self, code: str) -> dict[str, str]:
    url = f'https://{self.subdomain}.qualtrics.com/survey-collaboration/v1/invitations/accept'
    payload = f'{{"token":"{code}"}}'
    headers = self._generate_qualtrics_headers(content_type='application/json; charset=UTF-8')
    resp = self.session.post(url, headers=headers, data=payload)
    return resp.text

• The payload contains the collaboration token.

• Headers are generated to include authentication tokens (x-xsrf-token) and mimic browser requests.

• The authenticated requests.Session ensures the server recognizes the user context.

Integration with Parent Topic and Other Subtopics

This subtopic complements the parent topic **Survey Collaboration Management** by automating the acceptance side of collaboration invitations, whereas the sibling subtopic **Add Collaborators** automates the sending side (inviting collaborators). Together, they provide a full programmatic control loop over survey collaboration:

• The Add Collaborators subtopic enables survey owners to share their surveys by adding collaborators with specific permissions.

• The Accept Collaboration Codes subtopic allows recipients to programmatically accept those invitations without manual UI input.

Both rely on the shared foundation of an authenticated session managed by **Session and API Request Management**, which handles cookie and header synchronization post-login. The login sequence ensures that the session is valid to authorize both adding collaborators and accepting codes.

By providing an API-level acceptance mechanism, this subtopic removes the need for manual entry of collaboration codes, enabling automation scripts to onboard multiple shared surveys efficiently.

Diagram

sequenceDiagram
    participant UserScript as Automation Script
    participant Client as CollaborationClient
    participant QualtricsAPI as Qualtrics Collaboration API

    UserScript->>Client: enter_collaboration_code(code)
    Client->>QualtricsAPI: POST /invitations/accept\nPayload: {"token": code}\nHeaders with auth tokens
    QualtricsAPI-->>Client: Response (success/failure)
    Client-->>UserScript: Return response text

This sequence diagram illustrates the process flow of submitting a collaboration code through the API client, showing the interaction between the automation script, the client class, and the Qualtrics API endpoint.