List guests

Endpoint

GET /organizations/{org_id}/guests

This endpoint retrieves a list of guest users associated with the specified organization.

Request

Replace {org_id} with your Organization ID.

Headers

• Authorization: Bearer {your_access_token}
• Accept: application/json
• X-Tallyfy-Client: APIClient

Query parameters (optional)

• with (string): Include additional data, e.g., stats.
• Pagination parameters (page, per_page) may also be available.

Code samples

Javascript

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';

const queryParams = ''; // Example: Add query params like '?with=stats&page=2'
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/guests${queryParams}`;

const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');

fetch(apiUrl, {
    method: 'GET',
    headers: headers
})
.then(response => {
    return response.json().then(data => { // Attempt to parse JSON regardless of status
        if (!response.ok) {
            console.error("Failed to list guests:", data);
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return data; // Pass successful data along
    });
})
.then(data => {
    console.log('Successfully listed guests:');
    console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
    console.error('Error listing guests:', error.message);
});

Python

import requests
import json
import os

access_token = os.environ.get('TALLYFY_ACCESS_TOKEN', 'YOUR_PERSONAL_ACCESS_TOKEN')
org_id = os.environ.get('TALLYFY_ORG_ID', 'YOUR_ORGANIZATION_ID')
api_url = f'https://go.tallyfy.com/api/organizations/{org_id}/guests'

headers = {
    'Authorization': f'Bearer {access_token}',
    'Accept': 'application/json',
    'X-Tallyfy-Client': 'APIClient'
}

# Optional: Add query parameters
params = {
     'with': 'stats',
     'page': 1,
     'per_page': 50
}

response = None
try:
    response = requests.get(api_url, headers=headers, params=params)
    response.raise_for_status() # Raises HTTPError for bad responses (4xx or 5xx)

    guests_data = response.json()
    print('Successfully listed guests:')
    print(json.dumps(guests_data, indent=4))

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred listing guests: {http_err}")
    if response is not None:
        print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request failed listing guests: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response when listing guests")
    if response is not None:
        print(f"Response Text: {response.text}")
except Exception as err:
     print(f"An unexpected error occurred: {err}")

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.stream.Collectors;

public class ListGuests {
    public static void main(String[] args) {
        String accessToken = System.getenv().getOrDefault("TALLYFY_ACCESS_TOKEN", "YOUR_PERSONAL_ACCESS_TOKEN");
        String orgId = System.getenv().getOrDefault("TALLYFY_ORG_ID", "YOUR_ORGANIZATION_ID");
        String baseUrl = "https://go.tallyfy.com/api/organizations/" + orgId + "/guests";

        // Optional: Add query parameters
        Map<String, String> queryParamsMap = Map.of("with", "stats", "page", "1");
        String queryParamsString = queryParamsMap.entrySet().stream()
            .map(entry -> URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&", "?", ""));

        String apiUrl = baseUrl + (queryParamsMap.isEmpty() ? "" : queryParamsString);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "Bearer " + accessToken)
                .header("Accept", "application/json")
                .header("X-Tallyfy-Client", "APIClient")
                .GET()
                .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 200) {
                System.out.println("Successfully listed guests:");
                System.out.println(response.body());
                // TODO: Consider parsing JSON using Jackson/Gson
            } else {
                System.err.println("Failed to list guests. Status: " + response.statusCode());
                System.err.println("Response Body: " + response.body());
            }
        } catch (IOException | InterruptedException e) {
             System.err.println("Request failed: " + e.getMessage());
             Thread.currentThread().interrupt();
        } catch (Exception e) {
             System.err.println("An unexpected error occurred: " + e.getMessage());
             e.printStackTrace();
        }
    }
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
  "net/url"
  "os"
    "time"
)

func main() {
  accessToken := os.Getenv("TALLYFY_ACCESS_TOKEN")
    if accessToken == "" { accessToken = "YOUR_PERSONAL_ACCESS_TOKEN" }
  orgId := os.Getenv("TALLYFY_ORG_ID")
    if orgId == "" { orgId = "YOUR_ORGANIZATION_ID" }
    baseURL := fmt.Sprintf("https://go.tallyfy.com/api/organizations/%s/guests", orgId)

    // Optional: Add query parameters
    queryParams := url.Values{}
    queryParams.Add("with", "stats")
    queryParams.Add("page", "1")

    apiUrl := baseURL
    if len(queryParams) > 0 {
        apiUrl += "?" + queryParams.Encode()
    }

  client := &http.Client{Timeout: 10 * time.Second}
  req, err := http.NewRequest("GET", apiUrl, nil)
    if err != nil {
    fmt.Printf("Error creating list guests request: %v\n", err)
    return
  }

  req.Header.Set("Authorization", "Bearer "+accessToken)
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-Tallyfy-Client", "APIClient")

  resp, err := client.Do(req)
    if err != nil {
    fmt.Printf("Error executing list guests request: %v\n", err)
    return
  }
  defer resp.Body.Close()

  body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
    fmt.Printf("Error reading list guests response body: %v\n", err)
    return
  }

  if resp.StatusCode != http.StatusOK {
    fmt.Printf("Failed to list guests. Status: %d\nBody: %s\n", resp.StatusCode, string(body))
    return
  }

  fmt.Println("Successfully listed guests:")
    // Pretty print JSON response
    var prettyJSON bytes.Buffer
    if err := json.Indent(&prettyJSON, body, "", "  "); err == nil {
        fmt.Println(prettyJSON.String())
    } else {
      fmt.Println(string(body))
    }
  // TODO: Unmarshal JSON into a slice of guest structs if needed
}

C++

#include <iostream>
#include <string>
#include <cpprest/http_client.h>
#include <cpprest/json.h>

using namespace web;
using namespace web::http;
using namespace web::http::client;
using namespace web::json;

pplx::task<void> ListTallyfyGuests()
{
    utility::string_t accessToken = U("YOUR_PERSONAL_ACCESS_TOKEN");
    utility::string_t orgId = U("YOUR_ORGANIZATION_ID");

    uri_builder builder(U("https://go.tallyfy.com/api/organizations/"));
    builder.append_path(orgId);
    builder.append_path(U("guests"));
    builder.append_query(U("with"), U("stats")); // Example query parameter
    // builder.append_query(U("page"), 1); // Example pagination
    utility::string_t apiUrl = builder.to_string();

    http_client client(apiUrl);
    http_request request(methods::GET);

    request.headers().add(U("Authorization"), U("Bearer ") + accessToken);
    request.headers().add(U("Accept"), U("application/json"));
    request.headers().add(U("X-Tallyfy-Client"), U("APIClient"));

    return client.request(request).then([](http_response response)
    {
        return response.extract_json().then([response](pplx::task<value> task)
        {
            try {
                value const & body = task.get();
                if (response.status_code() == status_codes::OK) {
                    std::wcout << L"Successfully listed guests:\n" << body.serialize() << std::endl;
                    // Access data: body[U("data")].as_array()
                } else {
                    std::wcerr << L"Failed to list guests. Status: " << response.status_code() << L"\nResponse: " << body.serialize() << std::endl;
                }
            } catch (const http_exception& e) {
                 std::wcerr << L"HTTP exception during list guests: " << e.what() << std::endl;
            } catch (const std::exception& e) {
                std::wcerr << L"Exception during list guests response handling: " << e.what() << std::endl;
            }
        });
    });
}

int main() {
    try {
        ListTallyfyGuests().wait();
    } catch (const std::exception &e) {
        std::cerr << "Error in main: " << e.what() << std::endl;
    }
    return 0;
}
// Requires C++ REST SDK (Casablanca)

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using System.Text.Json;
using System.Web; // For HttpUtility

public class TallyfyGuestLister
{
    private static readonly HttpClient client = new HttpClient();

    public static async Task ListGuestsAsync()
    {
        var accessToken = Environment.GetEnvironmentVariable("TALLYFY_ACCESS_TOKEN") ?? "YOUR_PERSONAL_ACCESS_TOKEN";
        var orgId = Environment.GetEnvironmentVariable("TALLYFY_ORG_ID") ?? "YOUR_ORGANIZATION_ID";

        // Build URL with query parameters
        var query = HttpUtility.ParseQueryString(string.Empty);
        query["with"] = "stats"; // Example
        // query["page"] = "1";
        string queryString = query.ToString();
        var apiUrl = $"https://go.tallyfy.com/api/organizations/{orgId}/guests?{queryString}";

        try
        {
            using var request = new HttpRequestMessage(HttpMethod.Get, apiUrl);
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            request.Headers.Add("X-Tallyfy-Client", "APIClient");

            HttpResponseMessage response = await client.SendAsync(request);
            string responseBody = await response.Content.ReadAsStringAsync();

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Successfully listed guests:");
                // Pretty print JSON
                try {
                    using var doc = JsonDocument.Parse(responseBody);
                    Console.WriteLine(JsonSerializer.Serialize(doc.RootElement, new JsonSerializerOptions { WriteIndented = true }));
                } catch (JsonException) {
                    Console.WriteLine(responseBody); // Print raw if not valid JSON
                }
            }
            else
            {
                Console.WriteLine($"Failed to list guests. Status: {response.StatusCode}");
                Console.WriteLine($"Response: {responseBody}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request Exception listing guests: {e.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"An unexpected error occurred: {ex.Message}");
        }
    }

    // Example Usage:
    // static async Task Main(string[] args)
    // {
    //     await ListGuestsAsync();
    // }
}

Response

A successful request returns a 200 OK status code and a JSON object containing a data array. Each element represents a guest associated with the organization.

{
  "data": [
    {
      "id": "guest_code_abc123", // Unique guest code/identifier
      "email": "guest.user@external.com",
      "last_accessed_at": "2024-05-15T10:00:00Z",
      "last_known_ip": "192.0.2.1",
      "last_known_country": "US",
      "details": {
        "first_name": "External",
        "last_name": "Collaborator",
        "status": "active", // Can be active, disabled
        "phone_1": null,
        "company_name": "External Inc.",
        "timezone": "UTC",
        "disabled_on": null,
        "disabled_by": null,
        // ... other detail fields ...
      },
       // Included if requested with 'with=stats'
      "stats": {
          "active_tasks": 2,
          "completed_tasks": 5
          // ... other stats ...
      }
    },
    {
       "id": "guest_code_def456",
       "email": "another.guest@domain.com",
       // ... details ...
    }
  ]
  // Potential meta object for pagination if supported
}

---

Related articles

Guests > Get guest

A GET endpoint that retrieves specific guest user details within an organization using their email address while supporting multiple programming languages and optional query parameters for additional data inclusion.

Members > List members

A comprehensive API endpoint documentation for retrieving organization members through various programming languages including authentication headers optional query parameters and response structure with sample code snippets.

Guests > Delete guest

A DELETE endpoint that removes guest users from an organization by their email address and returns either a success status code or guest record details upon completion.

Guests > Create guest

The POST endpoint creates guest users in an organization by accepting JSON data with required email and optional fields like name and company details while returning the newly created guest’s information upon success.